skill-forge

Files (11)

• README.md
• SKILL.md
• architecture-guide.md · references/
• description-guide.md · references/
• output-patterns.md · references/
• parameter-system.md · references/
• workflow-patterns.md · references/
• writing-techniques.md · references/
• init_skill.py · scripts/
• package_skill.py · scripts/
• quick_validate.py · scripts/

SKILL.md (first lines)

# 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)
├── README.md          # Required for public repos: human-readable overview
├── 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
  - [ ] 6.4 Write README.md ⚠️ REQUIRED for public repos
- [ ] 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

From coding327/lc-skills, MIT.

More from coding327/lc-skills