claude-skills/engineering/write-a-skill
Claude 6278f7302d
fix(skills): rewrite descriptions of 111 skills that never auto-triggered
A trigger sweep of all 389 skills (Sonnet, Claude Code 2.1.317, 2 realistic
prompts + 1 near miss each) found 112 skills that fired on neither prompt.
Their descriptions now lead with the job in the words a user types and name
the situations that should load the skill ("Use whenever the user ..."),
with script names dropped to stay within each old length (G12 unchanged or
smaller). reflect is left as is: its pilot rewrite measured worse.

Also: run_evals.py --trigger-only for sweeps, a trigger case for design-qa,
and plugin versions bumped for every changed plugin (G11).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01L8KYFKBwgFwRBdcBaR6xCa
2026-11-03 10:41:50 +00:00
..
.claude-plugin fix(skills): rewrite descriptions of 111 skills that never auto-triggered 2026-11-03 10:41:50 +00:00
agents fix: v2.14.0 audit P0/P1 fixes (plugin updates, Codex, mirrors, script paths, two script bugs) (#1048) 2026-10-22 09:50:05 +02:00
commands fix(commands): hide skill-wrapper commands from the model's skill listing 2026-10-30 17:14:41 +00:00
skills/write-a-skill fix(write-a-skill): checklist requires a leading trigger, drops false-positive synonym pairs 2026-10-30 17:27:06 +00:00
vendor fix: v2.14.0 audit P0/P1 fixes (plugin updates, Codex, mirrors, script paths, two script bugs) (#1048) 2026-10-22 09:50:05 +02:00
README.md fix: close remaining v2.14.0 audit P2 items 2026-10-26 12:56:55 +00:00

write-a-skill

Skill-author skill: create new agent skills with proper structure, progressive disclosure, and bundled resources.

Attribution

Derived from Matt Pocock's write-a-skill (MIT-licensed). Matt's skills repo — "Skills for Real Engineers. Straight from my .claude directory" — is the original source. Matt's SKILL.md voice + 3-phase workflow (Gather → Draft → Review) preserved verbatim per his MIT license.

What this adds on top of Matt's original

Addition Where Why
3 stdlib Python validation tools skills/write-a-skill/scripts/ Operationalize Matt's review checklist (description validator, structure validator, review-checklist runner). Catches the common mistakes Matt names.
3 in-depth references (5+ sources each) skills/write-a-skill/references/ Progressive disclosure principles · Description design patterns · Quality gates for skills. Cites Anthropic skill docs + community precedent + research.
cs-skill-author persona agent agents/cs-skill-author.md Surface skill-authoring as a forcing-question interrogation matching our cs-* persona pattern.
/cs-write-a-skill slash command commands/cs-write-a-skill.md 6-question forcing interrogation that runs Matt's review checklist programmatically.

What Matt's original brings (preserved)

  • The 3-phase workflow: Gather → Draft → Review
  • The non-negotiable description rule: "The description is the only thing your agent sees when deciding which skill to load."
  • The 100-line SKILL.md ceiling + progressive-disclosure pattern (REFERENCE.md / EXAMPLES.md / scripts)
  • The good-example vs bad-example contrast for description writing
  • The 6-item review checklist
  • Matt's directness — no fluff, concrete patterns

Quick start

/plugin marketplace add alirezarezvani/claude-skills
/plugin install write-a-skill@claude-code-skills
# Run Matt's review checklist on an existing skill
python skills/write-a-skill/scripts/skill_review_checklist_runner.py path/to/SKILL.md

# Validate description meets Matt's criteria (≤1024 chars, third person, "Use when" trigger)
python skills/write-a-skill/scripts/skill_description_validator.py path/to/SKILL.md

# Validate skill folder structure
python skills/write-a-skill/scripts/skill_structure_validator.py path/to/skill-folder/

All three tools run with embedded samples if no path provided.

License

MIT (matching Matt's upstream).