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
