skill-forge

Imported from WilliamSaysX/skill-forge (SKILL.md). Install upstream with npx skills add WilliamSaysX/skill-forge. Copyright stays with the author (Complete terms in LICENSE.txt).

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:

📖 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 question strategies and best practices.

Step 2: Planning the Reusable Skill Contents

Goal: Identify what scripts, references, and assets to bundle with the skill.

Analysis Questions:

1. What code gets rewritten repeatedly? → scripts/
2. What documentation needs referencing? → references/
3. What templates or files are used in output? → assets/

Common Patterns:

• Repetitive code → Script (e.g., scripts/rotate_pdf.py)
• Schemas/API docs → Reference (e.g., references/schema.md)
• Boilerplate/templates → Asset (e.g., assets/template/)

Output: List of reusable resources to include.

📖 See workflow-guide.md#step-2 for detailed examples and analysis patterns.

Step 3: Initializing the Skill

Goal: Create skill directory structure using init_skill.py. Skip: If skill already exists (jump to Step 4).

Choosing Skill Location:

Unlike temporary materials (auto-detected), skills are permanent. Always ask user where to create it:

Where would you like to create the <skill-name> skill?
1. Project skills (.claude/skills/) - For this project only
2. Global skills (~/.claude/skills/) - Available everywhere
3. Custom path - Specify your own location

Usage:

# Based on user choice (1, 2, or 3):
scripts/init_skill.py <skill-name> --path <user-chosen-path>

What it creates:

• SKILL.md template with frontmatter
• scripts/, references/, assets/ directories
• Example files (customize or delete as needed)

📖 See workflow-guide.md#step-3 for detailed path selection guidance and examples.

Step 4: Edit the Skill

Goal: Implement bundled resources and write SKILL.md instructions.

Start with Resources:

1. Implement scripts/, references/, assets/ from Step 2
2. Delete unused example files from initialization
3. May require user input (e.g., brand assets, documentation)

🆕 Smart Processing for Large Documentation Files:

If documentation was fetched (especially via llms.txt), check file size:

# Check if documentation file is large
ls -lh <path-to-fetched-docs>

For large files (>50KB or >10,000 words):

Split into logical sections following Progressive Disclosure principle:

Example Structure:

references/
├── overview.md          # High-level concepts, getting started
├── core-concepts.md     # Main ideas, architecture
├── api-reference.md     # API documentation
└── advanced.md          # Advanced usage, examples

Splitting Strategy:

1. Read the large markdown file
2. Identify natural sections (based on headings, topics)
3. Split into 3-5 focused files (each <20KB)
4. Name files descriptively (overview, api, examples, etc.)
5. Update SKILL.md to reference specific files

Benefits:

• ✅ Faster context loading (load only needed sections)
• ✅ Better grep-ability (search specific files)
• ✅ Follows Progressive Disclosure design

For small files (<50KB):

• Keep as single file in references/

Update SKILL.md:

Writing Style: Use imperative/infinitive form (verb-first), not second person.

• ✅ "To accomplish X, do Y"
• ❌ "You should do X"

Answer These Questions:

1. What is the purpose? (a few sentences)
2. When should it be used? (trigger patterns)
3. How should Claude use it? (reference all bundled resources)

Focus: Include procedural knowledge and domain-specific details that benefit another Claude instance.

📖 See workflow-guide.md#step-4 for writing guidelines and examples.

Step 5: Completion and Optional Packaging

CRITICAL: After Step 4, the skill is already installed and ready to use!

Required Actions After Step 4:

1. Auto-cleanup temporary materials (if materials exist):

   # Silently clean up temp-materials - user doesn't need to know
   scripts/cleanup_materials.py <skill-name>

   Do this automatically without asking. Materials are no longer needed after skill creation.

2. Auto-cleanup temporary helper scripts (if any exist in skill's scripts/ directory):

   Common temporary scripts to remove:

   • split_docs.py - Document splitting helper (if created during Step 4)
   • process_*.py - Any temporary processing scripts
   • temp_*.py - Any scripts with "temp" prefix

   Check and clean:

   # Example: Remove split_docs.py if it exists
   rm -f <skill-path>/scripts/split_docs.py

   Do this silently. Only keep scripts that are part of the skill's permanent functionality.

3. Inform user of completion:

   ✅ Skill created and installed successfully!
   📁 Location: ~/.claude/skills/crewai/
   🎉 The skill is ready to use immediately!
   

4. ONLY THEN ask about packaging:

   📦 Would you like to package it as a .zip for sharing with others? (Optional)
   

⚠️ DO NOT package automatically - must ask user first!

If user wants to package (optional):

Goal: Validate and package skill into distributable .zip file for sharing.

Usage:

scripts/package_skill.py <path/to/skill-folder>

# Custom output location:
scripts/package_skill.py <path/to/skill-folder> ./dist

Process:

1. Validates: Frontmatter, naming, structure, descriptions
2. Packages: Creates <skill-name>.zip in skill directory (default)
3. Reports: Shows errors if validation fails

After Packaging:

✅ Skill packaged successfully!
📦 Package: ~/.claude/skills/crewai/crewai.zip
📁 Installed: ~/.claude/skills/crewai/ (ready to use)

Note: Temporary materials are automatically cleaned up after skill creation. Users don't need to manually manage cleanup.

📖 See workflow-guide.md#step-5 and path-management.md for detailed workflow documentation.

Step 6: Iterate

When: After testing skill on real tasks Trigger: Users request improvements based on skill performance

Workflow:

1. Use skill on real tasks
2. Notice struggles/inefficiencies
3. Update SKILL.md or resources
4. Test again

📖 See workflow-guide.md#step-6 for iteration patterns.