LeanMeanCleanAppsLeanMeanCleanApps/CleanModelContextProtocol/.agents/skills/writing-a-skill/SKILL.mdwriting-a-skill
Skill1 starsChanged 7 days agoMITView on GitHub
How to add or change a skill in .agents/skills - the open SKILL.md format, the house layout (rule, steps, example, don't, check), scope metadata, size limits, and keeping skills current as features are built on this solution. Use when a skill is missing, wrong or out of date, when you build a feature that adds a new pattern, or when the way we do something changes.
In this repository40 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- add-a-use-caseSkill
- api-conventionsSkill
- branches-and-pull-requestsSkill
- cancellationSkill
- ci-for-your-solutionSkill
- ci-pipelineSkill
- clean-architecture-layersSkill
- configuration-and-environmentsSkill
- coverageSkill
- csharp-house-styleSkill
- data-access-ef-coreSkill
- database-migrationsSkill
- docker-and-composeSkill
- docs-and-voiceSkill
- errors-and-exceptionsSkill
- expose-a-use-caseSkill
- family-syncSkill
- health-checksSkill
- integration-testsSkill
- json-serializationSkill
- mapping-with-mapperlySkill
- mcp-inspectorSkill
- mediatorSkill
- optional-token-authSkill
- packages-and-dependenciesSkill
- pagingSkill
- presentation-integration-testsSkill
- releasesSkill
- sample-dataSkill
- security-findingsSkill
- serilogSkill
- telemetrySkill
- template-authoringSkill
- test-designSkill
- time-providerSkill
- unit-testsSkill
- validationSkill
- xml-docs-and-openapiSkill
The file
We split this skill into the rules it gives an agent
7 rules. About 0 are common, 6 are distinctive, and 1 is very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈6
Distinctive · estimate
This author's own choices. Worth a look.
1
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 28
Look for an existing skill first.
- Distinctive: line 29
Write the skill from the code as it is.
- Distinctive: line 31
Add it to the skills table in AGENTS.md with a one-line "Use it when you...".
- Very specific: line 32
Check the format against the table above: the name matches the folder, the description says when to use it, and the file opens with the --- …
- Distinctive: line 36
Write a skill for a plan or a pattern the code doesn't follow yet.
- Distinctive: line 38
Put jokes in a skill.
- Distinctive: line 40
Leave a skill describing code that has changed.
≈ “Common” is an estimate: at least 1 in 5 of the 350,495 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Writing a skill
The rule
A skill is a folder in .agents/skills named for the job, holding a SKILL.md in the open Agent Skills format, so any agent can load it. Skills describe how things are done here today. When the way we do something changes, the skill changes in the same pull request as the code.
The skills grow with the solution. When you build a feature that brings a pattern someone will repeat (a new kind of integration, a background job, a payment provider), it gets a skill in the same change, written from the code you just added.
Frontmatter:
| Field | Rules |
name | Lowercase letters, digits and hyphens, at most 64 characters, the same as the folder |
description | What it covers, then "Use when..." with the situations that should load it. At most 1,024 characters |
metadata.scope | shared (the same in every Lean Mean Clean Apps template), presentation (this presentation layer only), or, in the template repositories only, repository and maintainer. Skills you add for your own features can use shared |
The body uses the same sections every time: The rule, Steps, Example (real code with its path), Don't (mistakes we've actually made), Check (commands that prove it). Keep it under 500 lines; move long material into a references/ folder beside SKILL.md.
Steps
- Look for an existing skill first; extend it rather than adding a near-duplicate.
- Write the skill from the code as it is. Copy examples from real files and give their paths.
- Point to related skills by name in backticks (
unit-tests) instead of repeating them. - Add it to the skills table in
AGENTS.mdwith a one-line "Use it when you...". - Check the format against the table above: the name matches the folder, the description says when to use it, and the file opens with the
---frontmatter block.
Don't
- Write a skill for a plan or a pattern the code doesn't follow yet.
- Cite decisions, tickets or dates. The skill is the current answer, not its history.
- Put jokes in a skill.
- Give a skill a vague description; the description is what makes an agent load it.
- Leave a skill describing code that has changed. Fix the skill or the code in the same change.
Check
head -6 .agents/skills/<name>/SKILL.md # name, description and scope are there
wc -l .agents/skills/<name>/SKILL.md # under 500 linesDoes it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.