Reusable Agent Skills Need a Thin SKILL.md

The mistake was simple. We built a reusable chat assistant skill, then put too much of the implementation into the skill file itself. It was technically correct and operationally wrong. The file got bloated, the boundaries got blurry, and the next agent would have had to read a wall of implementation detail just to learn whether the skill applied at all.

Why progressive disclosure matters

The Agent Skills format is built around progressive disclosure for a reason. The canonical Agent Skills spec is what we were following here. The frontmatter is what the agent sees first. The SKILL.md body is what it reads when the skill becomes relevant. Supporting files are where the deeper implementation lives. That is not a cosmetic choice. It is how you keep a skill fast to match, easy to scan, and still deep enough to be useful when it is activated.

If you dump the full build recipe into SKILL.md, you make the activation layer noisy. The agent has to carry too much context before it even knows whether the skill is the right one. That is a bad trade. It turns the skill file into a manual instead of a trigger and a map. The open standard is much closer to an interface contract than a notebook.

1. 1Frontmatter should answer selection. What does this skill do, and when should the agent use it?
2. 2SKILL.md should answer activation. What are the goals, boundaries, and quality rules once the skill is in play?
3. 3Supporting files should answer execution. What are the concrete steps, examples, templates, or edge cases?

What we moved out of SKILL.md

Our first pass at the site-chat-assistant skill included the implementation guide inline. That meant the same file had to do three jobs at once: explain when to use the skill, define the architectural boundary, and teach the build process. That is too much for one file. We refactored it so SKILL.md stayed compact and the real build guide moved into a references file.

site-chat-assistant/
├── SKILL.md
└── references/
    └── implementation-guide.md

That split made the skill easier to reason about immediately. The top-level file now tells an agent what this skill is for, what stays local to the consumer repo, and what the embedded retrieval model looks like. The implementation guide stays available, but only when the agent actually needs to build or modify the pattern. That is the whole point of progressive disclosure: load only what you need, when you need it.

The deeper lesson: write skills like interfaces, not essays

A good skill file should feel like an interface. It should describe the contract clearly: inputs, outputs, constraints, and the smallest set of rules needed for reliable use. If a section only matters after the skill has already activated, it probably belongs somewhere else. That is especially true for implementation steps, code snippets, and template files.

• Keep activation lightweight. The agent should know the intent of the skill quickly.
• Keep implementation deep. The build details still matter, just not in the first file the agent loads.
• Keep consumer specifics local. Brand copy, routes, content paths, and host rules should stay close to the project that owns them.
• Keep the shared core reusable. The generic pattern should survive in another repo without dragging along one project’s exact wiring.

Why this mattered in practice

This was not theory for theory’s sake. We were actually trying to make the skill portable across projects. That meant the shared skill needed to teach the assistant pattern, while the local Netrii adapter stayed thin and specific. Once we separated those layers, the repository structure started to look like the architecture: shared behavior in the shared repo, local details in the local repo, concrete implementation in supporting files.

The result is a better authoring standard for agent skills. The skill file is now easier to discover, easier to activate, and harder to misuse. The implementation guide still exists, but it no longer pollutes the front door. That makes the skill more portable, less fragile, and cheaper to maintain.

References

• Agent Skills spec — the canonical progressive-disclosure model that informed the skill refactor.
• site-chat-assistant skill — the reusable pattern this post discusses.

The next move

Going forward, I want this to be the default pattern for skills across Cascade projects. Keep the top layer short. Put the concrete procedure in a supporting file. Treat the skill file like a contract, not a dumping ground. That makes the skills easier for agents to load, easier for humans to maintain, and much easier to reuse when the same pattern shows up somewhere else.