Skip to content

/cs-write-a-skill

Slash Command Source

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

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