mirror of https://github.com/alirezarezvani/claude-skills.git synced 2026-09-06 08:15:58 +00:00

feat(write-a-skill): derive from Matt Pocock (MIT) + add validation wrapper

Stream B PR 1 of 2 — the skill-author skill that gives us the meta-tool to
build the rest of Matt Pocock's productivity skills (caveman, grill-me, handoff)
with consistent quality gates.

Derived from Matt Pocock's write-a-skill (MIT-licensed):
https://github.com/mattpocock/skills/tree/main/skills/productivity/write-a-skill

Matt's SKILL.md content + 3-phase workflow (Gather -> Draft -> Review) preserved
verbatim per MIT license. Attribution: README.md + plugin.json description +
SKILL.md frontmatter metadata + every file footer cites Matt + links to original.

Additions on top of Matt's original (the "hybrid voice" approach):

3 stdlib Python validation tools:
- skill_description_validator.py: 5-check verdict per Matt's 4 format rules
  (description present, <=1024 chars, third person, "Use when" trigger, action
  verb in first sentence). Action-verb vocabulary extracted as module constant.
- skill_structure_validator.py: 6-check verdict (SKILL.md present, line count,
  references when split needed, one-level-deep, no circular refs, scripts/
  folder note). Refactored to extract _list_md_in_subdir + _collect_links_for_file
  helpers to keep nesting depth <= 4 per karpathy-coder.
- skill_review_checklist_runner.py: combined verdict running all 6 items from
  Matt's review checklist. Refactored _find_nested_md helper for nesting.

4 in-depth references (each citing 7-8 authoritative sources):
- companion_tooling.md: tool catalogue + cs-* wrapper rationale
- progressive_disclosure_principles.md: 100-line ceiling + one-level-deep rule
  with sources (Matt, Anthropic, Don Norman, Pirolli & Card, Maeda, DocOps)
- description_design_patterns.md: good vs bad description patterns with sources
  (Matt, Anthropic, Garrett, Nielsen Norman, Karpathy)
- quality_gates_for_skills.md: the 6 mandatory gates + CI integration with
  sources (Matt, Humble & Farley, Kim et al., Hyrum's Law)

cs-skill-author persona agent + /cs:write-a-skill slash command:
- Forcing-question interrogator pattern matching our cs-* convention
- 6 forcing questions mirroring Matt's 6 review-checklist items
- Routes to validators + karpathy-coder gate + attribution check

Karpathy-coder validation (full sweep):
- complexity_checker: 100/100 across all 3 tools (0 findings)
- assumption_linter: CLEAN on all 3 tools
- All 3 tools: PASS text + PASS JSON output
- All 4 references cite >= 7 authoritative sources (range 7-8)

Self-validation note: this skill's own SKILL.md is 141 lines (over Matt's
100-line ceiling) because it preserves Matt's full content verbatim + adds
attribution + tooling references. The structure_validator + checklist_runner
correctly WARN on this — documented in progressive_disclosure_principles.md
as the wrapper-derived exception. README.md absorbs the attribution overhead
so SKILL.md stays close to Matt's original size.

12 files, 1,689 insertions. License: MIT (matching Matt's upstream).

https://claude.ai/code/session_01VFreMf7XLBqMgjsrG4wSYe

2026-05-13 21:26:44 +00:00

2.4 KiB

Raw Permalink Blame History

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

# 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).

2.4 KiB Raw Permalink Blame History