vamfi/skill-forge/forge-methodology

Skill Forge Methodology

Create research-grounded, high-quality Claude Code skills by following a rigorous methodology that verifies all information against official documentation before generation.

Core Principle: Research Before Generation

NEVER generate skill content from training data alone. Every piece of guidance in a skill must be:

1. Verified against official documentation
2. Cited with source URLs
3. Marked if based on inference rather than direct documentation

Research Pipeline

Stage 1: Claude Code Documentation Research

Before creating any skill, research the official skill format:

1. DeepWiki Query: Use mcp__deepwiki__ask_question on anthropics/claude-code for:

• Current SKILL.md format requirements
• Frontmatter fields and their purposes
• Progressive disclosure patterns

1. WebFetch Official Sources:

• https://github.com/anthropics/skills — Official skills repository
• https://www.anthropic.com/news/skills — Skills announcement
• https://github.com/anthropics/claude-code/blob/main/plugins/README.md — Plugin documentation

1. Context7 Library Docs: If the skill involves a library, use mcp__context7__resolve-library-id then mcp__context7__get-library-docs for accurate API information.

Stage 2: Domain Research

For the specific domain the skill covers:

1. Identify Authoritative Sources:

• Official project documentation
• GitHub repositories
• RFC/specification documents

1. WebSearch for Current Information:

• Search: "[domain] official documentation 2024 2025"
• Search: "[domain] best practices site:[official-domain]"

1. WebFetch and Extract:

• Read multiple authoritative pages
• Extract specific procedures, not general overviews
• Note version numbers and dates

Stage 3: Synthesis

Combine research into skill content:

• Cross-reference findings across sources
• Resolve conflicts by preferring official sources
• Mark uncertain information clearly

SKILL.md Format (Official)

Based on official Anthropic documentation:

---
name: skill-name-kebab-case
description: This skill should be used when the user asks to "[trigger phrase 1]", "[trigger phrase 2]", "[trigger phrase 3]". [Brief description of capability].
version: 1.0.0
---

Description Requirements

The description field is critical — it determines when Claude activates the skill.

Must include:

• Third-person voice: "This skill should be used when..."
• Specific trigger phrases users would say
• Concrete scenarios, not vague capabilities

Good example:

This skill should be used when the user asks to "deploy to Kubernetes", "create K8s manifests", "configure kubectl", or mentions Kubernetes deployment patterns.

Bad example:

Helps with Kubernetes tasks.

Body Requirements

Write the SKILL.md body in imperative/infinitive form (verb-first):

Correct: "Create the deployment manifest with..." Incorrect: "You should create the deployment manifest..."

Keep SKILL.md body lean (1,500-2,000 words). Move detailed content to references/.

Directory Structure

skill-name/
├── SKILL.md                 # Required: Core instructions (lean)
├── references/              # Detailed documentation
│   ├── patterns.md          # Common patterns and examples
│   ├── api-reference.md     # API details if applicable
│   └── sources.md           # Citation URLs
├── examples/                # Working code examples
│   └── example-usage.sh
└── scripts/                 # Utility scripts
    └── validate.sh

Progressive Disclosure

Skills load in three levels to optimize token usage:

Keep SKILL.md lean. If content exceeds 2,000 words, move to references/.

Quality Checklist

Before finalizing any skill, verify:

Structure:

• [ ] SKILL.md exists with valid YAML frontmatter
• [ ] name and description fields present
• [ ] All referenced files exist

Description Quality:

• [ ] Uses third-person ("This skill should be used when...")
• [ ] Includes 3-5 specific trigger phrases
• [ ] Lists concrete scenarios

Content Quality:

• [ ] Body uses imperative form
• [ ] Body under 2,000 words
• [ ] Detailed content in references/
• [ ] Examples are complete and working

Accuracy:

• [ ] All facts verified against official docs
• [ ] Source citations included
• [ ] Research date documented
• [ ] Uncertain content marked

Source Credibility Hierarchy

Prioritize sources in this order:

1. Official documentation (highest trust)

• *.anthropic.com, official project docs

1. Official GitHub repositories

• anthropics/*, project official repos

1. Authoritative technical sources

• MDN, framework official docs, RFCs

1. Verified community sources (use with caution)

• Stack Overflow (high votes), official blogs

1. General web (lowest trust)

• Mark as "community guidance" if used

Additional Resources

For detailed patterns and implementation guides, consult:

• `references/skill-patterns.md` — Common skill patterns from official examples
• `references/research-guide.md` — Detailed research methodology
• `references/quality-checklist.md` — Comprehensive validation criteria
• `references/sources.md` — Official documentation URLs

Security Considerations

From official Anthropic guidance:

"While this makes them powerful, it also means that malicious skills may introduce vulnerabilities... We recommend installing skills only from trusted sources."

When creating skills:

• Never include hardcoded credentials
• Avoid instructions that connect to untrusted external sources
• Document all external dependencies
• Review bundled scripts for security issues