I'm still finding skill use to be far less reliable than clear instruction in AGENTS.md - I appreciate the idea is to give the agent the opportunity not to add the skill if not relevant to avoid context bloat, but there's no way (without an explicit instruction in AGENTS.md) to ensure that the agent will use the skill, and that point they might as well be any markdown file referenced at any location.
While building https://www.agentkanban.io (a Github CoPilot integrated task board), I experimented a lot with instruction placement. A single degree of separation from AGENTS.md works really well (I needed a robust means of having the agent pick up task specific IDs and so settled on a file called INSTRUCTION.md in a file managed by the tool which avoids polluting AGENTS.md as much as possible). I experimented with skills, but they were skipped too often for the tool to work as reliably as it now does.
I have a similar project. Through experimentation, I’ve realized a few things about skills that might be useful:
1. Less is better. A project rarely needs more than a few skills. A skill is best when the output is measurable and clearly defined. The size of the skill is also very important, since shorter ones are easier to actively maintain and for the agent to reliably follow.
2. Context is important. I keep a short knowledge map in my AGENTS.md file, which gives the agent the context it needs for the overall workflow.
3. Frontmatters work surprisingly well. It pairs nicely with agents and has given me good results (though this might be somewhat of a byproduct).
4. Consistency matters. All skills should follow the same format. For example, I strip all Markdown formatting and enforce a very specific format to them. If you import a skill, do change its format with yours.
I would also go and say not to mistake skills for prompts, but that depends on what you deem the ideal workflow.
I also have an .agents/rules/init.md with the following prompt:
"At the start of every chat or task, you MUST read the following file:
- [AGENTS.md](@AGENTS.md)". Most harnesses find this automatically, and I just give the file to those that don't.
Overall, I’ve found that a project usually only needs the AGENTS.md file and an .agents directory (prompts/, rules/, skills/).
I would love to hear other opinions on the things I just said.
Question for you, since you seem like you know what you're doing here: How do I learn about stuff like agents.md? I feel like every week there's a new Claude feature people are talking about and I have no idea how they learned about it.
I'm not the guy in question, but I can offer a few pointers other than the ones I did in my other message.
Tailor things to make them your own. First, imagine the kind of workflow you want. Take a pen and a paper and map it out. Second, decide on a format for your agent-related files. Third, offer the prior information to an agent to create a few general iterations. Read them and ask yourself something along the lines of: "Will cutting this affect the workflow?". If not, cut it out.
Instead of jumping and copying the first thing you find, gather knowledge by reading different workflows first. Don't limit yourself to a single field, either. For example, learning about Bloom's Taxonomy can change how you view certain things, so expand your horizons.
Take small steps. It takes a lot of experimentation to reach a good enough workflow.
I think just keeping an ear to the ground, and sometimes through querying LLMs themselves about how to solve certain problems. Most vendors seem to follow Anthropics lead on configuration and agent instruction (though it certainly varies). I just picked up this link from HN today which was good https://claude.com/blog/how-claude-code-works-in-large-codeb... - I haven't been using hooks until now which the article emphasised, but I can see how they would be useful (for example for running formatters to enforce file format rules / clean up after the agents).
I've had cases where it doesn't explicitly use a skill I've added BUT it still performs the actions described in the skill on its own more often than it did before I created the skill. I'd rather it use the skill for consistency, but having it follow most of the steps most of the time in cases I've forgotten to explicitly call out the skill is a better outcome.
While building https://www.agentkanban.io (a Github CoPilot integrated task board), I experimented a lot with instruction placement. A single degree of separation from AGENTS.md works really well (I needed a robust means of having the agent pick up task specific IDs and so settled on a file called INSTRUCTION.md in a file managed by the tool which avoids polluting AGENTS.md as much as possible). I experimented with skills, but they were skipped too often for the tool to work as reliably as it now does.