agentleFS
L-X-TL-X-T/ng-agentic-skills/.agents/skills/update-skills-directory/SKILL.md

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.

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
  1. Very specific:

    Keep .agents/skills/ aligned with agent-skill best practices: one SKILL.md per skill, optional flat references/, scripts/, or assets/ …

    line 12
  2. Distinctive:

    No per-skill README.md exists.

    line 34
  3. Very specific:

    No stray tool-call markup (</content>, </invoke>, </output>) anywhere in the skill's files.

    line 35
  4. Very specific:

    Update SKILL.md pointers to use relative paths with forward slashes.

    line 69
  5. Very specific:

    Remove per-skill README.md files after preserving any still-useful origin or catalogue text in 02-SKILLS.md.

    line 70
  6. Distinctive:

    Add missing index rows and remove stale rows.

    line 72
  7. Distinctive:

    Do not stage or commit unless the user explicitly asks.

    line 76

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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.md exists.
  • Frontmatter has name matching the folder, using only lowercase letters, numbers, and hyphens.
  • Frontmatter has a trigger-focused description under 1,024 characters, including for explicit-only skills.
  • SKILL.md is under 500 lines and contains high-level procedure or routing, not bulky reference.
  • Support files live in one-level-deep references/, scripts/, or assets/ folders; supported harness metadata such as agents/openai.yaml is also allowed.
  • references/ links are explicit and loaded just in time.
  • No per-skill README.md exists.
  • 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 / yarn commands (pnpm only – pnpm add, pnpm exec, pnpm dlx), pnpm test or ng test without --watch=false, pnpm start / ng serve without 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/, or assets/.
  • Update SKILL.md pointers to use relative paths with forward slashes.
  • Remove per-skill README.md files after preserving any still-useful origin or catalogue text in 02-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 localSha256 for 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.md files stay under 500 lines.
  • Support files are one level deep under references/, scripts/, assets/, or agents/.
  • No em dashes, npm/npx/yarn commands, watch-mode test commands, or ungated dev-server starts.
  • skill-sources.json digests match the third-party skill folders.
  • No per-skill README.md files remain.
  • 02-SKILLS.md links every skill and no stale skill entries remain.

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.