update-skills-directory
Skill13 starsChanged 44 days agoMITView on GitHub
Audit .agents/skills so every skill has valid frontmatter, a lean SKILL.md, flat support folders, and a root 02-SKILLS.md link. Use when the user adds, renames, removes, or restructures a skill, or asks to update the skills index/directory. Do not use it to create per-skill README files.
In this repository34 other files it gives its agents.
- AGENTS.mdAGENTS.md
- .junie/AGENTS.mdAGENTS.md
- .claude/CLAUDE.mdCLAUDE.md
- .github/copilot-instructions.mdCopilot instructions
- angular-developerSkill
- brainstormingSkill
- code-reviewSkill
- create-a-skillSkill
- create-e2e-testsSkill
- diagnosing-bugsSkill
- frontend-designSkill
- git-stack-rewriteSkill
- grill-meSkill
- grill-with-styleSkill
- handoverSkill
- implement-planSkill
- ng-accessibilitySkill
- ng-data-accessSkill
- ng-formsSkill
- ng-migrateSkill
- ng-performanceSkill
- ng-prototypeSkill
- ng-refactorSkill
- ng-review-architectureSkill
- ng-review-style-guideSkill
- ng-securitySkill
- ng-signal-storeSkill
- ng-stylingSkill
- ng-testingSkill
- ng-verify-featureSkill
- spartanSkill
- test-driven-developmentSkill
- unslopSkill
- update-skillsSkill
The file
We split this skill into the rules it gives an agent
7 rules. About 0 are common, 3 are distinctive, and 4 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈3
Distinctive · estimate
This author's own choices. Worth a look.
4
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 12
Keep .agents/skills/ aligned with agent-skill best practices: one SKILL.md per skill, optional flat references/, scripts/, or assets/ …
- Distinctive: line 34
No per-skill README.md exists.
- Very specific: line 35
No stray tool-call markup (</content>, </invoke>, </output>) anywhere in the skill's files.
- Very specific: line 69
Update SKILL.md pointers to use relative paths with forward slashes.
- Very specific: line 70
Remove per-skill README.md files after preserving any still-useful origin or catalogue text in 02-SKILLS.md.
- Distinctive: line 72
Add missing index rows and remove stale rows.
- Distinctive: line 76
Do not stage or commit unless the user explicitly asks.
≈ “Common” is an estimate: at least 1 in 5 of the 372,429 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
Update skills directory
Keep .agents/skills/ aligned with agent-skill best practices: one SKILL.md per skill, optional
flat references/, scripts/, or assets/ folders, and a repo-root 02-SKILLS.md index. Skill
folders are agent artifacts, so do not create per-skill README.md files.
Process
1. Enumerate
List every immediate subfolder of .agents/skills/ and read 02-SKILLS.md if it exists.
Done when every skill folder and every current index entry is accounted for.
2. Audit each skill
For every skill folder, check:
SKILL.mdexists.- Frontmatter has
namematching the folder, using only lowercase letters, numbers, and hyphens. - Frontmatter has a trigger-focused
descriptionunder 1,024 characters, including for explicit-only skills. SKILL.mdis under 500 lines and contains high-level procedure or routing, not bulky reference.- Support files live in one-level-deep
references/,scripts/, orassets/folders; supported harness metadata such asagents/openai.yamlis also allowed. references/links are explicit and loaded just in time.- No per-skill
README.mdexists. - No stray tool-call markup (
</content>,</invoke>,</output>) anywhere in the skill's files. - Repo-state claims are detection, not assertion: grep the skill for phrases like
not set up,not wired,not installed,is NOT in,no \<file>`` and verify each against the working tree; the stack's branches are rewritten regularly, so any hard-coded "this repo has/lacks X" eventually lies. Rephrase hits as "check for X; if present … / if absent …". - House-rule sweep – the skills are the exemplar of the project rules, so grep every file in the
skill for: an em dash (U+2014; the Markdown guide mandates the spaced en dash),
npm/npx/yarncommands (pnpm only –pnpm add,pnpm exec,pnpm dlx),pnpm testorng testwithout--watch=false,pnpm start/ng servewithout the dev-server approval sentence, untagged code fences, and links to repo-root files that do not exist.
Done when each skill has pass/fail notes for structure, frontmatter, disclosure, house rules, and index status.
3. Audit the root index
Confirm 02-SKILLS.md links every skill's SKILL.md, contains no stale skill entries, and records
third-party origins in the index rather than in per-skill docs.
Done when the index is one-to-one with the skill folders present.
4. Report
Present a concise list of gaps: missing SKILL.md, invalid frontmatter, overlong SKILL.md,
nonstandard support files, stale links, missing index rows, house-rule violations, stale
localSha256 digests in skill-sources.json (recompute with the convention in
SKILL-MAINTENANCE.md), and forbidden per-skill README.md files.
Done when the user can see every gap at a glance.
5. Fix
With approval, make the smallest correction that restores the structure:
- Move bulky support material into
references/,scripts/, orassets/. - Update
SKILL.mdpointers to use relative paths with forward slashes. - Remove per-skill
README.mdfiles after preserving any still-useful origin or catalogue text in02-SKILLS.md. - Add missing index rows and remove stale rows.
- Replace em dashes, package-manager commands, and watch-mode test commands with the house form.
- Refresh
localSha256for every third-party skill whose files changed.
Do not stage or commit unless the user explicitly asks.
Done when every skill passes the audit and all local links resolve.
Checklist
- Every skill folder has one
SKILL.md. - Frontmatter names match folder names and descriptions are trigger-focused.
SKILL.mdfiles stay under 500 lines.- Support files are one level deep under
references/,scripts/,assets/, oragents/. - No em dashes,
npm/npx/yarncommands, watch-mode test commands, or ungated dev-server starts. skill-sources.jsondigests match the third-party skill folders.- No per-skill
README.mdfiles remain. 02-SKILLS.mdlinks every skill and no stale skill entries remain.
Does 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.

