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:

Core positioning (name, one-line description, target users, value proposition)
Functional boundaries (core features as input→process→output triples, extensions, exclusions)
Usage scenarios (at least 5, each with: user request, expected behavior, output format)
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
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):

Overview (2-3 sentences)
Core workflow (numbered steps or decision flow)
Detailed rules and instructions (domain-specific)
Code examples (✅ Good / ❌ Bad contrast format)
Edge case handling
Output format specification
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:

skillforge

Safety Notice

Copy this and send it to your AI assistant to learn