writing-skills

Constraints {
  require {
    Verify before committing — run frontmatter check, structure check, word count
    Define clear output format in every skill
    Test discipline-enforcing skills with pressure scenarios (3+ combined pressures)
    Use imperative steps, not declarative statements
  }
  never {
    Create a skill without checking for existing duplicates first — if >50% overlap, update existing skill
    Commit a skill without verification (frontmatter check, structure check, test)
    Write declarative-only skills — workflow steps must be imperative
    Summarize workflow in the description — description is for triggers only, not execution
    Skip testing with "I can see the fix is correct" or "it's just a small change" — analysis != verification
    Create skills over 500 lines — extract to reference.md
  }
}

# Search skill directories
find ~/.claude/skills -name "SKILL.md" -exec grep -l "[keyword]" {} \;
find plugins/*/skills -name "SKILL.md" -exec grep -l "[keyword]" {} \;

# Search skill descriptions
grep -r "description:" plugins/*/skills/*/SKILL.md | grep -i "[topic]"

---
name: kebab-case-name                    # Lowercase, numbers, hyphens (max 64 chars)
description: What it does and when to use it  # Max 1024 chars
allowed-tools: Tool1, Tool2              # Tools without permission prompts (optional)
disable-model-invocation: false          # true = only user can invoke (optional)
user-invocable: true                     # false = hides from / menu (optional)
context: fork                            # Run in subagent (optional)
agent: Explore                           # Subagent type when context: fork (optional)
---

# Verb phrase (action-oriented)
description: Explains code with visual diagrams and analogies. Use when explaining how code works.

# Trigger-focused
description: Use when creating new skills, editing existing skills, or auditing skill quality.

# Capability statement
description: API design patterns for this codebase. Applies when writing API endpoints.

## When to Activate
[Bullet list of triggers - be specific]

## Core Principle
[One sentence - the key insight]

## [Main Workflow Section]
[Numbered steps or decision flow]
[Use flowcharts ONLY for non-obvious decisions]

## Output Format
[What the agent should produce when done]

$ARGUMENTS         # All arguments passed when invoking
$ARGUMENTS[0]      # First argument (or use $0 shorthand)
${CLAUDE_SESSION_ID}  # Current session ID
!`shell command`   # Execute command, insert output (preprocessing)

# Verify frontmatter
head -10 path/to/SKILL.md

# Check structure exists
grep -E "^## " path/to/SKILL.md

# Word count (target <500 words for core skills)
wc -w path/to/SKILL.md

# Read the skill
cat path/to/SKILL.md

# Check related files
ls -la path/to/skill/

# Find usages if applicable
grep -r "skill-name" plugins/ ~/.claude/

The security review should check for SQL injection vulnerabilities.

## Step 2: Security Review
1. Run `grep -r "query\|sql" src/` to find database queries
2. Check each query for string interpolation (vulnerability)
3. Report findings in security format

allowed-tools: Task, Bash, Read
---
[skill body never mentions how to use tools]

allowed-tools: Task, Bash, Read
---
## Step 1: Gather Code
Use Bash: `git diff --cached` to get staged changes

## Step 2: Launch Reviewers
Use Task tool to launch security reviewer with this prompt:
[specific prompt]

description: Coordinates code review by launching four specialized subagents then synthesizing findings

description: Use when reviewing code changes, PRs, or staged files. Handles security, performance, quality, and test analysis.

| Excuse | Reality |
|--------|---------|
| "Just this once" | Exceptions become habits. No exceptions. |
| "It's obvious" | Obvious to you ≠ clear to agents. Test it. |

## Red Flags - STOP
If you think any of these, stop and follow the full workflow:
- [List specific rationalizations that indicate violation]