skill-forge

Skill Forge

An automated skill creation workshop that provides end-to-end guidance for forging effective skills. Features intelligent source detection, smart path management, automatic material fetching from GitHub repositories, online documentation (with llms.txt support), or local directories, and comprehensive cleanup tools.

About Skills

Skills are modular, self-contained packages that extend Claude's capabilities by providing specialized knowledge, workflows, and tools. Think of them as "onboarding guides" for specific domains or tasks—they transform Claude from a general-purpose agent into a specialized agent equipped with procedural knowledge that no model can fully possess.

What Skills Provide

1. Specialized workflows - Multi-step procedures for specific domains
2. Tool integrations - Instructions for working with specific file formats or APIs
3. Domain expertise - Company-specific knowledge, schemas, business logic
4. Bundled resources - Scripts, references, and assets for complex and repetitive tasks

Anatomy of a Skill

Every skill consists of a required SKILL.md file and optional bundled resources:

skill-name/
├── SKILL.md (required)
│   ├── YAML frontmatter metadata (required)
│   │   ├── name: (required)
│   │   └── description: (required)
│   └── Markdown instructions (required)
└── Bundled Resources (optional)
    ├── scripts/          - Executable code (Python/Bash/etc.)
    ├── references/       - Documentation intended to be loaded into context as needed
    └── assets/           - Files used in output (templates, icons, fonts, etc.)

SKILL.md (required)

Metadata Quality: The name and description in YAML frontmatter determine when Claude will use the skill. Be specific about what the skill does and when to use it. Use the third-person (e.g. "This skill should be used when..." instead of "Use this skill when...").

Bundled Resources (optional)

Scripts (scripts/)

Executable code (Python/Bash/etc.) for tasks that require deterministic reliability or are repeatedly rewritten.

• When to include: When the same code is being rewritten repeatedly or deterministic reliability is needed
• Example: scripts/rotate_pdf.py for PDF rotation tasks
• Benefits: Token efficient, deterministic, may be executed without loading into context
• Note: Scripts may still need to be read by Claude for patching or environment-specific adjustments

References (references/)

Documentation and reference material intended to be loaded as needed into context to inform Claude's process and thinking.

• When to include: For documentation that Claude should reference while working
• Examples: references/finance.md for financial schemas, references/mnda.md for company NDA template, references/policies.md for company policies, references/api_docs.md for API specifications
• Use cases: Database schemas, API documentation, domain knowledge, company policies, detailed workflow guides
• Benefits: Keeps SKILL.md lean, loaded only when Claude determines it's needed
• Best practice: If files are large (>10k words), include grep search patterns in SKILL.md
• Avoid duplication: Information should live in either SKILL.md or references files, not both. Prefer references files for detailed information unless it's truly core to the skill—this keeps SKILL.md lean while making information discoverable without hogging the context window. Keep only essential procedural instructions and workflow guidance in SKILL.md; move detailed reference material, schemas, and examples to references files.

Assets (assets/)

Files not intended to be loaded into context, but rather used within the output Claude produces.

• When to include: When the skill needs files that will be used in the final output
• Examples: assets/logo.png for brand assets, assets/slides.pptx for PowerPoint templates, assets/frontend-template/ for HTML/React boilerplate, assets/font.ttf for typography
• Use cases: Templates, images, icons, boilerplate code, fonts, sample documents that get copied or modified
• Benefits: Separates output resources from documentation, enables Claude to use files without loading them into context

Progressive Disclosure Design Principle

Skills use a three-level loading system to manage context efficiently:

1. Metadata (name + description) - Always in context (~100 words)
2. SKILL.md body - When skill triggers (<5k words)
3. Bundled resources - As needed by Claude (Unlimited*)

*Unlimited because scripts can be executed without reading into context window.

Path Management Overview

Three types of paths with different management strategies:

Type	Location	Strategy
Materials (temp)	.claude/temp-materials/ or ~/skill-materials/	Auto-detected
Skill (permanent)	User chooses location	Ask user
Zip (package)	Inside skill directory	Default

📖 Detailed Guide: See path-management.md for smart path detection, cleanup strategies, and examples.

When to Use This Skill

This skill should be triggered when users request to create a new skill or convert external resources into a skill. Common trigger patterns:

• "Create a skill from [URL/path]"
• "Turn this into a skill: [URL/path]"
• "Help me make a skill for [description]"
• "Convert [repository/docs] to a skill"
• "Build a skill from [source]"

Automatic Source Detection

Automatically detect source type and act accordingly:

Decision Tree:

GitHub URL (github.com/*) → fetch_source.py --git <url>
Documentation URL (docs.*, */docs/) → fetch_source.py --docs <url> --name <name>
Local Path (~/, /, ./) → Use directly (skip fetch)
Ambiguous → Ask user for clarification

Quick Examples:

• https://github.com/user/repo → Auto-clone to materials directory
• https://docs.example.com → Auto-scrape documentation
• ~/my-tools/ → Use local directory directly
• "Create skill for X" → Ask for source clarification

📖 Detailed Guide: See source-detection.md for complete patterns, edge cases, and examples.

Proactive Fetching

✅ Do: Immediately fetch when source type is clear ❌ Don't: Ask permission for obvious actions (GitHub URLs, documentation sites) ❓ Ask: Only when genuinely ambiguous

Skill Creation Process

Follow these steps in order. Skip only when clearly not applicable.

📖 Complete Workflow: See workflow-guide.md for detailed step-by-step instructions and examples.

Step 0: Fetch Source Materials (Automatic)

When: User provides external source (GitHub/docs URL) Skip: When using local directory

For GitHub Repositories

scripts/fetch_source.py --git https://github.com/user/repo

No additional dependencies needed (requires git command only).

For Online Documentation

🆕 llms.txt Detection (Recommended)

Many modern documentation sites support the llms.txt standard - a LLM-optimized documentation format that's 10x faster to fetch.

First, check if the site has llms.txt:

scripts/detect_llms_txt.py https://docs.example.com

If found, use the llms.txt URL directly:

# Much faster! ⚡
scripts/fetch_source.py --docs https://docs.example.com/llms-full.txt --name project-name

Note: fetch_source.py automatically detects llms.txt and recommends it if available.

Regular Documentation Scraping

If no llms.txt available, use regular scraping with markitdown:

First, verify markitdown is installed:

try:
    from markitdown import MarkItDown
    print("✅ MarkItDown is installed")
except ImportError:
    print("❌ Need to install: pip install 'markitdown[all]'")

If not installed:

pip install 'markitdown[all]'

Then fetch documentation:

scripts/fetch_source.py --docs https://docs.example.com --name project-name

For PDF and Office Documents

markitdown also supports PDF, Word, PowerPoint, and Excel files:

PDF Documents:

# From URL
scripts/fetch_source.py --docs https://example.com/manual.pdf --name manual

# From local file
scripts/fetch_source.py --docs /path/to/document.pdf --name doc

Other Formats:

# Word document
scripts/fetch_source.py --docs /path/to/spec.docx --name spec

# PowerPoint
scripts/fetch_source.py --docs /path/to/slides.pptx --name slides

# Excel
scripts/fetch_source.py --docs /path/to/data.xlsx --name data

Notes:

• Text-based PDFs (most common) work out of the box with markitdown
• Scanned PDFs: Provide the file directly for visual text extraction
• Complex PDFs with tables/graphics may need manual review

Combined Mode

scripts/fetch_source.py --git <url> --docs <url> --name combo

Smart Path Detection: Materials auto-saved to:

• Project mode: <project-root>/.claude/temp-materials/
• Global mode: ~/skill-materials/

Common Options: --depth 1 (shallow clone), --branch <name>, --output <path>

📖 See workflow-guide.md#step-0 for full options and examples.

Step 1: Understanding the Skill with Concrete Examples

Goal: Clearly understand how the skill will be used through concrete examples.

Process:

• Ask users for specific use cases
• Generate example scenarios for validation
• Identify trigger patterns
• Clarify scope and functionality

Example Questions:

• "What functionality should this skill support?"
• "What would users say to trigger this skill?"
• "Can you give concrete examples of how it would be used?"

When to conclude: Clear sense of the skill's purpose and usage patterns.

📖 See workflow-guide.md#step-1 for detailed questi

---

Content truncated.