Skill Forge

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:

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

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

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

Install

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

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:

## 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

# 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

# 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

## 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

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:

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.

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:

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:

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

# 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."

# 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.

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):

## 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:

## 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

## 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

## 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

## 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:

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.

# 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)

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:

## 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 /:

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:

/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:

## 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:

/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:

## 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:

## 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.

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

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

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

- [ ] 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)

- [ ] 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

## 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)

## 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

## 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

# 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

## 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:

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

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:

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

# 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.

# Bad
Watch out for race conditions.

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

# Bad
Handle edge cases properly.

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

# Bad
Watch out for TOCTOU vulnerabilities.

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

# 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:

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:

Weak CTAs to avoid: "Submit", "Sign Up", "Learn More"

Code review skill:

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:

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."