• Home
  • Fresh Content
  • Courses
  • Resources
  • Podcast
  • Talks
  • Publications
  • Sponsorship
  • Testimonials
  • Contact
  • Menu

Jon Krohn

  • Home
  • Fresh Content
  • Courses
  • Resources
  • Podcast
  • Talks
  • Publications
  • Sponsorship
  • Testimonials
  • Contact
Jon Krohn

CLAUDE.md, AGENTS.md, Skills, Hooks and Subagents: A Field Guide to Steering AI Agents

Added on August 31, 2026 by Jon Krohn.

Ever written careful instructions for an A.I. agent, only to watch it ignore them an hour into a session? The fix lies in knowing WHERE your instructions should live. Read on for all the details...

WHY AGENTS "FORGET"
• Everything an agent knows lives in its context window, and every token costs money and (more subtly) attention.
• Long sessions trigger "compaction": The conversation gets summarized to free up room, and instructions given early can get squeezed out.
• Every steering method answers one question: How do I make an instruction cheap to carry and hard for the agent to lose?


THE STEERING TOOLKIT (drawn from Anthropic's Claude Code, but the ideas generalize)
1.) Always-on files (e.g., CLAUDE.md): Loaded every session and re-read after compaction. Keep them under 200 lines, give them an owner, review changes like code.

2.) Rules: Path-scoped constraints that load only when relevant files are touched.

3.) Skills: Procedures (deploy workflows, checklists) whose full text loads only when invoked.

4.) Subagents: side tasks that run in isolated context windows... only the final summary returns.

5.) Hooks: deterministic code that fires on lifecycle events. The big idea: An instruction is a probability while a hook is a guarantee. If something must *never* happen, enforce it with code, not prose.


THE INDUSTRY IS CONVERGING
• AGENTS.md (kicked off by OpenAI, stewarded by the The Linux Foundation and backed by Google, Microsoft and AWS) serves similar function to CLAUDE.md and is read natively by Codex, Cursor, GitHub Copilot, Gemini CLI and dozens more tools across 60,000+ repositories.
• ETH Zurich researchers studied 138 real-world repos: Developer-written instruction files improved agent task success ~4% and cut agent-introduced bugs by 35-55%.
• The same study found LLM-generated instruction files DECREASED success while raising inference costs by 20%+. These data suggest the value is the human judgment encoded in the file... **you can't delegate the steering wheel to the thing being steered**.

NOT A CODER? THE SAME FRAMEWORK APPLIES
• Custom instructions = your always-on file (keep it short).
• Projects and Gems = your path-scoped rules.
• Custom GPTs = the consumer cousin of skills.

BOTTOM LINE
• Match persistence to relevance: always-on files stay ruthlessly short; procedures and area-specific conventions load on demand.
• "Always" and "never" are signals you need a guardrail (deterministic enforcement), not an instruction.
• Treat steering files as code: owned, reviewed and pruned. An instructions file that grows without gardening dilutes the instructions that matter.

The SuperDataScience podcast is available on all major podcasting platforms, YouTube, and at SuperDataScience.com.

In Five-Minute Friday, YouTube, SuperDataScience, Podcast Tags #promptengineering, #datascience, #agenticAI, #aiAgents, #ai, #superdatascience
Older: How dbt Won Analytics Engineering, with dbt Lab’s CEO Tristan Handy →
Back to Top