skill-forge

Original source / Raw SKILL.md

---
name: skill-forge
description: "Create high-quality, production-grade skills for Claude Code. Expert guidance on skill architecture, workflow design, prompt engineering, and packaging. Use when user wants to create a new skill, build a skill, design a skill, write a skill, update an existing skill, improve a skill, refactor a skill, debug a skill, or package a skill. Triggers: 'create skill', 'build skill', 'new skill', 'skill creation', 'write a skill', 'make a skill', 'design a skill', 'improve skill', 'package skill', 'skill development', 'skill template', 'skill best practices', 'write SKILL.md'."
---

# Skill Forge

IRON LAW: Every line in a skill must justify its token cost. If it doesn't make the model's output better, more consistent, or more reliable — cut it.

## What is a Skill

A skill is an "onboarding guide" for Claude — transforming it from a general-purpose agent into a specialized one with procedural knowledge, domain expertise, and bundled tools.

```
skill-name/
├── SKILL.md           # Required: workflow + instructions (<500 lines)
├── scripts/           # Optional: deterministic, repeatable operations
├── references/        # Optional: loaded into context on demand
└── assets/            # Optional: used in output, never loaded into context
```

**Default assumption: Claude is already very smart.** Only add what Claude doesn't already know. Challenge every paragraph: "Does this justify its token cost?"

## Workflow

Copy this checklist and check off items as you complete them:

```
Skill Forge Progress:

- [ ] Step 1: Understand the Skill ⚠️ REQUIRED
  - [ ] 1.1 Clarify purpose and concrete use cases
  - [ ] 1.2 Collect 3+ concrete usage examples
  - [ ] 1.3 Identify trigger scenarios and keywords
- [ ] Step 2: Plan Architecture
  - [ ] 2.1 Identify reusable resources (scripts, references, assets)
  - [ ] 2.2 Design progressive loading strategy
  - [ ] 2.3 Design parameter system (if applicable)
- [ ] Step 3: Initialize ⛔ BLOCKING (skip if skill already exists)
  - [ ] Run init_skill.py
- [ ] Step 4: Write Description
  - [ ] Load references/description-guide.md
  - [ ] Apply keyword bombing technique
- [ ] Step 5: Write SKILL.md Body
  - [ ] 5.1 Set Iron Law
  - [ ] 5.2 Design workflow checklist
  - [ ] 5.3 Add confirmation gates
  - [ ] 5.4 Add parameter system (if applicable)
  - [ ] 5.5 Apply writing techniques
  - [ ] 5.6 Add anti-patterns list
  - [ ] 5.7 Add pre-delivery checklist
- [ ] Step 6: Build Resources
  - [ ] 6.1 Implement and test scripts
  - [ ] 6.2 Write reference files
  - [ ] 6.3 Prepare assets
- [ ] Step 7: Review ⚠️ REQUIRED
  - [ ] Run pre-delivery checklist (Step 9)
  - [ ] Present summary to user for confirmation
- [ ] Step 8: Package
  - [ ] Run package_skill.py
- [ ] Step 9: Iterate based on real usage
```

## Step 1: Understand the Skill ⚠️ REQUIRED

Ask yourself:
- What specific problem does this skill solve that Claude can't do well on its own?
- What would a user literally type to trigger this skill?
- What are 3-5 concrete usage examples with realistic inputs and expected outputs?

If unclear, ask the user (don't ask everything at once — start with the most critical):
- "Can you give me 3 examples of how you'd use this skill?"
- "What would you literally say to trigger it?"
- "What does a good output look like?"

Do NOT proceed until you have at least 3 concrete examples.

## Step 2: Plan Architecture

For each concrete example, ask:
1. What operations are deterministic and repeatable? → `scripts/`
2. What domain knowledge does Claude need at specific steps? → `references/`
3. What files are used in output but not in reasoning? → `assets/`

Key constraints:
- SKILL.md must stay under 500 lines — everything else goes to `references/`
- References organized by domain, one level of nesting only
- Load references/architecture-guide.md for progressive loading patterns and organization strategies

## Step 3: Initialize ⛔ BLOCKING

Skip if working on an existing skill. Otherwise run:

```bash
python3 scripts/init_skill.py <skill-name> --path <output-directory>
```

The script creates a template with Iron Law placeholder, workflow checklist, and proper directory structure.

## Step 4: Write Description

This is the most underestimated part of a skill. The description determines:
1. Whether the skill triggers automatically
2. Whether users find it by search

Load references/description-guide.md for the keyword bombing technique and good/bad examples.

Key rule: NEVER put "When to Use" info in the SKILL.md body. The body loads AFTER triggering — too late.

## Step 5: Write SKILL.md Body

Load reference files as needed for each sub-step:

### 5.1 Set Iron Law

Ask: "What is the ONE mistake the model will most likely make with this skill?"
Write a rule that prevents it. Place it at the top of SKILL.md, right after the frontmatter.

→ Load references/writing-techniques.md for Iron Law patterns and red flag signals.

### 5.2 Design Workflow Checklist

Create a trackable checklist with:
- ⚠️ REQUIRED for steps that must not be skipped
- ⛔ BLOCKING for prerequisites
- Sub-step nesting for complex steps
- (conditional) for steps that depend on earlier choices

→ Load references/workflow-patterns.md for checklist patterns and examples.

### 5.3 Add Confirmation Gates

Force the model to stop and ask the user before:
- Destructive operations (delete, overwrite, modify)
- Generative operations with significant cost
- Applying changes based on analysis

→ Load references/workflow-patterns.md for confirmation gate patterns.

### 5.4 Add Parameter System (if applicable)

If the skill benefits from flags like `--quick`, `--style`, `--regenerate N`:

→ Load references/parameter-system.md for $ARGUMENTS, flags, argument-hint, and partial execution patterns.

### 5.5 Apply Writing Techniques

Three techniques that dramatically improve output quality:

1. **Question-style instructions**: Give questions, not vague directives
2. **Anti-pattern documentation**: List what NOT to do
3. **Iron Law + Red Flags**: Prevent the model from taking shortcuts

→ Load references/writing-techniques.md for all three with examples.

### 5.6 Add Anti-Patterns List

Ask: "What would Claude's lazy default look like for this task?" Then explicitly forbid it.

→ Load references/writing-techniques.md for anti-pattern examples.

### 5.7 Add Pre-Delivery Checklist

Add concrete, verifiable checks. Each item must be specific enough that the model can check it by looking at the output. Not "ensure good quality" but "no placeholder text remaining (TODO, FIXME, xxx)."

→ Load references/output-patterns.md for checklist patterns and priority-based output.

### Writing Principles

- **Concise**: Only add what Claude doesn't already know
- **Imperative form**: "Analyze the input" not "You should analyze the input"
- **Match freedom to fragility**: Narrow bridge → specific guardrails; open field → many routes
  - High freedom (text): multiple valid approaches
  - Medium (pseudocode/params): preferred pattern, some variation OK
  - Low (specific scripts): fragile operations, consistency critical

## Step 6: Build Resources

### Scripts
- Encapsulate deterministic, repeatable operations
- Scripts execute without loading into context — major token savings
- Test every script before packaging
- In SKILL.md, document only the command and arguments, not the source code

### References
- Organize by domain, not by type
- One level of nesting only
- Each file referenced from SKILL.md with clear "when to load" instructions
- Large files (>100 lines) should have a table of contents at the top

### Assets
- Templates, images, fonts used in output
- Not loaded into context, just referenced by path

→ Load references/architecture-guide.md for detailed patterns.

## Step 7: Review ⚠️ REQUIRED

Present the skill summary to the user and confirm before packaging.

### Pre-Delivery Checklist

#### Structure
- [ ] SKILL.md under 500 lines
- [ ] Frontmatter has `name` and `description` only (plus optional `allowed-tools`, `license`, `metadata`)
- [ ] Description includes trigger keywords and usage scenarios
- [ ] No README.md, CHANGELOG.md, or other unnecessary files
- [ ] No example/placeholder files left from initialization

#### Quality
- [ ] Has an Iron Law or core constraint at the top
- [ ] Has a trackable workflow checklist with ⚠️/⛔ markers
- [ ] Confirmation gates before destructive/generative operations
- [ ] Uses question-style instructions, not vague directives
- [ ] Lists anti-patterns (what NOT to do)
- [ ] References loaded progressively, not all upfront

#### Resources
- [ ] Scripts tested and executable
- [ ] References organized by domain, one level deep
- [ ] Large references have table of contents
- [ ] Assets used in output, not loaded into context

#### Anti-Patterns to Avoid
- Stuffing everything into one massive SKILL.md (>500 lines)
- Vague description like "A tool for X"
- No workflow — letting the model freestyle
- No confirmation gates — model runs unchecked to completion
- Vague instructions like "ensure good quality" instead of specific checks
- Including README.md, INSTALLATION_GUIDE.md, or other documentation files
- "When to Use" info in the body instead of the description field

## Step 8: Package

```bash
python3 scripts/package_skill.py <path/to/skill-folder> [output-directory]
```

Validates automatically before packaging. Fix errors and re-run.

## Step 9: Iterate

After real usage:
1. Notice where the model struggles or is inconsistent
2. Identify which workflow step needs improvement
3. Add more specific instructions, examples, or anti-patterns
4. Re-test and re-package


---

## Referenced Files

> The following files are referenced in this skill and included for context.

### references/description-guide.md

```markdown
# Writing Killer Skill Descriptions

## Why Description Matters

The `description` field in frontmatter is the ONLY thing Claude reads before deciding to trigger your skill. The SKILL.md body loads AFTER triggering. So "When to Use This Skill" sections in the body are useless for triggering.

Two things description controls:
1. Whether the skill triggers automatically
2. Whether users find it by search

## The Keyword Bombing Technique

List every possible trigger scenario — actions, objects, synonyms, and natural language phrases the user would literally say.

### Four Dimensions of a Great Description

1. **Core capability** — what it does (first sentence)
2. **Action verbs** — what users ask to do
3. **Object nouns** — what users mention
4. **Natural phrases** — what users would literally type

### Excellent Examples

**ui-ux-pro-max:**
```yaml
description: "UI/UX design intelligence. 50 styles, 21 palettes,
50 font pairings, 20 charts, 8 stacks (React, Next.js, Vue, Svelte,
SwiftUI, React Native, Flutter, Tailwind). Actions: plan, build,
create, design, implement, review, fix, improve, optimize, enhance,
refactor, check UI/UX code. Projects: website, landing page,
dashboard, admin panel, e-commerce, SaaS, portfolio, blog, mobile app.
Styles: glassmorphism, claymorphism, minimalism, brutalism..."
```

This is a "trigger keyword net" — no matter what the user says about UI, it hits.

**excalidraw-artist:**
```yaml
description: "Create beautiful, elegant Excalidraw diagrams based on
user intent. Use when user asks to draw, visualize, diagram, sketch,
illustrate concepts, create flowcharts, architecture diagrams, mind maps,
process flows, or any visual representation. Triggers on keywords like
'draw', 'diagram', 'visualize', 'sketch', 'flowchart', 'architecture',
'mind map', 'illustrate'."
```

Explicitly lists trigger keywords in natural language.

### Bad vs Good

```yaml
# Bad — too vague, won't trigger reliably
description: "代码审查工具"

# Good — covers natural language triggers
description: "代码审查与质量分析。当用户说'帮我 review'、'检查代码'、
'审查 PR'、'看看这段代码有没有问题'时使用。支持 Python、JavaScript、
TypeScript、Go、Rust。Actions: review, check, audit, inspect, analyze
code quality, find bugs, security review."
```

```yaml
# Bad — generic
description: "Helps create presentations"

# Good — keyword-rich
description: "Generate professional slide decks from content. Creates
outlines with style instructions, then generates individual slide images.
Use when user asks to 'create slides', 'make a presentation', 'generate
deck', 'slide deck', 'PPT', 'make slides from article', 'turn this into
a presentation'."
```

## Checklist

- [ ] First sentence states core capability
- [ ] 5+ action verbs listed
- [ ] 5+ object nouns / project types listed
- [ ] Natural language trigger phrases included
- [ ] Under 1024 characters
- [ ] No angle brackets (`<` or `>`)
- [ ] All "when to use" info is HERE, not in SKILL.md body

## Key Rule

NEVER put "When to Use This Skill" in the SKILL.md body. The body only helps AFTER triggering — which is too late. All trigger information belongs in the `description` field.

```

### scripts/init_skill.py

```python
#!/usr/bin/env python3
"""
Skill Initializer - Creates a new skill from template with best-practice structure.

Usage:
    init_skill.py <skill-name> --path <path>

Examples:
    init_skill.py my-new-skill --path skills/public
    init_skill.py my-api-helper --path skills/private
    init_skill.py custom-skill --path /custom/location
"""

import sys
from pathlib import Path


SKILL_TEMPLATE = """---
name: {skill_name}
description: "[TODO: Write a keyword-rich description. Include: (1) core capability in first sentence, (2) 5+ action verbs users might say, (3) 5+ object nouns, (4) natural language trigger phrases. See references/description-guide.md for examples. ALL trigger info goes HERE, not in the body.]"
---

# {skill_title}

[TODO: Write your Iron Law here. Ask: "What is the ONE mistake the model will most likely make?" Then write an unbreakable rule to prevent it.]

IRON LAW: [TODO: e.g., "NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST."]

## Workflow

Copy this checklist and check off items as you complete them:

```
{skill_title} Progress:

- [ ] Step 1: [TODO: First step] ⚠️ REQUIRED
  - [ ] 1.1 [TODO: Sub-step]
  - [ ] 1.2 [TODO: Sub-step]
- [ ] Step 2: Confirm with user ⚠️ REQUIRED
- [ ] Step 3: [TODO: Core operation]
- [ ] Step 4: [TODO: Output / delivery]
```

## Step 1: [TODO: First Step]

[TODO: Use question-style instructions, not vague directives.
Instead of "Check for problems", write "Ask: What happens if this value is null?"]

## Step 2: Confirm ⚠️ REQUIRED

[TODO: Present findings/plan to user before proceeding. Options:]
- Proceed with all?
- Only high-priority items?
- Select specific items?
- View only, no changes?

⚠️ Do NOT proceed without user confirmation.

## Step 3: [TODO: Core Operation]

[TODO: The main work of the skill. Load references as needed:]
- Load references/[TODO].md for [specific purpose]

## Step 4: [TODO: Output]

[TODO: Define output format and structure]

## Anti-Patterns

[TODO: List what the model should NOT do. Ask: "What would Claude's lazy default look like?"]
- [TODO: e.g., Don't use purple/blue gradients by default]
- [TODO: e.g., Don't add unnecessary try-catch blocks]

## Pre-Delivery Checklist

[TODO: Add concrete, verifiable checks — not "ensure quality" but specific items]
- [ ] [TODO: e.g., No placeholder text remaining (TODO, FIXME)]
- [ ] [TODO: e.g., All generated code runs without errors]
- [ ] [TODO: e.g., Output matches requested format]
"""


def title_case_skill_name(skill_name):
    """Convert hyphenated skill name to Title Case for display."""
    return ' '.join(word.capitalize() for word in skill_name.split('-'))


def init_skill(skill_name, path):
    """
    Initialize a new skill directory with best-practice template.

    Args:
        skill_name: Name of the skill
        path: Path where the skill directory should be created

    Returns:
        Path to created skill directory, or None if error
    """
    skill_dir = Path(path).resolve() / skill_name

    if skill_dir.exists():
        print(f"Error: Skill directory already exists: {skill_dir}")
        return None

    try:
        skill_dir.mkdir(parents=True, exist_ok=False)
        print(f"Created skill directory: {skill_dir}")
    except Exception as e:
        print(f"Error creating directory: {e}")
        return None

    # Create SKILL.md from template
    skill_title = title_case_skill_name(skill_name)
    skill_content = SKILL_TEMPLATE.format(
        skill_name=skill_name,
        skill_title=skill_title
    ).lstrip('\n')

    skill_md_path = skill_dir / 'SKILL.md'
    try:
        skill_md_path.write_text(skill_content)
        print("Created SKILL.md")
    except Exception as e:
        print(f"Error creating SKILL.md: {e}")
        return None

    # Create resource directories (empty — user fills as needed)
    for dirname in ('scripts', 'references', 'assets'):
        (skill_dir / dirname).mkdir(exist_ok=True)
        print(f"Created {dirname}/")

    print(f"\nSkill '{skill_name}' initialized at {skill_dir}")
    print("\nNext steps:")
    print("1. Fill in all [TODO] items in SKILL.md")
    print("2. Write your description using the keyword bombing technique")
    print("3. Add scripts/, references/, assets/ as needed")
    print("4. Delete any empty resource directories you don't need")
    print("5. Run package_skill.py when ready")

    return skill_dir


def main():
    if len(sys.argv) < 4 or sys.argv[2] != '--path':
        print("Usage: init_skill.py <skill-name> --path <path>")
        print()
        print("Skill name requirements:")
        print("  - Hyphen-case (e.g., 'data-analyzer')")
        print("  - Lowercase letters, digits, and hyphens only")
        print("  - Max 64 characters")
        print()
        print("Examples:")
        print("  init_skill.py my-skill --path ./skills")
        print("  init_skill.py code-reviewer --path /custom/location")
        sys.exit(1)

    skill_name = sys.argv[1]
    path = sys.argv[3]

    print(f"Initializing skill: {skill_name}")
    print(f"Location: {path}")
    print()

    result = init_skill(skill_name, path)
    sys.exit(0 if result else 1)


if __name__ == "__main__":
    main()

```

### scripts/package_skill.py

```python
#!/usr/bin/env python3
"""
Skill Packager - Creates a distributable .skill file.

Usage:
    package_skill.py <path/to/skill-folder> [output-directory]

Example:
    package_skill.py ./my-skill
    package_skill.py ./my-skill ./dist
"""

import sys
import zipfile
from pathlib import Path
from quick_validate import validate_skill


def package_skill(skill_path, output_dir=None):
    """
    Package a skill folder into a .skill file.

    Args:
        skill_path: Path to the skill folder
        output_dir: Optional output directory for the .skill file

    Returns:
        Path to the created .skill file, or None if error
    """
    skill_path = Path(skill_path).resolve()

    if not skill_path.exists():
        print(f"Error: Skill folder not found: {skill_path}")
        return None

    if not skill_path.is_dir():
        print(f"Error: Path is not a directory: {skill_path}")
        return None

    skill_md = skill_path / "SKILL.md"
    if not skill_md.exists():
        print(f"Error: SKILL.md not found in {skill_path}")
        return None

    # Run validation before packaging
    print("Validating skill...")
    valid, message = validate_skill(skill_path)
    if not valid:
        print(f"Validation failed: {message}")
        print("Fix the errors before packaging.")
        return None
    print(f"{message}\n")

    # Determine output location
    skill_name = skill_path.name
    if output_dir:
        output_path = Path(output_dir).resolve()
        output_path.mkdir(parents=True, exist_ok=True)
    else:
        output_path = Path.cwd()

    skill_filename = output_path / f"{skill_name}.skill"

    try:
        with zipfile.ZipFile(skill_filename, 'w', zipfile.ZIP_DEFLATED) as zipf:
            for file_path in skill_path.rglob('*'):
                if file_path.is_file():
                    # Skip __pycache__ and .pyc files
                    if '__pycache__' in file_path.parts or file_path.suffix == '.pyc':
                        continue
                    arcname = file_path.relative_to(skill_path.parent)
                    zipf.write(file_path, arcname)
                    print(f"  Added: {arcname}")

        print(f"\nPackaged skill to: {skill_filename}")
        return skill_filename

    except Exception as e:
        print(f"Error creating .skill file: {e}")
        return None


def main():
    if len(sys.argv) < 2:
        print("Usage: package_skill.py <path/to/skill-folder> [output-directory]")
        print()
        print("Example:")
        print("  package_skill.py ./my-skill")
        print("  package_skill.py ./my-skill ./dist")
        sys.exit(1)

    skill_path = sys.argv[1]
    output_dir = sys.argv[2] if len(sys.argv) > 2 else None

    print(f"Packaging skill: {skill_path}")
    if output_dir:
        print(f"Output directory: {output_dir}")
    print()

    result = package_skill(skill_path, output_dir)
    sys.exit(0 if result else 1)


if __name__ == "__main__":
    main()

```



---

## Skill Companion Files

> Additional files collected from the skill directory layout.

### README.md

```markdown
# Skill Forge

Create high-quality Claude Code skills instead of AI-generated slop.

## The Problem

Most skills are just a big markdown file dumped into SKILL.md — no structure, no workflow, no quality control. The model reads a wall of text, loses focus on what matters, and produces inconsistent output.

Skill Forge fixes this by teaching you **12 battle-tested techniques** for skill design: how to manage context efficiently, how to guide the model step-by-step, and how to prevent it from taking shortcuts.

## What's Inside

| Technique | What It Solves |
|-----------|---------------|
| Progressive Loading | Context bloat — keep SKILL.md lean, load details on demand |
| Keyword Bombing | Skills that never trigger — write descriptions that actually match user intent |
| Workflow Checklist | Inconsistent execution — give the model a trackable path with ⚠️/⛔ markers |
| Script Encapsulation | Wasted tokens — wrap deterministic ops in scripts (zero context cost) |
| Question-Style Instructions | Vague output — ask specific questions instead of abstract directives |
| Confirmation Gates | Runaway execution — force the model to pause before critical operations |
| Pre-Delivery Checklist | Quality gaps — add concrete, verifiable checks before output |
| Parameter System | Inflexibility — support `--flags`, partial execution, `--quick` mode |
| Reference Organization | Loading irrelevant context — organize by domain, load only what's needed |
| CLI + Skill Pattern | MCP overhead — replace MCP Servers with CLI tools |
| Iron Law | Model shortcuts — set one unbreakable rule the model can never violate |
| Anti-Pattern Documentation | Default AI behavior — explicitly list what NOT to do |

## Install

```bash
npx skills add sanyuan0704/sanyuan-skills --path skills/skill-forge
```

## Usage

```
/skill-forge
```

Follow the guided workflow — from understanding requirements to packaging a distributable `.skill` file.

## Structure

```
skill-forge/
├── SKILL.md                          # Core workflow (<250 lines)
├── scripts/
│   ├── init_skill.py                 # Initialize new skill from template
│   ├── package_skill.py              # Package into .skill file
│   └── quick_validate.py             # Validate structure and frontmatter
└── references/                       # Loaded on demand, not upfront
    ├── description-guide.md          # How to write trigger-rich descriptions
    ├── workflow-patterns.md          # Checklists, confirmation gates, pre-delivery
    ├── writing-techniques.md         # Question prompting, iron laws, anti-patterns
    ├── architecture-guide.md         # Progressive loading, scripts, CLI+Skill
    ├── parameter-system.md           # $ARGUMENTS, flags, partial execution
    └── output-patterns.md            # Templates, examples, delivery checklists
```

## License

MIT

```

### references/architecture-guide.md

```markdown
# Skill Architecture Guide

## Progressive Loading

### The 500-Line Rule

SKILL.md must stay under 500 lines. Everything beyond that goes into `references/`.

Why? The context window is shared with system prompts, conversation history, user input, and other skill metadata. A bloated SKILL.md crowds out everything else.

**Bad:** A 2000-line SKILL.md with API docs, examples, and FAQ all in one file. The model reads all of it, and the truly important instructions get buried.

**Good:** A 150-line SKILL.md with clear workflow steps. Each step says "Load references/xxx.md" only when needed.

### Three-Level Loading

1. **Metadata (name + description)** — Always in context (~100 words)
2. **SKILL.md body** — Loaded when skill triggers (<500 lines)
3. **Bundled resources** — Loaded on demand (unlimited)

### Load-on-Demand Pattern

In SKILL.md, reference files only at the step where they're needed:

```markdown
## Step 3: Security Review

Load references/security-checklist.md and check each item against the code.
```

The model reads security-checklist.md only when it reaches Step 3 — not at the beginning.

### Progressive Disclosure Patterns

**Pattern 1: High-level guide with references**

```markdown
# PDF Processing

## Quick start
Extract text with pdfplumber:
[code example]

## Advanced features
- **Form filling**: See references/forms.md for complete guide
- **API reference**: See references/api.md for all methods
```

Claude loads forms.md or api.md only when needed.

**Pattern 2: Conditional details**

```markdown
# DOCX Processing

## Creating documents
Use docx-js for new documents. See references/docx-js.md.

## Editing documents
For simple edits, modify the XML directly.
**For tracked changes**: See references/redlining.md
```

Claude reads redlining.md only when the user needs tracked changes.

## Reference Organization

### Organize by Domain, Not by Type

```
# Bad — organized by type (everything in each folder gets loaded together)
references/
├── checklists/
├── templates/
└── examples/

# Good — organized by domain (only relevant domain gets loaded)
references/
├── palettes/          # 9 color schemes, one per file
├── renderings/        # 6 rendering styles, one per file
├── dimensions/        # Style dimensions
├── config/            # Configuration
└── workflow/          # Workflow details
```

When the user picks a specific palette, the model loads only that one file — not all 9.

### Multi-Framework Skills

```
cloud-deploy/
├── SKILL.md (workflow + provider selection)
└── references/
    ├── aws.md         # Loaded only when user chooses AWS
    ├── gcp.md         # Loaded only when user chooses GCP
    └── azure.md       # Loaded only when user chooses Azure
```

### Rules

1. **One level of nesting only.** All references reachable directly from SKILL.md.
2. **Clear "when to load" instructions.** SKILL.md says when each reference is needed.
3. **Large files (>100 lines) get a TOC** at the top so the model can preview scope.
4. **No duplication.** Information lives in SKILL.md OR references, not both.

## Script Encapsulation

### When to Use Scripts

Ask: "Is this operation deterministic and repeatable?" If yes → script it.

Examples:
- PDF rotation → `scripts/rotate_pdf.py`
- Design database search → `scripts/search.py`
- Image merging → `scripts/merge_images.py`
- File format conversion → `scripts/convert.py`

### Key Benefit: No Context Cost

Scripts execute without being loaded into context. The model only needs to know:
1. The script exists
2. What arguments it takes
3. What it returns

This saves massive context compared to the model writing the same code from scratch each time.

### Document Scripts Minimally in SKILL.md

```markdown
## Available Scripts

### scripts/search.py
Search the design database for matching styles.
Usage: `python3 scripts/search.py "<query>" --domain <color|font|layout>`
Returns: JSON array of matching entries with name, values, and usage notes.
```

The model calls it via Bash without reading the script's source code.

### Script Testing

Added scripts must be tested by actually running them. If there are many similar scripts, test a representative sample.

## CLI + Skill Pattern (MCP Alternative)

For capabilities that would traditionally require an MCP Server, consider: CLI tool + Skill.

### How It Works

Instead of an MCP Server with 20+ tool definitions in context, use:
- A CLI tool with clear commands
- A SKILL.md that teaches the model how to use it

### Example — Browser Automation

```bash
agent-browser open https://example.com
agent-browser snapshot -i
agent-browser click @e1
agent-browser fill @e2 "text"
```

SKILL.md lists the command reference. The model calls them via Bash.
Context savings: up to 93% compared to MCP approach.

### Security: Restrict Allowed Tools

Use `allowed-tools` in frontmatter to restrict what the skill can execute:

```yaml
allowed-tools: Bash(agent-browser:*)
```

The skill can ONLY run commands starting with `agent-browser` — nothing else.

### When to Choose CLI + Skill over MCP

- The tool has a clean command-line interface
- You want to minimize context usage
- The tool doesn't need bidirectional streaming
- You want simpler deployment (no server to run)

## What NOT to Include in a Skill

A skill should only contain files that directly support its functionality. Do NOT create:

- README.md
- INSTALLATION_GUIDE.md
- QUICK_REFERENCE.md
- CHANGELOG.md
- Any user-facing documentation

The skill is for an AI agent to do the job — not for humans to read about it.

```

### references/output-patterns.md

```markdown
# Output Patterns

## Template Pattern

Provide output templates to ensure consistency across runs.

### Strict Templates (for structured output)

When exact format matters (API responses, data exports, reports):

```markdown
## Output Format

For each issue found, output:

| Field | Format |
|-------|--------|
| severity | P0 / P1 / P2 / P3 |
| location | file:line |
| description | One sentence explaining the problem |
| suggestion | One sentence with the fix |
```

### Flexible Templates (for creative output)

When structure matters but content varies:

```markdown
## Output Structure

1. **Summary** (2-3 sentences): What was done and key findings
2. **Details**: Organized by category, most important first
3. **Next Steps**: Actionable items, prioritized
```

## Example Pattern

Show input/output pairs to demonstrate expected style and detail level. Examples are more effective than verbose explanations.

### Example — Commit Messages

```markdown
## Commit Message Style

Input: Added error handling for API timeout and network errors
Output: `fix: handle API timeout and network errors gracefully`

Input: Refactored the user service to use dependency injection
Output: `refactor: use dependency injection in user service`
```

### Example — Code Review Comments

```markdown
## Comment Style

Bad: "This function is too long."
Good: "P1: `processOrder()` (142 lines) handles validation, payment, and notification.
Split into `validateOrder()`, `processPayment()`, `sendNotification()`."
```

## Pre-Delivery Checklist Pattern

Add concrete, verifiable checks before delivering output. Each item must be specific enough that the model can verify it by looking at the output.

### Organize by Category

```markdown
## Pre-Delivery Checklist

### Visual Quality
- [ ] No emojis used as icons (use SVG instead)
- [ ] All icons from consistent icon set
- [ ] Hover states don't cause layout shift
- [ ] Brand logos are correct

### Interaction
- [ ] All clickable elements have cursor-pointer
- [ ] Transitions are smooth (150-300ms)

### Accessibility
- [ ] All images have alt text
- [ ] Form inputs have labels
- [ ] prefers-reduced-motion respected
```

### Priority-Based Output

For review/analysis skills, categorize findings by priority:

| Level | Meaning | Action |
|-------|---------|--------|
| P0 | Critical | Must block delivery / must fix immediately |
| P1 | High | Should fix before delivery |
| P2 | Medium | Create follow-up task |
| P3 | Low | Optional improvement |

This prevents the model from treating all issues as equally important. A critical security bug and a naming nitpick should not get the same weight.

### Key Rule

Every checklist item must be **specific and verifiable** — not subjective.

```markdown
# Bad
- [ ] Ensure good quality
- [ ] Make sure it looks nice

# Good
- [ ] No placeholder text remaining (TODO, FIXME, xxx)
- [ ] All generated code runs without errors
- [ ] Color contrast ratio meets WCAG AA (4.5:1 for text)
```

```

### references/parameter-system.md

```markdown
# Parameter System

## The $ARGUMENTS Variable

Skills receive user input through the `$ARGUMENTS` variable. This includes everything the user types after the skill invocation.

Example: `/my-skill article.md --style dark --quick`
→ `$ARGUMENTS` = `article.md --style dark --quick`

## Designing Parameters

### Basic Structure

Document parameters as a table in SKILL.md:

```markdown
## Options

| Option | Description | Default |
|--------|-------------|---------|
| `<content>` | Input file or text | Required |
| `--style <name>` | Visual style | auto |
| `--quick` | Skip confirmation gates | false |
| `--lang <code>` | Output language | en |
```

### Parameter Types

1. **Positional**: `<content>` — the main input
2. **Named flags**: `--style dark` — configuration with a value
3. **Boolean flags**: `--quick` — toggle behavior (no value)
4. **Partial execution**: `--outline-only`, `--images-only` — run only part of the workflow
5. **Selective redo**: `--regenerate 3` — redo a specific item without rerunning everything

### Argument Hint

Add `argument-hint` to frontmatter so users see parameter suggestions when typing `/`:

```yaml
argument-hint: [content] [--style name] [--quick] [--lang code]
```

## Advanced Patterns

### Partial Execution

Let users run only part of the workflow instead of start-to-finish:

```bash
/slide-deck content.md --outline-only     # Only generate outline
/slide-deck content.md --prompts-only     # Only generate image prompts
/slide-deck slide-deck/topic/ --images-only  # Only generate images
```

In SKILL.md, check the flag and skip to the relevant step:

```markdown
## Step 1: Parse Arguments

$ARGUMENTS

If `--outline-only`: Execute Steps 1-3 only, then output.
If `--images-only`: Skip to Step 7, load existing prompts.
If `--regenerate N`: Skip to Step 7, regenerate only slide N.
Otherwise: Execute full workflow.
```

### Independent Dimensions

Design parameters to be independently combinable — any combination is valid:

```bash
/cover-image article.md --type conceptual --palette warm --rendering flat-vector
/cover-image article.md --quick                # Skip confirmation, full auto
/cover-image article.md --ref style-ref.png    # Use reference image
```

Each dimension (type, palette, rendering) is independent. The user can set any, all, or none.

### Quick Mode

A `--quick` flag that skips confirmation gates is a common and useful pattern:

```markdown
## Step 2: Confirm Options ⚠️ REQUIRED

Unless `--quick` was passed:
- Present options to user
- Wait for confirmation

If `--quick`: Use auto-selected defaults and proceed.
```

This lets power users skip the interactive flow while keeping it safe by default.

### Default Values

Always define sensible defaults for every parameter:

```markdown
## Defaults

- `--style`: auto-detected from content
- `--lang`: same as input content
- `--slides`: 8-12 based on content length
```

This way, `/my-skill content.md` with zero flags still produces good output.

```

### references/workflow-patterns.md

```markdown
# Workflow Patterns

## The Checklist Pattern

A trackable checklist gives the model a clear execution path. Without one, the model freestyles — inconsistent, skipping steps, mixing priorities.

### Basic Structure

```markdown
Copy this checklist and check off items as you complete them:

- [ ] Step 1: Setup & Analyze
  - [ ] 1.1 Load preferences
  - [ ] 1.2 Analyze content
  - [ ] 1.3 Check existing ⚠️ REQUIRED
- [ ] Step 2: Confirmation ⚠️ REQUIRED
- [ ] Step 3: Execute core task
- [ ] Step 4: Review & output
```

### Markers

| Marker | Meaning | When to Use |
|--------|---------|-------------|
| ⚠️ REQUIRED | Must not skip | User confirmation, critical validation |
| ⛔ BLOCKING | Must complete before proceeding | Prerequisite setup, dependency loading |
| (conditional) | Execute based on earlier decisions | Optional review, user-selected features |

### Design Principles

1. **Progressive depth**: Start macro, go micro. Don't start with naming conventions — start with understanding the overall change.
2. **Sub-step nesting**: Complex steps broken into 1.1, 1.2, 1.3.
3. **Conditional branches**: Mark steps that only run in certain scenarios.

### Example — PPT Generation Workflow

```markdown
- [ ] Step 0: Check preferences ⛔ BLOCKING
  - [ ] Found → load preferences → continue
  - [ ] Not found → run first-time setup → MUST complete before Step 1
- [ ] Step 1: Analyze content
- [ ] Step 2: Confirm options ⚠️ REQUIRED
- [ ] Step 3: Generate outline
- [ ] Step 4: Review outline (conditional — only if user opted in)
- [ ] Step 5: Generate slides
- [ ] Step 6: Output summary
```

### Example — Code Review Workflow (Progressive Depth)

```markdown
- [ ] Step 1: Understand scope (what changed and why)
- [ ] Step 2: Architecture review (does the design make sense?)
- [ ] Step 3: Security review → Load security-checklist.md
- [ ] Step 4: Code quality → Load quality-checklist.md
- [ ] Step 5: Present findings ⚠️ REQUIRED
- [ ] Step 6: Apply fixes (only after user confirms which ones)
```

Note: The order matters. Good reviewers don't start with naming conventions — they start with understanding intent. The workflow reflects this.

## Confirmation Gates

Force the model to stop and ask the user before critical operations.

### When to Add Confirmation Gates

- Before any destructive operation (delete, overwrite, modify)
- Before any generative operation with significant compute cost
- Before applying changes based on analysis
- When user preferences affect the output

### Pattern 1: Simple Gate

```markdown
## Step 5: Confirm ⚠️ REQUIRED

Present findings to the user. Ask:
- Proceed with all recommendations?
- Only apply high-priority (P0/P1) items?
- Select specific items to apply?
- View only, no changes?

⚠️ Do NOT proceed without explicit user confirmation.
```

### Pattern 2: Structured Gate (using AskUserQuestion)

```markdown
## Step 2: Confirm Options ⚠️ REQUIRED

Use AskUserQuestion to confirm:
- Round 1 (always): style, audience, quantity, review preferences
- Round 2 (conditional): only if "custom" was selected — texture, tone, layout

Unless user passed `--quick` flag, this step is mandatory.
```

### Pattern 3: Blocking Gate

```markdown
## Step 0: Load Preferences ⛔ BLOCKING

- Found → load and continue
- Not found → run first-time setup → MUST complete before Step 1
```

### Why Confirmation Gates Matter

Without them, if the model makes a wrong decision at step 3, everything after step 3 is wasted work. Gates give users control over the process and ensure the model's analysis is reviewed before action.

## Pre-Delivery Checklist Pattern

Add concrete, verifiable checks before delivering output. Each item must be specific enough to check by looking at the output.

### Bad vs Good

```markdown
# Bad — vague, uncheckable
- [ ] Ensure good quality
- [ ] Make sure it's accessible

# Good — specific, verifiable
- [ ] No emojis used as icons (use SVG instead)
- [ ] All images have alt text
- [ ] All clickable elements have cursor-pointer
- [ ] Transitions are 150-300ms
- [ ] No placeholder text remaining (TODO, FIXME, xxx)
```

### Organize by Category

```markdown
## Pre-Delivery Checklist

### Correctness
- [ ] Generated code compiles/runs without errors
- [ ] Output matches requested format exactly
- [ ] No placeholder text remaining

### Quality
- [ ] Follows existing code style in the project
- [ ] No unnecessary complexity added

### Completeness
- [ ] All workflow checklist items checked off
- [ ] User's original request fully addressed
```

### Priority-Based Output

For review/analysis skills, categorize findings instead of a flat list:

| Level | Meaning | Action |
|-------|---------|--------|
| P0 | Critical | Must block delivery |
| P1 | High | Should fix before delivery |
| P2 | Medium | Create follow-up task |
| P3 | Low | Optional improvement |

This prevents the model from treating all issues equally — critical bugs and naming nitpicks should not get the same weight.

```

### references/writing-techniques.md

```markdown
# Writing Techniques for Skills

## Technique 1: The Iron Law

Set one unbreakable rule at the top of SKILL.md, right after frontmatter. This prevents the model from taking shortcuts.

### Examples

**Debugging skill:**
```
IRON LAW: NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST.
```

**TDD skill:**
```
IRON LAW: NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST.
```

**Copywriting skill:**
```
IRON LAW: Clarity over cleverness — ALWAYS.
```

**Database migration skill:**
```
IRON LAW: Every migration must have a rollback script. No rollback = no execution.
```

### How to Write an Iron Law

Ask: "What is the ONE mistake the model will most likely make with this skill?"

Then write a rule that prevents it:
- ALL CAPS for emphasis
- Absolute language ("NEVER", "ALWAYS", "MUST")
- No wiggle room — no "try to" or "consider"

### Red Flag Signals

Pair your Iron Law with "red flags" that force the model to backtrack when it drifts:

```markdown
Red Flags (return to Step 1 if any appear):
- "I think the problem might be..." (guessing, not analyzing)
- Making changes without understanding root cause
- Fix works but you can't explain why
```

This is a "rollback mechanism" — when the model catches itself drifting, it resets to the investigation phase.

## Technique 2: Question-Style Instructions

Give the model specific questions to answer, not vague directives. Models excel at "finding answers to specific questions" but struggle with abstract instructions.

### Why This Works

A good question focuses the model's attention on the right part of the code or content. A vague directive leaves the model unsure where to look.

### Examples

```markdown
# Bad — vague directive
Check if the code violates the Single Responsibility Principle.

# Good — specific question
Ask yourself: How many distinct reasons could this module need to change?
If the answer is more than one, it likely violates SRP.
```

```markdown
# Bad
Watch out for race conditions.

# Good
Ask: What happens if two requests hit this code simultaneously?
```

```markdown
# Bad
Handle edge cases properly.

# Good
Ask: What happens if this value is null? Is 0? Is an empty array? Is negative?
```

```markdown
# Bad
Watch out for TOCTOU vulnerabilities.

# Good
Ask: Between checking the permission and performing the action,
could the state have changed?
```

```markdown
# Bad
Write engaging copy.

# Good
Ask: If the reader stopped after the first sentence, would they know
what they're getting and why they should care?
```

### Pattern

Transform vague directives into concrete questions:

1. Identify what you want the model to check
2. Ask the question a senior expert would ask when checking it
3. Include what the answer implies ("if more than one → likely violates SRP")

## Technique 3: Anti-Pattern Documentation

Explicitly list what the model should NOT do. This is as important as listing what it should do.

### Why This Works

Models have "default patterns" from training data — purple/blue gradients for UI, "Learn More" for CTAs, try-catch-console.log for error handling. If you only say "write good UI," the model uses its defaults. But if you say "NOT purple gradients, NOT Inter font, NOT rounded card grids," it's forced out of its comfort zone.

### How to Find Anti-Patterns

Ask: "What would Claude's lazy default look like for this task?" Then explicitly forbid it.

### Examples

**Frontend design skill:**
```markdown
Anti-Patterns to Avoid:
- Generic AI aesthetics
- Purple/blue gradients as default
- Cookie-cutter layouts
- Overused fonts like Inter for everything
- Avoid designs that look "AI-generated"
```

**Copywriting skill:**
```markdown
Weak CTAs to avoid: "Submit", "Sign Up", "Learn More"
```

**Code review skill:**
```markdown
Insecure patterns (must flag):
- Direct SQL string concatenation
- User input inserted into HTML without escaping
- Check-then-act without locks
- Hardcoded secrets or credentials
```

**Any skill that generates code:**
```markdown
Do NOT:
- Add unnecessary try-catch blocks with console.log
- Over-abstract one-time operations into utility functions
- Add comments that restate the code
- Create configuration for things that won't change
```

### Structure

Place anti-patterns either:
- In the SKILL.md body near the relevant step
- In a reference file for detailed anti-pattern lists (e.g., `references/security-antipatterns.md`)

Keep them concrete and specific — not "don't write bad code" but "don't concatenate SQL strings."

```

### scripts/quick_validate.py

```python
#!/usr/bin/env python3
"""
Quick validation script for skills.
"""

import sys
import re
import yaml
from pathlib import Path


def validate_skill(skill_path):
    """Basic validation of a skill."""
    skill_path = Path(skill_path)

    # Check SKILL.md exists
    skill_md = skill_path / 'SKILL.md'
    if not skill_md.exists():
        return False, "SKILL.md not found"

    # Read and validate frontmatter
    content = skill_md.read_text()
    if not content.startswith('---'):
        return False, "No YAML frontmatter found"

    # Extract frontmatter
    match = re.match(r'^---\n(.*?)\n---', content, re.DOTALL)
    if not match:
        return False, "Invalid frontmatter format"

    frontmatter_text = match.group(1)

    # Parse YAML frontmatter
    try:
        frontmatter = yaml.safe_load(frontmatter_text)
        if not isinstance(frontmatter, dict):
            return False, "Frontmatter must be a YAML dictionary"
    except yaml.YAMLError as e:
        return False, f"Invalid YAML in frontmatter: {e}"

    # Define allowed properties
    ALLOWED_PROPERTIES = {'name', 'description', 'license', 'allowed-tools', 'metadata', 'argument-hint'}

    # Check for unexpected properties
    unexpected_keys = set(frontmatter.keys()) - ALLOWED_PROPERTIES
    if unexpected_keys:
        return False, (
            f"Unexpected key(s) in SKILL.md frontmatter: {', '.join(sorted(unexpected_keys))}. "
            f"Allowed properties are: {', '.join(sorted(ALLOWED_PROPERTIES))}"
        )

    # Check required fields
    if 'name' not in frontmatter:
        return False, "Missing 'name' in frontmatter"
    if 'description' not in frontmatter:
        return False, "Missing 'description' in frontmatter"

    # Validate name
    name = frontmatter.get('name', '')
    if not isinstance(name, str):
        return False, f"Name must be a string, got {type(name).__name__}"
    name = name.strip()
    if name:
        if not re.match(r'^[a-z0-9-]+$', name):
            return False, f"Name '{name}' should be hyphen-case (lowercase letters, digits, and hyphens only)"
        if name.startswith('-') or name.endswith('-') or '--' in name:
            return False, f"Name '{name}' cannot start/end with hyphen or contain consecutive hyphens"
        if len(name) > 64:
            return False, f"Name is too long ({len(name)} characters). Maximum is 64 characters."

    # Validate description
    description = frontmatter.get('description', '')
    if not isinstance(description, str):
        return False, f"Description must be a string, got {type(description).__name__}"
    description = description.strip()
    if description:
        if '<' in description or '>' in description:
            return False, "Description cannot contain angle brackets (< or >)"
        if len(description) > 1024:
            return False, f"Description is too long ({len(description)} characters). Maximum is 1024 characters."

    return True, "Skill is valid!"


if __name__ == "__main__":
    if len(sys.argv) != 2:
        print("Usage: python quick_validate.py <skill_directory>")
        sys.exit(1)

    valid, message = validate_skill(sys.argv[1])
    print(message)
    sys.exit(0 if valid else 1)

```