mirror of https://github.com/alirezarezvani/claude-skills.git synced 2026-09-07 08:26:02 +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

4.9 KiB

Raw Permalink Blame History

name	description
cs-write-a-skill	/cs:write-a-skill <name-or-description> — Author a new agent skill with Matt Pocock's 3-phase workflow (Gather → Draft → Review). Runs 6 review-checklist items + 3 validator tools as a gate. Use when starting a new skill in this repo.

/cs:write-a-skill — Skill-Author Forcing Questions

Command: /cs:write-a-skill <name-or-description>

The skill-author persona pressure-tests any new-skill commit. Six forcing questions before any merge, matching Matt Pocock's review checklist.

When to Run

Starting a new skill from scratch
Deriving a skill from an upstream (MIT-licensed) source
Auditing an existing skill against current standards
Reviewing a new-skill PR before merge

The Six Skill-Author Questions

1. What's the description, and does it pass Matt's 4-rule test?

The description is the only thing your agent sees when deciding to load this skill.

Max 1024 chars
Third person (no I / you / we)
First sentence: what it does (action verb)
Second sentence: "Use when [specific triggers]"
Run skill_description_validator.py

2. Is SKILL.md under 100 lines?

Over 100 lines = over-conditioning + reference soup downstream.

If yes: great, ship it
If no: split workflows into references/<topic>.md; replace inline content with 1-2 line pointers
Wrapper-derived skills (preserving upstream content) get a documented exception

3. Are there time-sensitive claims?

Dates rot. "As of October 2024" becomes wrong by next year.

Remove: "as of YYYY", "in YYYY", "released YYYY", "updated YYYY"
Replace with: pattern description that doesn't depend on date
Example: not "ISO 42001 published December 2023"; use "ISO 42001 (the first AI management-system standard)"

4. Is terminology consistent?

Synonym drift confuses agents + readers.

Pick one: agent OR bot, skill OR tool, user OR developer
Use the chosen term throughout
Document the choice in a glossary if multiple stakeholders involved

5. Are there at least 2 concrete examples (good + bad if possible)?

Without examples, agents construct from scratch and hallucinate.

At least 1 code block
Ideally good/bad contrast (Matt's pattern)
Examples must be runnable or copy-pasteable

6. Are references one level deep + no circular refs?

Deep nesting = agent gives up resolving the chain.

Flat references/<topic>.md layout
No references/category/subtopic.md
No A→B→A cycles
Run skill_structure_validator.py

Workflow

# 1. Description gate
python ../skills/write-a-skill/scripts/skill_description_validator.py path/to/SKILL.md

# 2. Structure gate
python ../skills/write-a-skill/scripts/skill_structure_validator.py path/to/skill-folder/

# 3. Combined review (Matt's 6-item checklist)
python ../skills/write-a-skill/scripts/skill_review_checklist_runner.py path/to/skill-folder/

# 4. Karpathy code-quality gate (if scripts/ exist)
python ../../karpathy-coder/skills/karpathy-coder/scripts/complexity_checker.py path/to/skill-folder/scripts/
python ../../karpathy-coder/skills/karpathy-coder/scripts/assumption_linter.py path/to/skill-folder/scripts/

# 5. Attribution check (if derived)
grep -r "derived_from\|original_author" path/to/skill-folder/

Output Format

# Skill Author Review: <skill-name>
**Date:** YYYY-MM-DD

## The Decision Being Made
[gather | draft | review | validate | derive | audit]

## Description Validation
- Length: N chars (limit 1024): pass/fail
- Third person: pass/fail
- "Use when" trigger: pass/fail
- Action verb in first sentence: pass/fail

## Structure Validation
- SKILL.md present + ≤100 lines: pass/fail (N lines)
- References one level deep: pass/fail
- No circular refs: pass/fail
- scripts/ folder: present/absent (optional)

## Review Checklist (Matt's 6 items)
- [x|/] 1. Description includes triggers
- [x|/] 2. SKILL.md under 100 lines
- [x|/] 3. No time-sensitive info
- [x|/] 4. Consistent terminology
- [x|/] 5. Concrete examples included
- [x|/] 6. References one level deep

## Karpathy Code Gate (if applicable)
- complexity_checker: PASS / WARN (with findings)
- assumption_linter: CLEAN / NOISY

## Attribution (if derived skill)
- Upstream link: present/missing
- License compatibility: yes/no
- Author credit: present/missing

## Verdict
🟢 SHIP | 🟡 WARN-WITH-JUSTIFICATION | 🔴 BLOCK

## Top 3 Actions (if not green)
[3 concrete fixes with file:line references]

Routing

/cs:karpathy-check — for code-quality concerns in scripts/
/cs:tdd — for testing discipline (different from skill quality gates)
/cs:decide — to log the verdict

Agent: cs-skill-author
Skill: write-a-skill
Adjacent: ../../karpathy-coder/, ../../autoresearch-agent/

Version: 1.0.0 Derived: Matt Pocock's write-a-skill (MIT) + this repo's wrapper

4.9 KiB Raw Permalink Blame History