skill-design
Skill0 starsChanged 4 days agoMITView on GitHub
Authors, improves, and prunes agent skills: --create builds a skill from a job description; --improve audits and repairs an existing skill; --prune merges duplicate skills into one folder.
- Deletes or force-pushes
5 other projects use a version of this.
Adopted by
Most recently taken up by
- twglhk/gamedev-agent-skillstheir own version, first seen Nov 8, 2026
- MiguelSavignano/claude-code-systemtheir own version, first seen Nov 1, 2026
- Noizefield/audio-plugin-codertheir own version, first seen Oct 8, 2026
- i-9-ai/skillstheir own version, first seen Sep 24, 2026
- zznabil/lean-agent-skill-collectiontheir own version, first seen Aug 26, 2026
Other versions5 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 5
- Noizefield/audio-plugin-coder★ 334same name
- MiguelSavignano/claude-code-system★ 6same name
- zznabil/lean-agent-skill-collection★ 1same name
- i-9-ai/skills★ 0same name
- twglhk/gamedev-agent-skills★ 0same name
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository75 other files it gives its agents.
- AGENTS.mdAGENTS.md
- skills/skill-authoring/tools/AGENTS.mdAGENTS.md
- aes-docsSkill
- aes-fixSkill
- aes-layerSkill
- aes-migrationSkill
- android-emulator-linux-gpsSkill
- computer-useSkill
- flatpak-chromium-automationSkill
- qwen-webSkill
- grok-buildSkill
- hermes-agentSkill
- omnirouteSkill
- orcaSkill
- account-managerSkill
- brave-setupSkill
- password-managerSkill
- codegraphSkill
- deep-cleanSkill
- dogfoodSkill
- reviewSkill
- systematic-debuggingSkill
- blender-arwakySkill
- comfyuiSkill
- llm-writingSkill
- vision-arwakySkill
- playwright-toolingSkill
- setup-ci-quality-gatesSkill
- statuslineSkill
- systemd-headless-serviceSkill
- xdg-spec-complianceSkill
- figcraft-builderSkill
- figcraft-iconsSkill
- figcraft-motionSkill
- figcraft-prototyperSkill
- figcraft-reviewSkill
- figcraftSkill
- figcraft-svgSkill
- figcraft-typographySkill
- github-authSkill
- issue-makerSkill
- issue-workerSkill
- mergifySkill
- pr-babysitSkill
- releasingSkill
- repo-managerSkill
- ascii-artSkill
- ascii-videoSkill
- gif-searchSkill
- media-acquisitionSkill
- docxSkill
- emailSkill
- google-workspaceSkill
- notionSkill
- pdfSkill
- pptxSkill
- xlsxSkill
- competitor-news-monitorSkill
- product-price-monitorSkill
- weekly-review-planningSkill
- The first 60 shown.
The file
Files
SKILL.md
Skill Design
You author, improve, and prune agent skill directories (a collection of SKILL.md folders). Three modes own three distinct jobs; pick one per invocation.
Purpose of this skill: keep the skill tree holding skills that read clean, invoke correctly, follow the shared body shape and lint standard, and carry no duplicate or overlapping folders. --create builds from a described job; --improve runs the full audit-then-improve sequence on an existing skill (structure, naming, frontmatter, body shape, and dangling refs to the lint standard); --prune collapses duplicate or same-purpose skills into one folder.
Rules
Rules that apply to every step. Reference files cite these; they never restate them.
| ID | Rule | Why | Check | ||
| R1 | Mode scope: --create and --improve author/improve a single skill (or pack); --improve runs the full audit-then-improve sequence; --prune works on a category or the whole tree and collapses overlap. Each mode routes to its own reference; they do not share state. | Keeps modes isolated so an edit in one mode cannot leak into another. | --create/--improve touch one skill folder; --prune touches a category or whole tree; no cross-mode state shared. | ||
| R2 | Interface changes ripple: the argument-hint plus every flag and safety-model mention in a skill body must stay in lockstep. Grep the whole skill directory (body and all references/) for each flag name and mode term before deciding an edit is done; a flag retired or renamed in SKILL.md that still governs a step file silently re-imposes the old behavior for that path. Safety-model flips (e.g. flipping the default from interactive-with-approval to headless-autonomous, or inverting when a flag gates execution) touch more than the flag's own mention: every step file that carries a blocking approval step, a "wait for explicit approval" line, a Dry-Run Mode section, a verification checklist item, or a decision-flowchart branch must be found and re-worded to the new semantics. Grep for approv, wait for, explicit confirmation, and the flag name (both bare and backtick-wrapped) across the whole skill directory, not just SKILL.md; a step file that still says "wait for approval" under a new headless default silently re-blocks the pipeline for that step. | Retired flags must not silently re-activate old behavior. | Grep every flag name and mode term across body + references/; zero stale references after the edit; every "wait for approval" line matches the new default semantics. | ||
| R3 | One home per fact. Each rule, value, or list lives in a single authoritative place — a Rules bullet below or a reference file. When an edit touches an existing copy elsewhere, make the requested change and report the duplication instead of silently rewriting. | Prevents drift between two copies of the same fact. | No fact appears in two locations; any edit touching a copy reports the duplication. | ||
| R4 | Splitting a language monolith into step variants. When a Pattern B pipeline skill carries per-language monolith reference files (one file per language bundling multiple phases) and the user asks for `step-<N>[a | b | c]variant naming: find the phase boundary inside each monolith (usually a## Phase 2:heading or equivalent) and split there. The shared preamble (rules, purpose, when-to-use, fundamental questions, language-specific KEEP/REMOVE tables) stays with the first phase's step file; the second phase's step file carries only the phase body plus the cross-phase tails (verification checklists, quick-reference commands, common mistakes, decision flowchart, dry-run mode, tool reference) — those tails span both phases and belong to the later step so the step-1 file stays focused on detection. Re-title each new file to# Step <N><variant>: <Phase> — <Language>and add a one-line self-containment note (what the file owns and how it is picked:picked by target_lang from step 0). Never leave the old monolith filenames in the tree after the split; delete them (or git mv` the content out first). | Splits per-language monoliths into ordered step variants without leaving dead filenames behind. | Phase boundary located; shared preamble stays with step-1; tails move to later step; new files titled # Step <N><variant>: <Phase> — <Language>; old monolith filenames removed from tree. |
| R5 | No no-op sentences. If a sentence does not change behavior — "be careful", "use best practices", a guardrail restating the instruction it follows — delete it or replace it with a checkable criterion. | Removes filler that wastes tokens and changes nothing. | Every sentence either changes behavior or is deleted/replaced with a checkable criterion. | ||
| R6 | Solve the class, not the instance. Fix bad output where the fact is owned, not with a downstream check that catches one symptom. Check every generalization against at least two concrete instances. | One guard at the shared function is a smaller diff than one per caller; fixes the root cause. | Every fix located at the fact's owner; each generalization checked against two concrete instances. | ||
| R7 | Set degrees of freedom. High (text steps) for context-dependent work; medium (parameterized scripts) when a preferred pattern exists; low (exact commands) for fragile, strict-sequence operations. | Matches autonomy to fragility; avoids over-automating brittle steps. | DOF level chosen per step kind; high for context-dependent, medium for parameterized scripts, low for fragile strict-sequence operations. | ||
| R8 | Budget for permanent cost. description: and when-to-use: are injected into the skill list every session; the body loads per use; references/*.md cost nothing until opened. Keep the two trigger fields non-overlapping, and move anything task-conditional out of the body. | Trigger fields are per-session cost; keep them minimal and non-overlapping. | description: and when-to-use: non-overlapping; all task-conditional content moved out of body into references. | ||
| R9 | Consistent terminology. One term per concept, no synonyms; model-agnostic wording. | Synonyms break cross-step reference and model-agnostic parsing. | One term per concept; no synonyms; all wording model-agnostic. | ||
| R10 | Dangling refs rot fast. related_skills:, sibling mentions, and cross-skill links are not existence-checked — resolve each against the tree before relying on it, and remove refs to skills that do not exist. | Unchecked links silently point nowhere. | Every related_skills:, sibling mention, and cross-skill link resolved against tree; refs to missing skills removed. | ||
| R11 | Mandatory frontmatter. Exactly four keys are mandatory: name, description, when-to-use, argument-hint; every other key is optional and target-dependent. Full key table: references/improve/step-3-frontmatter-keys.md; validator rule catalog: references/improve/step-4-validator-catalog.md. | Parser depends on exactly these four keys; extras are target-dependent. | Four mandatory keys present; optional keys only where target-dependent. | ||
| R12 | Frontmatter semantics. description: = WHAT + WHEN + trigger terms, third person. Trigger phrases the description cannot fit go in when-to-use:, never in a triggers: key. | triggers: key is ignored by the parser; trigger terms belong in description: / when-to-use:. | description: covers WHAT + WHEN + triggers; when-to-use: holds overflow trigger phrases; no triggers: key present. | ||
| R13 | YAML hygiene. Quote values containing : or indicator characters (`{ } [ ] * & # ! | > % @, backtick); never indent a field under a previous field's value (one nested line invalidates the whole frontmatter — only name, description, when-to-use survive recovery); multi-word keys kebab-case (when_to_useis the accepted alias). **Unclosed block**: aSKILL.mdwhose frontmatter opening---has no closing---(or the closing delimiter was lost) makes the parser treat everything to the first valid end-of-document as one value —descriptionandwhen-to-usesilently vanish even though the file *reads* fine. An improve pass must verify the second---exists *and* sits immediately before the# Titleheading;sdc read <skill>` (or the description in the skill list) is the probe — a missing description after a frontmatter edit means the block is not closed, not that the key was dropped. | Unclosed frontmatter silently drops description and when-to-use; bad quoting breaks parsing. | Values with : or indicator chars quoted; no field indented under a previous value; multi-word keys kebab-case; second --- verified immediately before # Title. | |
| R14 | Grok Build parser limits. name ≤ 64 chars; description and when-to-use ≤ 1,024 chars; top-level version:, triggers:, and entry_points: are ignored. | Parser truncates or ignores oversized/ignored keys silently. | name ≤ 64 chars; description / when-to-use ≤ 1,024 chars; no top-level version:, triggers:, or entry_points:. | ||
| R15 | Structure. Exactly one SKILL.md at <category>/<skill>/SKILL.md (nested SKILL.md files are rejected). The body is a routing table of contents, ~100–200 lines, with steps that end in checkable completion criteria; detail lives in references/*.md (subfolders allowed when the set is large) and every reference, whatever its depth, links directly from SKILL.md. Non-trivial logic ships as scripts/<file> referenced by path. | One SKILL.md per skill; detail offloaded to references; logic in scripts. | Exactly one SKILL.md per <category>/<skill>/; body ~100–200 lines; every reference linked from SKILL.md; non-trivial logic in scripts/ referenced by path. | ||
| R16 | Mandatory body shape. Every SKILL.md uses exactly three sections: # Title, ## Rules, ## Routing. All task data, commands, examples, field shapes, stop conditions, and worked examples belong in references/*.md or scripts/*. If the body contains anything beyond those three sections, move it to a reference before publishing. Stop conditions, limitations, and "when done" criteria are Rules bullets — not their own ## heading. A fourth ## heading (e.g. ## Completion, ## Current limitations, ## Pitfalls) breaks the three-section shape. Before finishing any improve run, grep ^## on each target SKILL.md: exactly two ## lines expected, both named Rules and Routing. Any other ## must be folded into a Rules bullet or moved to a reference. | Three-section shape keeps skills scannable and machine-readable. | grep ^## returns exactly two lines: ## Rules and ## Routing; no other ## headings; all task data in references or scripts. | ||
| R17 | Templates are the single source of truth for shape. template/template.md is the entry index; template/skill.md is the canonical SKILL.md skeleton and template/reference.md is the canonical reference-file shape. Every create/improve step copies from the template the index names rather than restating the shape inline; a new artifact kind gets its own template/<artifact>.md registered in the index. | Shape lives in exactly one file — its template; nothing restates the shape inline. | template/template.md indexes every template; create/improve copy from template; no inline restatements of shape. | ||
| R18 | Audit standard: sdc lint is the mechanical gate; references/improve/step-0-overview.md holds the key table, the validator rule catalog, the reference-pattern decision, and the pre-publish checklist. --improve runs the full audit-then-improve sequence against that standard and fixes every flagged issue. | Mechanical gate catches issues before publish. | sdc lint passes; --improve fixes every flagged issue against references/improve/step-0-overview.md. | ||
| R19 | Validation rules (enforced when improving, pruning, and consolidating skills): the full rule catalog is references/improve/step-4-validator-catalog.md; sdc lint is the mechanical gate. | Consistent validation across improve/prune/consolidate. | Full rule catalog at references/improve/step-4-validator-catalog.md; sdc lint used as gate. | ||
| R20 | Tracked catalog artifact: sdc catalog --build regenerates catalog.json (the JSON catalog) at the skills root. catalog.json is a list of objects, each carrying name, description, when_to_use, and category per skill. Operators must rebuild after any skill frontmatter change; the drift check (exit 3) is available at the agent level — it is not a CLI flag on sdc catalog. When the sdc binary cannot import its modules (missing cli/skills_design package after a directory rename or stale worktree), call SkillsCatalog().rebuild(Path('<repo>/skills')) directly from Python with the working modules/ directory inserted into sys.path; it writes the same catalog.json the CLI would. | Catalog is regenerated from frontmatter; drift check at agent level. | catalog.json rebuilt after every frontmatter change; drift check uses exit 3 at agent level, not a sdc catalog flag; Python fallback used when the sdc binary fails to import. | ||
| R21 | Rollback: the snapshot (or HEAD SHA when the tree was dirty) is the undo path; git reset --hard <sha> restores both the skill and unrelated state. A git reset --hard also reverts your own tracked-file edits on disk (untracked new files survive) — after any hard reset, re-verify on-disk state with git diff against the target paths and re-apply lost edits before declaring the run done. Record the snapshot SHA in the commit message and final report. A run that cannot commit (snapshot or final commit blocked) falls back to --dry-run behavior: report only, no changes applied. | Provides an undo path for any edit run. | Snapshot SHA recorded; git reset --hard <sha> used for rollback; on-disk state re-verified after hard reset; uncommitted changes re-applied before declaring done. | ||
| R22 | Safety model: every mode runs fully autonomous by default — read-only, edit, snapshot, and execute steps all proceed without asking the user for confirmation. --dry-run is the only control flag: it generates the full report and stops before any snapshot or execute, making no changes to the tree. Destructive actions go to _archive/ first; permanent delete only with explicit --hard-delete. Commit blocked, not --dry-run: when the edit completed and on-disk verification passes but the commit lane is irrecoverably swept by concurrent commits or a dirty tree, the run still ends cleanly — report the on-disk paths as the verified handle, state that the files are uncommitted, and give the exact one-line git add + git commit command for the quiet-tree retry. Do not fall back to --dry-run (report-only) for a run that already applied edits: that would misreport the tree as untouched when it is not. | Autonomous by default; --dry-run is report-only; destructive actions archived first. | All steps proceed without user confirmation; --dry-run stops before snapshot/execute; destructive actions go to _archive/; --hard-delete required for permanent delete; blocked commit reports on-disk paths + exact git add/git commit retry command. | ||
| R23 | Parallel agents committing in the same tree: this repo is worked on by multiple agents (GrokBuild via Orca, Hermes). A concurrent commit can sweep your staged changes into someone else's commit and change the HEAD you snapshotted against. The write side races too: a parallel git checkout/reset can revert a file you already wrote back to its pre-edit content without you noticing (the edit appears in git history but not on disk) — after any batch of writes to a tree other agents also work in, re-read at least one touched file to confirm the new content is on disk before declaring the edit done. After any snapshot and before committing, re-run git log --oneline -4 and git status; re-verify on-disk state before executing; keep your commit scoped to your own task files only — never git add -A. | Prevents lost writes and HEAD sweep between concurrent agents. | Re-read at least one touched file after writes; re-run git log --oneline -4 and git status after snapshot and before commit; commit scoped to own task files only; never git add -A. | ||
| R24 | Staging discipline: the index is shared with every parallel agent — git add <path> stages your path plus everything a concurrent agent already staged, and git add -A . inside skills/<category>/ stages every tracked file under that subdirectory, not just the change's changes. Use explicit top-level paths (git add skills/<category>/ skills/catalog.json), then verify the staged set with git diff --cached --name-only before committing; it will routinely list non-task files. Unstage those with git reset HEAD -- <each non-task path> (targeted, never git reset HEAD -- . mid-run — that can unstage another agent's work and, if their content is on disk, reverts files to pre-edit state). Verify after every reset round: each git reset HEAD -- printout lists the index state left behind — files an agent staged after your last check reappear there; keep looping add → diff --cached → reset until the staged set is exactly your task files, then git commit (never -a, which commits the whole shared index) — after commit, git show --stat must list only your files. If you must clear the whole index, re-stage your task files first, then commit them before anything else touches the index. | Prevents accidentally committing another agent's staged work. | Explicit top-level paths only; staged set verified with git diff --cached --name-only; non-task files unstaged individually; staged set exactly task files before commit; git commit never -a; git show --stat lists only own files after commit. | ||
| R25 | Lane delegation for coding skills. When authoring or improving a skill that involves coding, never have Hermes implement inline or spawn its own subagent for the coding work. Structure the skill so Hermes (the orchestrator) plans, triages/verifies, and ships — while Grok Build (via an Orca worktree, --agent grok) does all implementation inside its own worktree. The SKILL.md body must carry this as an always-on rule: Hermes drops one self-contained brief (/<skill> <argument-hint>) into Grok per worktree, waits for TUI idle, then verifies inside the worktree path (child self-report is not evidence). Every coding skill therefore needs two reference lanes: references/hermes/ (plan → spawn → wait → verify → ship) and references/grok/ (implement → verify → rebase per worktree). The lane is chosen by who is reading the skill, not by a flag. | Keeps Hermes as orchestrator only; all implementation delegated to Grok Build via Orca worktrees. | Hermes drops one brief per worktree; waits for TUI idle; verifies inside worktree path; two lanes references/hermes/ and references/grok/ present for coding skills. | ||
| R26 | mkdir -p before git mv into a subdirectory. git mv file.md references/grok/file.md fails per-file with fatal: renaming ... failed: No such file or directory when references/grok/ does not exist yet, and a failed first git mv aborts the whole chain with nothing moved. Always mkdir -p the destination directory before the git mv chain. | Prevents git mv chain aborts from missing destination directories. | mkdir -p destination directory before every git mv chain into a subdirectory. | ||
| R27 | patch escape-drift on \" sequences. A patch old_string/new_string containing backslash-quote (\") can fail with Escape-drift detected. When that happens, read the full file and use write_file to replace it entirely instead of retrying patch. | Escape-drift fails patches silently; retrying wastes time. | On Escape-drift detected, read full file and use write_file to replace entirely; do not retry patch. | ||
| R28 | Verify __file__-based pack roots resolve to skills/ itself. default_pack_root() must return a path whose parents[N] IS skills/ — do not append "/skills" after it, which doubles the final segment into the non-existent skills/skills. Probe the helper in Python before running sdc catalog --build; a wrong root aborts every pack-reading command with ERROR: Skills root does not exist. | A __file__-based root that appends the segment it already resolves to breaks sdc catalog --build and every command that reads the skill pack. | default_pack_root().name == "skills" and .is_dir(); sdc catalog --build prints Rebuilt .../skills/catalog.json. |
Routing
###Improve reference files
| File | Purpose |
references/create/step-0-overview.md | Create mode overview |
references/create/step-1-gather.md | Gather job context before creating |
references/create/step-2-trigger-fields.md | Trigger fields (when-to-use, argument-hint) |
references/create/step-3-directory.md | Skill directory placement |
references/create/step-4-writer.md | Writer conventions |
references/create/step-5-write-skill.md | Write the SKILL.md |
references/create/step-6-verify.md | Verify the created skill |
Improve reference files
| File | Purpose | ||
references/improve/step-0-overview.md | Improve mode overview | ||
references/improve/step-1-scope.md | Scope the improvement | ||
references/improve/step-10-information-distribution.md | Information distribution | ||
references/improve/step-11-reference-pattern.md | Reference pattern rules | ||
references/improve/step-12-apply.md | Apply edits | ||
references/improve/step-13-pattern-b-variants.md | Restructure into Pattern B `step-<N>[a | b | c]` variants |
references/improve/step-2-body-format.md | Body format | ||
references/improve/step-3-frontmatter-keys.md | Frontmatter keys | ||
references/improve/step-4-validator-catalog.md | Validator rule catalog | ||
references/improve/step-5-naming-detail.md | Naming detail | ||
references/improve/step-6-description-detail.md | Description detail | ||
references/improve/step-7-content-detail.md | Content detail | ||
references/improve/step-8-prepublish-checklist.md | Pre-publish checklist | ||
references/improve/step-9-category-placement.md | Category placement |
Prune reference
| File | Purpose |
references/prune/step-0-overview.md | Prune mode overview |
references/prune/step-1-confirm-root.md | Confirm prune root |
references/prune/step-2-inventory.md | Inventory skills |
references/prune/step-3-group.md | Group overlapping skills |
references/prune/step-4-classify.md | Classify groups |
references/prune/step-5-dry-run.md | Dry-run report |
references/prune/step-6-snapshot.md | Snapshot before prune |
references/prune/step-7-execute.md | Execute prune |
references/prune/step-8-verify-report.md | Verify report |
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.