SkillForge — Agent Skill Generator
Generate complete, production-ready Agent Skill packages via a 7-step pipeline. Each step has defined inputs, outputs, and quality constraints.
Core Design Principles
Apply these principles throughout all 7 steps:
- Concise is Key — Context window is a public good. Only include knowledge the AI model does NOT already have. Challenge each paragraph: "Does this justify its token cost?"
- Description is the trigger — Determines whether the Skill gets selected. Must include WHAT + WHEN.
- Progressive disclosure — SKILL.md < 500 lines. Supporting files in scripts/, references/, templates/ loaded on demand.
- Code examples > text — Prefer concise, runnable examples over verbose descriptions.
- Anti-patterns are essential — Show what NOT to do using ❌/✅ contrast format.
- Imperative tone — "Run" not "You should run".
- No auxiliary files — No README.md, CHANGELOG.md. Skills are for AI agents, not humans.
Pipeline Overview
User requirement
→ Step 1: Requirement deep analysis
→ Step 2: Architecture decisions
→ Step 3: Metadata (YAML frontmatter)
→ Step 4: SKILL.md body
→ Step 5: Quality audit + optimization
→ Step 6: Resource files (scripts/, references/, templates/)
→ Step 7: Usage documentation
→ Complete Skill package
Execute steps sequentially. Each step builds on previous outputs.
Step 1: Requirement Deep Analysis
Analyze the user's requirement. Output a structured document (2000-5000 chars).
Read the full step prompt: references/step-prompts.md → Section "Step 1".
Output structure:
1. Core positioning (name, one-line description, target users, value proposition)
2. Functional boundaries (core features as input→process→output triples, extensions, exclusions)
3. Usage scenarios (at least 5, each with: user request, expected behavior, output format)
4. Knowledge gap analysis (most critical):
- AI already knows → exclude from SKILL.md
- AI doesn't know → core content of SKILL.md
- AI often gets wrong → needs anti-pattern examples
5. Dependencies and constraints
Step 2: Architecture Decisions
Make 5 key decisions. Read full prompt: references/step-prompts.md → Section "Step 2".
| Decision | Options |
|---|---|
| Structure pattern | Workflow / Task-oriented / Guide / Capability |
| Freedom level | High / Medium / Low |
| Resource file plan | Table of files with paths, types, purposes, line counts |
| Progressive disclosure | What goes in SKILL.md vs references/ vs scripts/ |
| Quality assurance | Validation checklist, common errors, quality standards |
Output a complete directory tree at the end.
Step 3: Metadata Crafting
Generate YAML frontmatter with optimized description.
- Generate 3 candidate descriptions
- Score each on: trigger precision (1-5), capability coverage (1-5), information density (1-5)
- Select highest-scoring candidate
Read full prompt: references/step-prompts.md → Section "Step 3".
description quality rules:
- 30-80 words, objective descriptive tone
- Must include WHAT the skill does AND WHEN to use it
- Every word must earn its place
Step 4: SKILL.md Body Generation
Generate the complete body (excluding frontmatter). Target: 150-450 lines.
Read full prompt: references/step-prompts.md → Section "Step 4".
Structure (adapt as needed):
1. Overview (2-3 sentences)
2. Core workflow (numbered steps or decision flow)
3. Detailed rules and instructions (domain-specific)
4. Code examples (✅ Good / ❌ Bad contrast format)
5. Edge case handling
6. Output format specification
7. Validation checklist (Markdown checkboxes)
Key constraints:
- No generic knowledge AI already has
- No repetition of description content
- Sections > 100 lines → split to references/
- All code examples must be complete and runnable
Step 5: Quality Audit
Audit the generated SKILL.md (Step 3 frontmatter + Step 4 body) against 10 dimensions, then output the optimized version.
Read full prompt: references/step-prompts.md → Section "Step 5".
10-dimension scoring (1-10 each):
| # | Dimension |
|---|---|
| 1 | Description trigger precision |
| 2 | Knowledge increment (only AI-unknown content) |
| 3 | Code example quality (runnable, representative) |
| 4 | Anti-pattern coverage (❌/✅ contrast) |
| 5 | Structure clarity |
| 6 | Progressive disclosure (<500 lines) |
| 7 | Tone consistency (imperative throughout) |
| 8 | Edge case handling |
| 9 | Actionability (instructions directly executable) |
| 10 | Completeness (no missing critical content) |
Fix any dimension scoring below 8. Output optimized complete SKILL.md.
Step 6: Resource File Generation
Generate all supporting files planned in Step 2.
Read full prompt: references/step-prompts.md → Section "Step 6".
Rules:
- Strictly follow Step 2 file plan — no omissions, no extras
- If Step 2 says "no resource files needed" → skip this step
- Every file must be complete — no ... or TODO placeholders
- Scripts must include shebang lines
Step 7: Usage Documentation
Generate usage guide with 4 sections:
- Installation (1-3 sentences)
- Trigger examples (at least 5 natural language requests)
- Iteration suggestions (3-5 specific improvement directions)
- Validation checklist (completeness checks with checkboxes)
Read full prompt: references/step-prompts.md → Section "Step 7".
Execution Workflow
When a user requests Skill generation:
- Collect requirement: skill name, target domain, core capabilities, usage scenarios (optional), notes (optional)
- Execute Steps 1-7 sequentially, presenting each step's output to the user
- After Step 5, write the final SKILL.md to disk
- After Step 6, write all resource files to disk
- After Step 7, present the complete skill package
File output structure:
{skill-name}/
├── SKILL.md
├── scripts/ (if planned)
├── references/ (if planned)
└── templates/ (if planned)
Quality Gate
Before delivering the final package, verify:
- [ ] SKILL.md exists with valid YAML frontmatter (name + description)
- [ ] description includes WHAT + WHEN, 30-80 words
- [ ] SKILL.md body < 500 lines
- [ ] All code examples are complete and runnable
- [ ] Anti-patterns use ❌/✅ contrast format
- [ ] Imperative tone throughout
- [ ] All Step 2 planned resource files exist
- [ ] No README.md, CHANGELOG.md, or auxiliary docs
- [ ] No generic knowledge AI already has
- [ ] Directory structure matches Step 2 plan
