alirezarezvani--claude-skills/docs/commands/cs-write-a-skill.md

title, description

title	description
/cs-write-a-skill — Slash Command for AI Coding Agents	/cs:write-a-skill <name-or-description> — Author a new agent skill with Matt Pocock's 3-phase workflow (Gather → Draft → Review). Runs 6. Slash command for Claude Code, Codex CLI, Gemini CLI.

/cs-write-a-skill

:material-console: Slash Command :material-github: 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

Related

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

---

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