One challenge with agent instructions when integrating with CLIs is how to direct the LLM so it knows how to use them, and keep those instructions up to date. I recently learned about a relatively simple idea: create a subcommand that outputs instructions targetted at LLMs and refer to it from AGENTS.md.
I have been writing a lot more CLI tools lately, and I use some across projects. Having to copy instructions across projects and keep them up to date is cumbersome. Markdown is also not very refactoring-friendly.
Of course, there are skills that are intended to be used as interfaces for reuse. But this also means that in cases where a CLI command needs a different set of instructions, you also need to update the skill. This could work locally, but if this is a public command, how do you ship the updated skill with the updated command? Or, in a skill-first way of thinking: should the command ship with the skill instead so they form a single unit? (The latter seems weird, but I would not be surprised if we start seeing this. Also, dependency management in skills should be worked out before that, but that is a whole other topic.)
A more interesting way is to rely only on the AGENTS.md file, a much more stable and consistently adopted interface to instruct LLMs, and add a dedicated subcommand that outputs its operational details as instructions to the LLM.
I learned this from Beads, a task management tool. It has a specific subcommand that targets LLMs: bd prime. Here is the top of what it outputs:
# Beads Workflow Context
> **Context Recovery**: Run `bd prime` after compaction, clear, or new session
> Hooks auto-call this in Claude Code when .beads/ detected
# 🚨 SESSION CLOSE PROTOCOL 🚨
**CRITICAL**: Before saying "done" or "complete", you MUST run this checklist:
...
## Core Rules
- **Default**: Use beads for ALL task tracking (`bd create`, `bd ready`, `bd close`)
...
## Essential Commands
### Finding Work
- `bd ready` - Show issues ready to work (no blockers)
- `bd list --status=open` - All open issues
...
...
And it integrates into the AGENTS.md file as follows (note the last line):
**Quick reference:**
- `bd ready` - Find unblocked work
- `bd create "Title" --type task --priority 2` - Create issue
- `bd close <id>` - Complete work
- `bd dolt push` - Push beads to remote
For full workflow details: `bd prime`
Aside from having a way to ship instructions with the CLI command, this is extra useful because instructions can evolve with versions of the command.
For example, Beads had some major changes related to how tasks were synced across team members; however, the LLM instructions to handle this were hard-coded in the AGENTS.md file. This meant all projects had to have their AGENTS.md file changed after you updated Beads.
However, if you have a subcommand that outputs the latest instructions aligned with how the command works, everything can stay in sync. The AGENTS.md file does not need to be updated. So instead of adding a lot of instructions to the AGENTS.md file, add a few basic commands and point the LLM to the subcommand if more is needed.
To circle back to agent skills, you could create a short Beads integration skill, with only the short instruction set above, and invoke it from the AGENTS.md file. This is probably the cleanest; I am currently considering whether I should do that or not.