skill-article-writer

Original source / Raw SKILL.md

---
name: skill-article-writer
description: Generate comprehensive analysis articles from Claude skills. This skill should be used when you want to analyze a skill from the Anthropic skills repository and create a detailed tutorial article explaining its structure, design patterns, and usage. Perfect for creating documentation, tutorials, and educational content about existing skills.
license: Complete terms in LICENSE.txt
---

# skill-article-writer

Generate comprehensive analysis articles from Claude skills. This skill transforms any skill from the Anthropic repository into a detailed tutorial with explanations, best practices, and usage examples.

## What This Skill Does

**skill-article-writer** is a meta-skill that:
- Analyzes skill structure and bundled resources
- Generates detailed article outlines
- Creates comprehensive tutorials with code examples
- Produces multi-language versions (en, zh, fr)
- Follows proven documentation patterns

**Use cases**:
- Creating documentation for internal skills
- Writing tutorials for skill development
- Analyzing best practices from example skills
- Generating educational content for Claude users

### Skills vs. Articles

- **Skills**: Executable workflows that extend Claude's capabilities
- **Articles**: Educational content that explains how skills work
- **This Skill**: Bridges the gap by analyzing skills and creating articles

## Prerequisites

Before using this skill, you must have:

1. **Access to Anthropic skills repository**: `github.com/anthropics/skills`
2. **Local clone of target skill**: The skill must be available locally
3. **Python 3.x**: Required for analysis scripts
4. **Write access**: Ability to create article files in your project

## How The Skill Works

### Progressive Analysis

This skill uses a three-stage analysis process:

1. **Structure Analysis** (`analyze_skill.py`)
   - Examines directory structure
   - Parses SKILL.md metadata
   - Identifies bundled resources
   - Generates comprehensive metadata

2. **Outline Generation** (`generate_article_outline.py`)
   - Creates article structure
   - Plans section content
   - Identifies code examples
   - Generates markdown template

3. **Content Creation**
   - Fills in outline with detailed analysis
   - Adds practical examples
   - Creates multi-language versions
   - Validates MDX syntax

### Output Structure

Each generated article follows this structure:

```
1. Introduction (what is this skill?)
2. Skill Anatomy (directory structure)
3. Technical Deep Dive (how it works)
4. Usage Examples (practical demonstrations)
5. Best Practices (design principles)
6. Integration Patterns (with other skills)
7. Troubleshooting (common issues)
8. Conclusion and Next Steps
```

## Directory Structure

The skill-article-writer includes helper scripts for automation:

```
skill-article-writer/
├── SKILL.md                    # This file
├── scripts/
│   ├── analyze_skill.py        # Analyze skill structure
│   └── generate_article_outline.py  # Generate article template
├── references/
│   └── article-templates.md    # Template patterns for different skill types
└── examples/
    └── skill-creator-output.md # Example: analysis of skill-creator
```

## The 7-Step Article Creation Process

### Step 1: Understand the Source Skill

**Purpose**: Gain deep understanding of the skill's structure and purpose

**Actions**:
1. **Read the skill's SKILL.md**: Understand what problem it solves
2. **Examine bundled resources**: Scripts, references, and assets
3. **Identify key workflows**: How does the skill accomplish its goals?
4. **Note the target audience**: Who is this skill designed for?

**Output**: Comprehensive understanding of the skill's value proposition

**Example**: When analyzing `skill-creator`, we identified:
- **Problem solved**: Manual skill creation is error-prone
- **Key workflows**: 6-step creation process with validation
- **Target audience**: Developers creating Claude skills
- **Value proposition**: Systematic approach ensures quality and consistency

### Step 2: Analyze Structure and Extract Metadata

**Purpose**: Extract structured information for article generation

**Run analysis script**:
```bash
scripts/analyze_skill.py /path/to/skill-name > /tmp/skill-metadata.json
```

**What the script extracts**:
- Directory structure and file organization
- YAML frontmatter (name, description, etc.)
- Section headings and content structure
- Bundled resources inventory
- Commands and usage patterns
- Workflow steps

**Output**: JSON metadata file with structured skill information

**Key insight**: This metadata serves as the single source of truth for article generation

### Step 3: Generate Article Outline

**Purpose**: Create a structured outline that covers all important aspects

**Run outline generator**:
```bash
scripts/generate_article_outline.py /tmp/skill-metadata.json > /tmp/article-outline.md
```

**The outline includes**:
- Complete article structure with all sections
- Calls to action for expansion
- Component placeholders (Callouts, Cards, Steps)
- Source attribution blocks
- Appendix for detailed resource listings

**Design considerations**:
- Follows proven article structure from successful skill analyses
- Adapts section depth based on skill complexity
- Includes both overview and deep-dive sections
- Provides practical examples and use cases

**Output**: Comprehensive outline (150-200 lines) covering:
- Introduction and overview
- Technical deep dive
- Usage examples
- Best practices
- Troubleshooting
- Conclusion

### Step 4: Research and Expand Content

**Purpose**: Transform the outline into a detailed, informative article

**Content expansion process**:

1. **Fill in section details**:
   - Explain each concept thoroughly
   - Add code snippets and examples
   - Include practical demonstrations
   - Provide real-world use cases

2. **Add visual elements**:
   - Insert `<Callout type="info|warn|tip">` for important points
   - Use `<Cards>` and `<Card>` for related concepts
   - Add `<Steps>` and `<Step>` for procedural content
   - Include `<Files>`, `<Folder>`, `<File>` for directory structures

3. **Create practical examples**:
   - Walk through a complete example
   - Show before and after
   - Include expected output
   - Highlight key takeaways

4. **Add cross-references**:
   - Link to related skills
   - Reference external documentation
   - Connect to broader concepts

**Writing style**: Use imperative/infinitive form throughout

- ❌ **Wrong**: "You should run the script"
- ✅ **Right**: "Run the script"

**Output**: Complete article draft in English (3000-4000 words)

### Step 4.5: Generate Article Cover Illustration

**Purpose**: Automatically create a modern, theme-relevant SVG cover illustration for the skill analysis article.

**Why this matters**:
- Visual appeal increases engagement and readability
- Consistent illustration style across all skill documentation
- Saves time compared to manual design
- Automatically matches skill theme and technical domain

**Process**:

1. **Invoke the philosophical-illustrator skill**:
   - This skill generates modern, colorful SVG illustrations for technical content
   - Automatically selects color palette based on skill domain
   - Creates theme-relevant visual metaphors

2. **Prepare illustration context from skill analysis**:
   ```
   Skill Name: {skill-name}
   Article Title: {article-title}
   Main Topic: {skill's main purpose}
   Key Concepts: {extracted from Step 1 and Step 3}
   Technical Domain: {development/data/ai-ml/testing/etc.}
   ```

3. **Domain-to-Category Mapping** (for color palette selection):

   | Skill Domain | Category | Palette | Colors |
   |--------------|----------|---------|--------|
   | Code/Development | development | Pink-Purple | #C67B9B, #B8789E, #A97BA1 |
   | AI/ML/Agents | ai-ml | Pink-Purple | #C67B9B, #B8789E, #A97BA1 |
   | Data Processing | data | Beige-Neutral | #C9BFA8, #D4CAAF, #B8AD98 |
   | Testing/QA | development | Blue | #5B8FB9, #6B9BC4, #7AA5C8 |
   | DevOps/Infrastructure | devops | Green-Olive | #6B7F64, #758C6E, #607360 |
   | Security | security | Blue | #5B8FB9, #6B9BC4, #7AA5C8 |
   | Design/UI | design | Orange-Coral | #D17B5C, #C88860, #B87A5D |
   | General/Multi-purpose | content | Multi-topic | #CA8760, #D17B5C, #B87A5D |

4. **Generate SVG illustration**:
   - Use the Skill tool to invoke philosophical-illustrator
   - Pass skill name, domain, and key concepts
   - The skill will generate a 800x450px SVG with theme-relevant imagery
   - For skill analysis articles, focus on visual metaphors that represent:
     - Workflow automation (gears, connections, flow diagrams)
     - Code structure (brackets, files, hierarchies)
     - Problem-solving (lightbulbs, tools, transformations)

5. **Save illustration**:
   ```bash
   mkdir -p "public/images/docs/{article-slug}"
   # Save SVG output to:
   # public/images/docs/{article-slug}/cover.svg
   ```

6. **Update frontmatter reference**:
   - Add to frontmatter: `image: /images/docs/{article-slug}/cover.svg`
   - This field will be used by Fumadocs for article preview cards
   - Image appears in:
     - Article header
     - Card previews in navigation
     - Social media sharing (og:image)

**Example invocation**:
```
Use the philosophical-illustrator skill to generate a cover illustration:

Skill: skill-creator
Article Title: "Skill Creator Deep Dive: Systematic Approach to Building Claude Skills"
Domain: development
Key Concepts: Progressive disclosure, validation, bundled resources, 6-step process
Description: Analysis of skill-creator, a meta-skill for creating high-quality Claude skills

Please create a modern SVG illustration with:
- Pink-Purple color palette (development domain)
- Visual elements: code brackets, file structure icons, workflow connections, gears
- Metaphors: building blocks, systematic process, quality validation
- Modern, friendly aesthetic
- 800x450px dimensions
```

**Output**:
- SVG file saved to `public/images/docs/{slug}/cover.svg`
- Frontmatter updated with `image` field
- Illustration ready for all language versions (reused across en, zh, fr)

**Fallback**:
- If illustration generation fails, continue without image
- Log warning in summary report
- Article still functions normally (image is optional)

**Note**: The same cover image is used for all language versions of the article, as visual metaphors are language-agnostic.

### Step 5: Create Multi-Language Versions

**Purpose**: Make the article accessible to international audiences

#### CRITICAL: Terms to Preserve (DO NOT TRANSLATE)

Certain terms must remain in English as they are:
- **Product/Brand Names**: Claude, Anthropic, Claude.ai, Claude Code
- **Technical Concepts/Features**: Skills, Projects, MCP, Agent, SubAgent
- **Specific Tools**: GitHub, Google Drive, Slack, Excel
- **Framework/Technology Names**: React, Python, Node.js, TypeScript
- **Standard Acronyms**: API, SDK, AI, ML, RAG, UI, UX
- **Code Examples**: Variable names, function names, class names

**Translation Instruction**:
```
Translate the following to {language_name}, but PRESERVE these terms in English:
- Claude, Anthropic, Skills, Projects, MCP, Agent, SubAgent
- GitHub, Google Drive, Slack, Excel
- React, Python, Node.js, TypeScript
- API, SDK, AI, ML, RAG, UI, UX
- All code identifiers (variable/function/class names)

Why: These are proper names, brand names, or universal technical terms.
Translating them would confuse readers who expect the standard English terms.

Example of CORRECT translation:
English: "Claude's Skills feature helps agents work better"
Chinese: "Claude 的 Skills 功能帮助 agents 更好地工作" (NOT: "克劳德的技能功能帮助代理更好地工作")

Example of CORRECT translation:
English: "Use the React component with Node.js"
French: "Utilisez le composant React avec Node.js" (NOT: "Utilisez le composant Réagir avec Noeud.js")
```

#### Translation Process

For each target language (en, zh, fr):

1. **Prepare content for translation**:
   - Combine title, description, and main content
   - Ensure code blocks are clearly marked
   - Keep image references intact
   - Mark terms to preserve (see list above)

2. **Request translation**:
   - Ask for professional translation to the target language
   - Specify that this is technical documentation
   - Emphasize the need to preserve Markdown formatting and code blocks
   - **CRITICAL**: List all terms that must NOT be translated (from the preserve list above)

   Example request format:
   ```
   Please translate the following article to Chinese (zh).
   This is technical documentation - preserve all Markdown syntax, code blocks,
   and image references exactly as they appear.

   CRITICAL: DO NOT translate these terms - keep them in English:
   - Claude, Anthropic, Skills, Projects, MCP, Agent, SubAgent, Subagents
   - GitHub, Google Drive, Slack, Excel
   - React, Python, Node.js, TypeScript, JavaScript
   - API, SDK, AI, ML, RAG, UI, UX, REST, HTTP
   - All variable names, function names, and class names in code blocks

   Why preserve: These are proper names, brand names, or universal technical terms.
   Translating them would confuse readers.

   Example correct translation:
   WRONG: "克劳德的技能功能帮助代理更好地工作"
   CORRECT: "Claude 的 Skills 功能帮助 agents 更好地工作"

   Article to translate:
   [Article content here]
   ```

3. **Translation will automatically apply**:
   - Professional translation quality (via translator skill)
   - **Preserves specified English terms in all languages**
   - Preservation of all Markdown syntax
   - Code blocks remain unchanged (including identifiers)
   - Image references stay the same (paths unchanged)
   - Heading hierarchy maintained
   - Technical terms handled appropriately for target language
   - Natural, fluent target language text

4. **Language-specific handling**:
   - **Chinese (zh)**: Simplified Chinese, technical terms stay in English when appropriate
     - Format: English term with normal text (e.g., "Skills 功能" not "技能功能")
     - No extra spaces needed around English terms
   - **French (fr)**: Standard French technical terminology, formal tone
     - English terms remain in original form
   - **English (en)**: Clear, professional US English

5. **Quality considerations**:
   - Translation preserves the original meaning and intent
   - Technical accuracy is maintained
   - Content reads naturally in the target language
   - Format and structure remain identical to source

6. **Save translations**:
   - Save original English version first
   - Then save each translated version
   - Maintain consistent file structure across all languages

**Output**: Three complete article versions (en, zh, fr)

### Step 6: Create/Update meta.json for All Languages

**Purpose**: Ensure proper sidebar navigation with localized titles for all languages

**CRITICAL**: Create proper meta.json files for sidebar navigation with localized titles.

Load reference files:
- `references/category-translations.json` - Get translated category names
- `references/category-icons.json` - Get appropriate icons

For **each language** (en, zh, fr):

1. **Create/Update category meta.json**: `content/docs/{lang}/{category}/meta.json`

   ```json
   {
     "title": "{translated_category_name}",
     "icon": "{category_icon}",
     "pages": ["{article-slug}", "..."],
     "defaultOpen": false
   }
   ```

   **Example for ai-ml category:**
   - **English** (`content/docs/en/ai-ml/meta.json`):
     ```json
     {
       "title": "AI & Machine Learning",
       "icon": "Brain",
       "pages": ["{article-slug}", "..."],
       "defaultOpen": false
     }
     ```

   - **Chinese** (`content/docs/zh/ai-ml/meta.json`):
     ```json
     {
       "title": "AI 与机器学习",
       "icon": "Brain",
       "pages": ["{article-slug}", "..."],
       "defaultOpen": false
     }
     ```

   - **French** (`content/docs/fr/ai-ml/meta.json`):
     ```json
     {
       "title": "IA et Apprentissage Automatique",
       "icon": "Brain",
       "pages": ["{article-slug}", "..."],
       "defaultOpen": false
     }
     ```

2. **Handling existing meta.json:**
   - If file exists, read current `pages` array
   - Ask user: "Where to add new article? (1: top, 2: bottom, 3: alphabetical)"
   - Preserve other user customizations (icon, defaultOpen, etc.)
   - If `pages` array exists, insert article slug; if not, create with `["{slug}", "..."]`

3. **Update/Create root meta.json**: `content/docs/{lang}/meta.json`

   - Check if category is listed in root `pages` array
   - If not, ask user: "Add '{category}' to root navigation? (yes/no)"
   - If yes, ask: "Where to add? (1: top, 2: bottom, 3: after specific item)"

   **Example root meta.json:**
   ```json
   {
     "title": "Documentation",
     "pages": [
       "index",
       "getting-started",
       "---[Book]Categories---",
       "ai-ml",
       "development",
       "data",
       "..."
     ]
   }
   ```

4. **Translation mapping for all 8 categories:**

   | Category | English | Chinese | French |
   |----------|---------|---------|--------|
   | ai-ml | AI & Machine Learning | AI 与机器学习 | IA et Apprentissage Automatique |
   | development | Development | 开发 | Développement |
   | data | Data | 数据 | Données |
   | design | Design | 设计 | Design |
   | content | Content | 内容 | Contenu |
   | business | Business | 商业 | Affaires |
   | devops | DevOps | DevOps | DevOps |
   | security | Security | 安全 | Sécurité |

5. **Icon mapping for categories:**

   | Category | Icon | Alternative Icons |
   |----------|------|-------------------|
   | ai-ml | Brain | Cpu, Zap, Sparkles |
   | development | Code | Terminal, Braces, FileCode |
   | data | Database | BarChart, PieChart, TrendingUp |
   | design | Palette | Paintbrush, Layers, Layout |
   | content | FileText | BookOpen, Book, FileEdit |
   | business | Briefcase | TrendingUp, DollarSign, Users |
   | devops | Server | Cloud, Container, GitBranch |
   | security | Shield | Lock, ShieldCheck, Key |

**Important Notes:**
- Always create meta.json for ALL 3 languages (en, zh, fr), not just English
- Use localized titles from the translation mapping
- Use the `...` syntax to auto-include other pages: `["featured-article", "..."]`
- Never hardcode English titles in non-English meta.json files
- Preserve user's existing customizations when updating

**Output**: meta.json files created/updated for all languages with proper navigation structure

### Step 7: Package and Validate

**Purpose**: Ensure articles are ready for publication

**Validation checklist**:

✅ **Content validation**:
- [ ] MDX syntax is correct
- [ ] All components are properly imported
- [ ] Frontmatter is valid YAML
- [ ] SourceAttribution component is present
- [ ] Links are working
- [ ] Code blocks are syntax-highlighted

✅ **Build validation**:
- [ ] `npm run build` completes without errors
- [ ] All language versions render correctly
- [ ] No missing imports or undefined components
- [ ] Responsive design works (mobile, tablet, desktop)

✅ **Quality checks**:
- [ ] Article is comprehensive (2000+ words)
- [ ] Examples are practical and clear
- [ ] Best practices are highlighted
- [ ] Related articles are cross-referenced
- [ ] Summary provides actionable next steps

✅ **Multi-language verification**:
- [ ] All 3 language versions created (en, zh, fr)
- [ ] Technical terms preserved in all languages (Claude, Skills, MCP, etc.)
- [ ] meta.json files created/updated for all languages
- [ ] Category titles properly localized
- [ ] Navigation structure consistent across languages

**Output**: Production-ready articles in three languages

**Expected file structure**:
```
content/docs/
├── en/{category}/
│   ├── meta.json (English category title)
│   └── {article-slug}.mdx
├── zh/{category}/
│   ├── meta.json (Chinese category title)
│   └── {article-slug}.mdx
└── fr/{category}/
    ├── meta.json (French category title)
    └── {article-slug}.mdx
```

**Summary report template**:
```
✅ Article Creation Complete!

📄 Article: {title}
🔗 Source Skill: {skill-name}
📁 Category: {category}
🏷️  Tags: {tag1, tag2, tag3, ...}

📝 Files Created:
  ✅ en: content/docs/en/{category}/{slug}.mdx
  ✅ zh: content/docs/zh/{category}/{slug}.mdx
  ✅ fr: content/docs/fr/{category}/{slug}.mdx

📂 Navigation (meta.json):
  ✅ en: content/docs/en/{category}/meta.json ("{English Category Name}")
  ✅ zh: content/docs/zh/{category}/meta.json ("{Chinese Category Name}")
  ✅ fr: content/docs/fr/{category}/meta.json ("{French Category Name}")
  📌 Article added to sidebar navigation
  🎨 Icon: {category_icon}

🎨 Article Cover (Step 4.5):
  ✅ Generated SVG illustration using philosophical-illustrator
  📁 Saved to: public/images/docs/{slug}/cover.svg
  🎨 Color palette: {palette_name} ({domain} domain)
  📏 Dimensions: 800x450px
  🔗 Referenced in frontmatter: image: /images/docs/{slug}/cover.svg
  ✨ Visual theme: {theme_description}
  🌐 Shared across all language versions (language-agnostic)
  (Or: ⚠️  Cover generation skipped/failed - article continues without image)

🌐 Multi-Language Processing:
  ✅ Technical terms preserved: Claude, Skills, MCP, Agent, API, SDK
  ✅ Code blocks unchanged across all languages
  ✅ Frontmatter properly localized
  ✅ All language versions validated

🎉 Next Steps:
  1. Review generated MDX files for accuracy
  2. Test article in local Fumadocs (npm run dev)
  3. Verify all language versions render correctly
  4. Check navigation in all languages
  5. Run build to ensure no errors (npm run build)
```

## Article Structure Template

Generated articles follow this proven structure:

```
1. Introduction (what is this skill?)
2. Skill Anatomy (directory structure)
3. Bundled Resources (scripts, references, assets)
4. Technical Deep Dive (how it works)
5. Usage Examples (practical demonstrations)
6. Best Practices (design principles)
7. Integration Patterns (with other skills)
8. Real-World Use Cases
9. Troubleshooting Guide
10. Conclusion and Next Steps
```

### Component Usage Guide

**Recommended Fumadocs components**:

- **`<Callout type="info|warn|tip|error">`**: Highlight important points
- **`<Cards>` + `<Card>`**: Group related concepts
- **`<Steps>` + `<Step>`**: Show procedural workflows
- **`<Files>` + `<Folder>` + `<File>`**: Display directory structures
- **`<Tabs>` + `<Tab>`**: Show alternative approaches

**Writing pattern example**:

```mdx
<Callout type="info">
  This is a production-ready skill from the Anthropic repository.
</Callout>

<CodeBlock title="Example Usage">
```bash
python script.py --help
```
</CodeBlock>

<Steps>
  <Step>
    **Step 1**: Do this first...
  </Step>
  <Step>
    **Step 2**: Then do this...
  </Step>
</Steps>
```

## Examples

### Example 1: Analyzing skill-creator

**Source**: `github.com/anthropics/skills/tree/main/skill-creator`

**Analysis output**:
```json
{
  "name": "skill-creator",
  "complexity": "moderate",
  "resource_types": ["scripts"],
  "key_features": [
    "6-step creation process",
    "Progressive disclosure pattern",
    "Validation and packaging"
  ]
}
```

**Generated article**: See `examples/skill-creator-output.md`

### Example 2: Analyzing mcp-builder

**Source**: `github.com/anthropics/skills/tree/main/mcp-builder`

**Analysis output**:
```json
{
  "name": "mcp-builder",
  "complexity": "complex",
  "resource_types": ["scripts", "references"],
  "key_features": [
    "MCP specification analysis",
    "Server implementation guidance",
    "Tool definition workflows"
  ]
}
```

## Best Practices

### When to Use This Skill

✅ **DO use skill-article-writer when**:
- You need to document an existing skill
- Creating tutorials for internal skill development
- Analyzing best practices from example skills
- Generating educational content for the Claude community
- Creating multi-language documentation

❌ **DON'T use skill-article-writer when**:
- Writing about non-skill topics (use direct writing instead)
- Creating quick notes or brief summaries
- Documenting one-off workflows
- The source skill is not from Anthropic skills repository

### Article Quality Standards

Each generated article should:

1. **Be comprehensive**: Cover all aspects of the skill (2000-4000 words)
2. **Include practical examples**: Show real usage with code snippets
3. **Follow proven structure**: Use the template sections consistently
4. **Be accessible**: Provide context for readers unfamiliar with the domain
5. **Be actionable**: Include clear next steps and related resources

### Multi-Language Quality Standards

**Translation Quality**:
- **Preserve English terms** (see Terms to Preserve list in Step 5)
  - Claude, Skills, Projects, MCP, Agent, SubAgent
  - GitHub, Google Drive, Slack, Excel
  - React, Python, Node.js, TypeScript
  - API, SDK, AI, ML, RAG, UI, UX
  - All variable/function/class names in code
- Technical accuracy is paramount
- Preserve code examples exactly (including identifiers)
- Adapt cultural references when necessary
- Use appropriate technical terminology for each language
- **Chinese (zh)**: 使用简体中文，技术术语保持英文
  - Example: "Claude 的 Skills 功能" (NOT: "克劳德的技能功能")
  - Example: "使用 React 组件" (NOT: "使用回应组件")
- **French (fr)**: Maintain formal tone, keep English terms as-is
  - Example: "La fonctionnalité Skills de Claude" (NOT translated)
  - Example: "Utilisez le composant React" (NOT: "Réagir")

**File Organization**:
Follow Fumadocs conventions:
- Language-specific directories: `content/docs/{lang}/` (en, zh, fr)
- Category subdirectories: `content/docs/{lang}/{category}/`
- meta.json files: Localized category titles for each language
- Navigation: Consistent structure across all languages

### Writing Style Guidelines

**Critical: Always use imperative/infinitive form**

❌ **Wrong**: "You should run the analysis script"
✅ **Right**: "Run the analysis script to extract metadata"

❌ **Wrong**: "If you want to create an article..."
✅ **Right**: "To create a comprehensive article..."

**Maintain consistency**:
- Verb-first sentences in all instructions
- Clear section headings
- Logical flow from overview to details
- Balanced use of components (not too many, not too few)

## Integration with Other Skills

skill-article-writer works well with:

1. **skill-creator**: Document new skills you create
2. **skill-builder**: Analyze complex skill architectures
3. **translator**: Generate multi-language versions
4. **fumadocs-article-importer**: Import external skill documentation

## Troubleshooting

### Analysis Script Errors

**Symptom**: `analyze_skill.py` reports parsing errors

**Causes**:
- SKILL.md has invalid YAML frontmatter
- File encoding issues
- Missing files or directories

**Solutions**:
1. Verify SKILL.md starts with `---` and has valid YAML
2. Check file encoding is UTF-8
3. Ensure skill directory structure is complete

### Missing Components

**Symptom**: Generated articles don't include expected Fumadocs components

**Cause**: Outline generator creates component placeholders, but they need to be manually expanded

**Solution**: Review the outline and expand component sections with actual content:
- Replace `<Callout>` placeholders with real callouts
- Add examples to `<Steps>` sections
- Fill in `<Cards>` with relevant information

### Translation Issues

**Symptom**: Technical terms like "Skills" or "Agent" are translated

**Cause**: Not following "Terms to Preserve" guidelines

**Solutions**:
1. Maintain the list of English terms that should not be translated:
   - Claude, Skills, SKILL.md, Agent, SubAgent, MCP
   - GitHub, Google Drive, Slack, Excel
   - React, Python, Node.js, TypeScript
   - API, SDK, AI, ML, RAG, UI, UX

2. Check each translation for accidentally translated terms

## Conclusion

**skill-article-writer** provides a systematic way to:

- ✅ Analyze skill structure and extract insights
- ✅ Generate comprehensive tutorial articles
- ✅ Create multi-language documentation efficiently
- ✅ Follow proven patterns for skill explanations
- ✅ Scale documentation creation across many skills

By using this skill, you can create high-quality educational content that helps others understand and use Claude skills effectively.

---

## Appendix

### Related Resources

- **Anthropic Skills Repository**: github.com/anthropics/skills
- **Claude Code Documentation**: claude.ai/docs
- **Fumadocs Documentation**: fumadocs.com
- **Example Skill Articles**: See `examples/` directory

### Article Templates

For different skill types, see:
- `references/article-templates.md` - Template variations
- `examples/skill-creator-output.md` - Full example analysis
- `references/writing-style-guide.md` - Writing conventions

## ℹ️ Source Information

**Base Skill Analysis**: skill-creator
- **Source**: Anthropic Skills Repository
- **Author**: Anthropic
- **License**: See LICENSE.txt

*This skill was created by analyzing best practices from skill-creator and applying them to the domain of skill documentation.*


---

## Referenced Files

> The following files are referenced in this skill and included for context.

### scripts/analyze_skill.py

```python
#!/usr/bin/env python3
"""
Analyze a skill structure and generate metadata for article creation.

Usage:
    python analyze_skill.py <skill-path> [--output <output-file>]

Examples:
    python analyze_skill.py /path/to/skill-creator
    python analyze_skill.py /path/to/skill-creator --output skill-metadata.json
"""

import json
import sys
import argparse
from pathlib import Path
from typing import Dict, Any, List


def analyze_skill(skill_path: Path) -> Dict[str, Any]:
    """Analyze a skill directory and extract comprehensive metadata."""

    metadata = {
        "skill_path": str(skill_path),
        "name": skill_path.name,
        "exists": skill_path.exists(),
        "structure": {},
        "skill_md": {},
        "scripts": [],
        "references": [],
        "assets": [],
        "analysis": {
            "complexity": "unknown",
            "resource_types": [],
            "key_features": [],
            "recommendations": []
        }
    }

    if not skill_path.exists():
        return metadata

    # Analyze directory structure
    structure_analysis = analyze_structure(skill_path)
    metadata["structure"] = structure_analysis

    # Analyze SKILL.md
    skill_md_path = skill_path / "SKILL.md"
    if skill_md_path.exists():
        skill_md_analysis = analyze_skill_md(skill_md_path)
        metadata["skill_md"] = skill_md_analysis

    # Analyze bundled resources
    metadata["scripts"] = list_resource_files(skill_path / "scripts", ["*.py", "*.sh", "*.js"])
    metadata["references"] = list_resource_files(skill_path / "references", ["*.md", "*.txt", "*.json"])
    metadata["assets"] = list_resource_files(skill_path / "assets", ["*"])

    # Generate skill-level analysis
    metadata["analysis"] = generate_skill_analysis(metadata)

    return metadata


def analyze_structure(skill_path: Path) -> Dict[str, Any]:
    """Analyze the directory structure of a skill."""

    return {
        "has_skill_md": (skill_path / "SKILL.md").exists(),
        "has_scripts": (skill_path / "scripts").exists(),
        "has_references": (skill_path / "references").exists(),
        "has_assets": (skill_path / "assets").exists(),
        "total_files": count_files(skill_path),
        "depth": get_directory_depth(skill_path)
    }


def analyze_skill_md(skill_md_path: Path) -> Dict[str, Any]:
    """Analyze the SKILL.md file."""

    try:
        with open(skill_md_path, 'r', encoding='utf-8') as f:
            content = f.read()

        return {
            "exists": True,
            "size": len(content),
            "line_count": len(content.split('\n')),
            "has_yaml_frontmatter": content.startswith('---\n'),
            "sections": extract_sections(content),
            "title": extract_title(content),
            "description": extract_description(content),
            "commands": extract_commands(content)
        }
    except Exception as e:
        return {
            "exists": True,
            "error": str(e),
            "size": 0,
            "line_count": 0
        }


def extract_sections(content: str) -> List[str]:
    """Extract major section headings from SKILL.md."""

    sections = []
    for line in content.split('\n'):
        line = line.strip()
        if line.startswith('## '):
            section = line[3:].strip()
            if section and not section.startswith('---'):
                sections.append(section)
    return sections


def extract_title(content: str) -> str:
    """Extract the skill name from frontmatter or first heading."""

    if content.startswith('---'):
        parts = content.split('\n---', 1)
        if len(parts) == 2:
            frontmatter = parts[0]
            lines = frontmatter.split('\n')
            for line in lines:
                if line.startswith('name: '):
                    return line[6:].strip().strip('"\'')

    # Fallback: find first H1
    for line in content.split('\n'):
        if line.startswith('# '):
            return line[2:].strip()

    return "Unknown Skill"


def extract_description(content: str) -> str:
    """Extract skill description from frontmatter."""

    if content.startswith('---'):
        parts = content.split('\n---', 1)
        if len(parts) == 2:
            frontmatter = parts[0]
            lines = frontmatter.split('\n')
            for line in lines:
                if line.startswith('description: '):
                    desc = line[13:].strip().strip('"\'')
                    return desc if len(desc) < 200 else desc[:200] + "..."

    return "No description available"


def extract_commands(content: str) -> List[str]:
    """Extract command-line examples from the content."""

    commands = []
    in_code_block = False
    current_block = []

    for line in content.split('\n'):
        if line.startswith('```bash'):
            in_code_block = True
            current_block = []
        elif line.startswith('```') and in_code_block:
            in_code_block = False
            block_content = '\n'.join(current_block).strip()
            if block_content:
                commands.append(block_content)
        elif in_code_block:
            current_block.append(line)

    return commands


def list_resource_files(resource_path: Path, patterns: List[str]) -> List[str]:
    """List files in a resource directory."""

    if not resource_path.exists() or not resource_path.is_dir():
        return []

    files = []
    for pattern in patterns:
        files.extend([str(p.relative_to(resource_path)) for p in resource_path.glob(pattern)])

    return sorted(files)


def count_files(directory: Path) -> int:
    """Count total files in directory."""

    try:
        return len(list(directory.rglob('*'))) if directory.exists() else 0
    except:
        return 0


def get_directory_depth(directory: Path) -> int:
    """Get maximum directory depth."""

    if not directory.exists():
        return 0

    max_depth = 0
    for path in directory.rglob('*'):
        if path.is_file():
            depth = len(path.relative_to(directory).parts) - 1
            max_depth = max(max_depth, depth)
    return max_depth


def generate_skill_analysis(metadata: Dict[str, Any]) -> Dict[str, Any]:
    """Generate high-level analysis of the skill."""

    analysis = {
        "complexity": determine_complexity(metadata),
        "resource_types": identify_resource_types(metadata),
        "key_features": extract_key_features(metadata),
        "recommendations": generate_recommendations(metadata)
    }

    return analysis


def determine_complexity(metadata: Dict[str, Any]) -> str:
    """Determine skill complexity level."""

    script_count = len(metadata.get("scripts", []))
    ref_count = len(metadata.get("references", []))
    asset_count = len(metadata.get("assets", []))

    total_resources = script_count + ref_count + asset_count

    if total_resources == 0:
        return "simple"
    elif total_resources <= 3:
        return "moderate"
    else:
        return "complex"


def identify_resource_types(metadata: Dict[str, Any]) -> List[str]:
    """Identify what types of resources the skill uses."""

    types = []
    if metadata.get("scripts"):
        types.append("scripts")
    if metadata.get("references"):
        types.append("references")
    if metadata.get("assets"):
        types.append("assets")
    return types


def extract_key_features(metadata: Dict[str, Any]) -> List[str]:
    """Extract key features based on skill content."""

    features = []

    # Check for common patterns
    skill_md = metadata.get("skill_md", {})
    if skill_md:
        content = skill_md.get("content", "")
        if "workflow" in content.lower():
            features.append("workflow-automation")
        if "script" in content.lower():
            features.append("scripting")
        if "API" in content.lower():
            features.append("api-integration")
        if any(word in content.lower() for word in ["create", "generate", "build"]):
            features.append("content-generation")

    return features


def generate_recommendations(metadata: Dict[str, Any]) -> List[str]:
    """Generate recommendations for article structure."""

    recs = []
    analysis = metadata.get("analysis", {})

    complexity = analysis.get("complexity", "simple")
    if complexity == "complex":
        recs.append("Use detailed sections for each resource type")
        recs.append("Include comprehensive examples")
    else:
        recs.append("Keep sections concise and focused")

    resource_types = analysis.get("resource_types", [])
    if "scripts" in resource_types:
        recs.append("Document each script's purpose and usage")
    if "references" in resource_types:
        recs.append("Explain when and how to load reference files")
    if "assets" in resource_types:
        recs.append("Show examples of asset usage in output")

    return recs


def main():
    parser = argparse.ArgumentParser(description="Analyze a Claude skill structure")
    parser.add_argument("skill_path", help="Path to the skill directory")
    parser.add_argument("--output", help="Output JSON file (default: stdout)")

    args = parser.parse_args()

    skill_path = Path(args.skill_path)

    if not skill_path.exists():
        print(f"Error: Path does not exist: {skill_path}", file=sys.stderr)
        sys.exit(1)

    metadata = analyze_skill(skill_path)

    if args.output:
        output_path = Path(args.output)
        with open(output_path, 'w', encoding='utf-8') as f:
            json.dump(metadata, f, indent=2, ensure_ascii=False)
        print(f"Metadata saved to: {output_path}")
    else:
        print(json.dumps(metadata, indent=2, ensure_ascii=False))


if __name__ == "__main__":
    main()

```

### scripts/generate_article_outline.py

```python
#!/usr/bin/env python3
"""
Generate article outline based on skill analysis metadata.

Usage:
    python generate_article_outline.py <skill-metadata.json> [--output <outline.md>]

Examples:
    python generate_article_outline.py skill-metadata.json
    python generate_article_outline.py skill-metadata.json --output article-outline.md
"""

import json
import sys
import argparse
from pathlib import Path
from typing import Dict, Any


def generate_outline(metadata: Dict[str, Any]) -> str:
    """Generate a complete article outline based on skill metadata."""

    skill_name = metadata.get("name", "Unknown Skill")
    description = metadata.get("skill_md", {}).get("description", "No description available")
    sections = metadata.get("skill_md", {}).get("sections", [])
    analysis = metadata.get("analysis", {})

    outline = f"""---
title: "Analyzing {skill_name}: A Complete Guide"  # Will be translated
description: "{description[:150]}..."  # Will be translated
lang: {{{{language}}}}
category: development
difficulty: intermediate
tags:
  - claude-skills
  - skill-analysis
  - tutorial
source_url: "{{{{source_url}}}}"
published_date: "{{{{published_date}}}}"
author: Anthropic
source:
  url: "{{{{source_url}}}}"
  name: "Anthropic Skills Repository"
  author: "Anthropic"
  published_date: "{{{{published_date}}}}"
  accessed_date: "{{{{current_date}}}}"
  license: "See SKILL.md for terms"
import:
  date: "{{{{current_date}}}}"
  slug: "{{{{slug_from_url(source_url)}}}}"
  translator: "Claude AI"
---

import {{ SourceAttribution }} from '@/components/SourceAttribution';
import {{ Callout }} from 'fumadocs-ui/components/callout';
import {{ Cards, Card }} from 'fumadocs-ui/components/card';
import {{ Steps, Step }} from 'fumadocs-ui/components/steps';

<SourceAttribution
  source={{{{...}}}}
  languages={{{{['en', 'zh', 'fr']}}}}
  currentLang={{{{language}}}}
/>

# Analyzing {skill_name}

**{skill_name}** is {{description}} This article provides a comprehensive analysis of its structure, design patterns, and practical applications.

<Callout type="info">
  This is a real-world skill from the Anthropic skills repository, designed to {{description.lower().split()[0]}}.
</Callout>

## Overview

### What is {skill_name}?

<Callout type="question">
  Based on the description: {description}
</Callout>

### Core Purpose

The {skill_name} skill aims to:

{{generate_purpose_bullet_points(description)}}

### Target Audience

This skill is designed for:

- Users who want to...
- Developers working with...
- Anyone interested in...

## Skill Anatomy

### Directory Structure

```
{skill_name}/
├── SKILL.md (required)
└── Bundled Resources (optional)
    ├── scripts/          - Executable code
    ├── references/       - Documentation
    └── assets/           - Templates and files
```

### SKILL.md Structure

Every skill begins with metadata in YAML frontmatter:

```yaml
---
name: {skill_name}
description: "{description}"
license: See SKILL.md for terms
---
```

### Key Components

{{generate_component_sections(metadata)}}

## Technical Deep Dive

### How It Works

<Steps>
  <Step>
    **Trigger Detection**: Claude identifies when this skill should be used based on the description and user query.
  </Step>
  <Step>
    **Context Loading**: SKILL.md content is loaded into Claude's context window.
  </Step>
  <Step>
    **Resource Access**: If needed, Claude loads or references bundled resources.
  </Step>
  <Step>
    **Execution**: Claude follows the procedural instructions to complete the task.
  </Step>
</Steps>

### Detailed Workflow

{{generate_workflow_section(metadata)}}

## Usage Examples

### Basic Usage

```bash
{{generate_basic_usage(metadata)}}
```

### Advanced Scenarios

<Callout type="tip">
  Best practices and advanced usage patterns.
</Callout>

## Best Practices

Based on the design of {skill_name}, here are key principles:

{{generate_best_practices(metadata)}}

## Common Pitfalls

<Callout type="warn">
  Common mistakes users make when working with this skill.
</Callout>

{{generate_common_pitfalls(metadata)}}

## Integration with Other Skills

{skill_name} works well with:

1. **skill-creator** - For creating new skills based on this pattern
2. **skill-builder** - For extending functionality
3. **Other related skills**

## Real-World Applications

### Use Case 1: {{Use Case Description}}

Practical example of how this skill solves a real problem...

### Use Case 2: {{Another Use Case}}

Another practical example with specific details...

## Troubleshooting

<Callout type="error">
  Common errors and their solutions.
</Callout>

{{generate_troubleshooting_section(metadata)}}

## Next Steps

To use {skill_name} effectively:

1. **Clone the repository**: {{repository_url}}
2. **Install dependencies**: {{install_commands}}
3. **Follow the workflow**: {{workflow_instructions}}
4. **Iterate based on feedback**: {{iteration_tips}}

### Related Resources

- **Anthropic Skills Repository**: github.com/anthropics/skills
- **Creating Your First Skill**: /tutorials/creating-first-skill
- **Advanced Skill Development**: /development/advanced-skills

## Conclusion

{skill_name} demonstrates excellent Claude skill design by:

{{generate_conclusion_points(metadata)}}

The key insights from this skill can be applied to your own skill development projects.

---

## Summary

This analysis covered:

- ✅ Skill structure and anatomy
- ✅ Core workflow and execution flow
- ✅ Best practices and design patterns
- ✅ Real-world usage examples
- ✅ Integration strategies
- ✅ Troubleshooting guide

## Next Steps

Ready to apply what you learned?

1. **Study other skills** in the repository
2. **Create your own skill** using these patterns
3. **Share your skills** with the community
4. **Iterate and improve** based on usage

## ℹ️ Source Information

**Original Skill**: [{{skill_name}}]({{source_url}})

- **Source**: Anthropic Skills Repository
- **Author**: Anthropic
- **Accessed**: {{current_date}}
- **License**: See SKILL.md for full terms

*This article was automatically generated based on skill analysis.*

---

## Appendix

### Directory Structure Details

{{generate_directory_details(metadata)}}

### Resource Inventory

<Callout type="info">
  Complete listing of all resources included in this skill.
</Callout>

**Scripts**:
{{generate_resources_list(metadata.get("scripts", []))}}

**References**:
{{generate_resources_list(metadata.get("references", []))}}

**Assets**:
{{generate_resources_list(metadata.get("assets", []))}}
"""

    return outline


def generate_purpose_bullet_points(description: str) -> str:
    """Generate purpose bullet points from description."""

    return """- Automate repetitive tasks
- Provide specialized workflows
- Integrate domain knowledge
- Improve efficiency and consistency"""


def generate_component_sections(metadata: Dict[str, Any]) -> str:
    """Generate component analysis sections."""

    sections = []

    if metadata.get("scripts"):
        sections.append("""### Scripts

<Callout type="info">
  Scripts provide deterministic, reusable code that Claude can execute.
</Callout>

The {skill_name} includes scripts for:

- **init_skill.py**: Initialize a new skill with proper structure
- **package_skill.py**: Package and validate skills for distribution

Each script serves a specific purpose in the skill creation workflow.
""")

    if metadata.get("references"):
        sections.append("""### References

Reference files provide domain knowledge that Claude loads on-demand:

- **schemas.md**: Database schemas and data models
- **policies.md**: Company policies and guidelines
- **API specifications**: API documentation and examples
""")

    if metadata.get("assets"):
        sections.append("""### Assets

Asset files are used in the final output without being loaded into Claude's context:

- **Templates**: HTML/React boilerplate
- **Images**: Logos, icons, and visual assets
- **Sample data**: Example files for demonstration
""")

    return "\n\n".join(sections) if sections else "No bundled resources found."


def generate_workflow_section(metadata: Dict[str, Any]) -> str:
    """Generate workflow analysis section."""

    sections = metadata.get("skill_md", {}).get("sections", [])

    if len(sections) >= 3:
        return f"""### Core Workflow

The skill follows a structured workflow with {len(sections)} major steps:

<Steps>
  <Step>
    **{sections[0]}**: First step in the process...
  </Step>
  <Step>
    **{sections[1]}**: Second step with specific actions...
  </Step>
  <Step>
    **{sections[2]}**: Final step to complete the workflow...
  </Step>
</Steps>

Detailed explanation of each step and how they connect...
"""
    else:
        return """### Core Workflow

The skill provides a clear workflow that Claude follows to accomplish tasks effectively.

<Callout type="question">
  Review the SKILL.md sections to understand the detailed workflow:
</Callout>
"""


def generate_basic_usage(metadata: Dict[str, Any]) -> str:
    """Generate basic usage example."""

    skill_name = metadata.get("name", "unknown")
    return f"# Example usage for {skill_name}\n./scripts/run_{skill_name}.py --help"


def generate_best_practices(metadata: Dict[str, Any]) -> str:
    """Generate best practices section."""

    return """<Cards>
  <Card title="Progressive Disclosure" icon="Layers">
    Load information in three levels: metadata, SKILL.md, and bundled resources.
  </Card>

  <Card title="Avoid Duplication" icon="FileText">
    Keep detailed reference material in references/ files, not in SKILL.md
  </Card>

  <Card title="Test & Iterate" icon="RefreshCw">
    Use the skill on real tasks to identify improvements and update accordingly.
  </Card>
</Cards>
"""


def generate_common_pitfalls(metadata: Dict[str, Any]) -> str:
    """Generate common pitfalls section."""

    return """- **Overloading SKILL.md**: Don't include excessive detail in the main skill file.
- **Missing Context**: Ensure bundled resources are properly referenced.
- **Unclear Triggers**: Make the description specific about when to use the skill.
- **Ignoring Validation**: Always use package_skill.py before distribution.
"""


def generate_troubleshooting_section(metadata: Dict[str, Any]) -> str:
    """Generate troubleshooting section."""

    return """### Validation Errors

**Symptom**: package_skill.py reports validation errors

**Solution**: Run the script and fix all reported issues before packaging.

### Missing Resources

**Symptom**: Claude cannot find referenced files

**Solution**: Verify all paths in SKILL.md and ensure files exist.

### Skill Not Triggering

**Symptom**: Claude doesn't recognize when to use the skill

**Solution**: Make the description more specific and include trigger phrases.
"""


def generate_conclusion_points(metadata: Dict[str, Any]) -> str:
    """Generate conclusion bullet points."""

    return """- ✅ Systematically extending Claude's capabilities
- ✅ Managing context efficiently
- ✅ Providing reusable resources
- ✅ Maintaining high quality through validation
- ✅ Following proven design patterns"""


def generate_resources_list(resources: list) -> str:
    """Generate a markdown list of resources."""

    if not resources:
        return "- None"

    return "\n".join([f"- {res}" for res in resources])


def generate_directory_details(metadata: Dict[str, Any]) -> str:
    """Generate directory structure details."""

    return """### Required Files

- **SKILL.md**: The core skill definition with metadata and instructions

### Optional Directories

- **scripts/**: Executable code for the skill
- **references/**: Documentation and reference material
- **assets/**: Templates, images, and output files

### Best Practices

- Keep SKILL.md under 5k words for optimal loading
- Use descriptive names for all resources
- Follow the six-step skill creation process"""


def main():
    parser = argparse.ArgumentParser(description="Generate article outline from skill metadata")
    parser.add_argument("metadata_file", help="Path to the skill metadata JSON file")
    parser.add_argument("--output", help="Output markdown file (default: stdout)")

    args = parser.parse_args()

    metadata_path = Path(args.metadata_file)

    if not metadata_path.exists():
        print(f"Error: File not found: {metadata_path}", file=sys.stderr)
        sys.exit(1)

    try:
        with open(metadata_path, 'r', encoding='utf-8') as f:
            metadata = json.load(f)
    except Exception as e:
        print(f"Error reading metadata: {e}", file=sys.stderr)
        sys.exit(1)

    outline = generate_outline(metadata)

    if args.output:
        output_path = Path(args.output)
        with open(output_path, 'w', encoding='utf-8') as f:
            f.write(outline)
        print(f"Outline saved to: {output_path}")
    else:
        print(outline)


if __name__ == "__main__":
    main()

```

### examples/skill-creator-output.md

```markdown
# Analyzing skill-creator: A Complete Guide

**skill-creator** is a Claude skill that provides a systematic approach to creating high-quality Claude skills. This article provides a comprehensive analysis of its structure, design patterns, and practical applications.

<Callout type="info">
  This is a real-world skill from the Anthropic skills repository, designed to provide a systematic approach to creating high-quality Claude skills.
</Callout>

## Overview

### What is skill-creator?

<Callout type="question">
  Based on the description: Create a structured, well-documented skill that follows community best practices
</Callout>

### Core Purpose

The skill-creator skill aims to:

- Automate repetitive tasks
- Provide specialized workflows
- Integrate domain knowledge
- Improve efficiency and consistency

### Target Audience

This skill is designed for:

- Users who want to create their own Claude skills
- Developers working with Claude Code
- Anyone interested in systematic skill development

## Skill Anatomy

### Directory Structure

```
skill-creator/
├── SKILL.md (required)
└── Bundled Resources (optional)
    ├── scripts/
    └── references/
        └── article-templates.md
```

### SKILL.md Structure

Every skill begins with metadata in YAML frontmatter:

```yaml
---
name: skill-creator
description: "Create a structured, well-documented skill that follows community best practices"
license: See LICENSE.txt
---
```

### Key Components

### Scripts

<Callout type="info">
  Scripts provide deterministic, reusable code that Claude can execute.
</Callout>

The skill-creator includes scripts for:

<Steps>
  <Step>
    **Step 1**: Initialize a new skill with proper structure
  </Step>
  <Step>
    **Step 2**: Package and validate skills for distribution
  </Step>
</Steps>

Each script serves a specific purpose in the skill creation workflow.

### References

Reference files provide domain knowledge that Claude loads on-demand:

- **article-templates.md**: Template patterns for different skill types

## Technical Deep Dive

### How It Works

<Steps>
  <Step>
    **Trigger Detection**: Claude identifies when this skill should be used based on the description and user query.
  </Step>
  <Step>
    **Context Loading**: SKILL.md content is loaded into Claude's context window.
  </Step>
  <Step>
    **Resource Access**: If needed, Claude loads or references bundled resources.
  </Step>
  <Step>
    **Execution**: Claude follows the procedural instructions to complete the task.
  </Step>
</Steps>

### The 6-Step Skill Creation Process

The skill follows a structured workflow with 6 major steps:

<Steps>
  <Step>
    **Step 1: Understand the Skill's Purpose**: Conduct a 30-minute discovery session to understand what problem the skill solves, its target audience, and the workflows it should enable. Discuss with the user or research the domain to gather requirements. If this is based on an existing skill from the Anthropic repository, carefully analyze its structure, resources, and workflows to extract best practices and design patterns.
  </Step>
  <Step>
    **Step 2: Design the Directory Structure**: Based on the skill's purpose, design an appropriate directory structure. Determine what resources to bundle: scripts for deterministic tasks, references for domain knowledge, and assets for templates or sample files. Follow the three-level progressive disclosure model: SKILL.md (always loaded), scripts/references (loaded on-demand), and directory structure (for organization).
  </Step>
  <Step>
    **Step 3: Create SKILL.md**: Write a comprehensive SKILL.md following this structure:
    - YAML frontmatter with name, description, and license
    - Clear description of what the skill does
    - Prerequisites section
    - How the skill works (execution flow)
    - Detailed workflows or procedures
    - Usage examples with code blocks
    - Best practices and common pitfalls
    - Troubleshooting section
    - Related resources and conclusion

    Use imperative/infinitive command form throughout and include practical examples. If analyzing an existing skill, document its structure, key components, and design patterns thoroughly.
  </Step>
  <Step>
    **Step 4: Create Bundled Resources**: Develop the scripts, references, and assets that support the skill:
    - **Scripts**: Write Python or bash scripts for automation tasks. Include argparse for CLI usage, clear docstrings, and error handling. Follow the #!/usr/bin/env python3 shebang pattern.
    - **References**: Create markdown files with domain knowledge, schemas, policies, or documentation that Claude can reference.
    - **Assets**: Provide sample files, templates, or configuration examples.

    Each resource should serve a specific purpose and be well-documented.
  </Step>
  <Step>
    **Step 5: Test the Skill**: Before deployment, thoroughly test the skill:
    - Create a test directory and try using the skill on real tasks
    - Verify all scripts execute correctly
    - Test reference loading when needed
    - Check that the description triggers appropriately
    - Validate all code examples work as expected
    - Run the skill at least once end-to-end on a real problem

    Iterate based on testing feedback to improve clarity and functionality.
  </Step>
  <Step>
    **Step 6: Package and Validate**: Ensure the skill is production-ready:
    - Verify all file paths and resource references are correct
    - Check YAML frontmatter syntax
    - Validate markdown and code block formatting
    - Remove or comment out any draft content
    - Create or update navigation files (meta.json) if needed
    - Consider creating related articles or documentation for complex skills

    The final skill should be ready for use in Claude Code immediately.
  </Step>
</Steps>

Detailed explanation of each step and how they connect...

### Detailed Workflow

<Callout type="info">
  This skill follows a structured approach to ensure quality and consistency in Claude skill development.
</Callout>

The workflow demonstrates several key design patterns:

**Progressive Disclosure**: Information is structured in three levels:
1. YAML frontmatter provides metadata
2. SKILL.md body contains detailed instructions
3. References contain domain-specific knowledge

**Command-Based Writing**: All instructions use imperative/infinitive form:
- ❌ "You should run the analysis script"
- ✅ "Run the analysis script to extract metadata"

**Practical Examples**: Each step includes concrete examples and expected outputs.

## Usage Examples

### Basic Usage

```bash
cd /path/to/skills/skill-creator
python3 scripts/init_skill.py --help
```

### Advanced Scenarios

<Callout type="tip">
  Best practices and advanced usage patterns.
</Callout>

## Best Practices

Based on the design of skill-creator, here are key principles:

<Cards>
  <Card title="Progressive Disclosure" icon="Layers">
    Load information in three levels: metadata, SKILL.md, and bundled resources.
  </Card>

  <Card title="Avoid Duplication" icon="FileText">
    Keep detailed reference material in references/ files, not in SKILL.md
  </Card>

  <Card title="Test & Iterate" icon="RefreshCw">
    Use the skill on real tasks to identify improvements and update accordingly.
  </Card>
</Cards>

## Common Pitfalls

<Callout type="warn">
  Common mistakes users make when working with this skill.
</Callout>

- **Overloading SKILL.md**: Don't include excessive detail in the main skill file.
- **Missing Context**: Ensure bundled resources are properly referenced.
- **Unclear Triggers**: Make the description specific about when to use the skill.
- **Ignoring Validation**: Always test skills before distribution.

## Integration with Other Skills

skill-creator works well with:

1. **skill-article-writer** - For documenting created skills
2. **skill-packager** - For distributing skills
3. **skill-validator** - For automated testing
4. **Other development skills**

## Real-World Applications

### Use Case 1: Creating a Custom Skill

A development team needs to create a skill for their internal API. Using skill-creator:
1. **Discovery**: Identify API endpoints and common workflows
2. **Structure**: Design scripts/ for API calls, references/ for endpoint docs
3. **SKILL.md**: Document the API integration process
4. **Resources**: Create Python scripts for authentication and data handling
5. **Testing**: Try the skill on real API tasks
6. **Validation**: Package and share with the team

### Use Case 2: Documenting Best Practices

A developer wants to share their skill development patterns:
1. **Analysis**: Study existing successful skills
2. **Structure**: Create references/ with design patterns
3. **SKILL.md**: Document the methodology step-by-step
4. **Resources**: Include templates and examples
5. **Testing**: Validate with other developers
6. **Sharing**: Publish to the community

## Troubleshooting

<Callout type="error">
  Common errors and their solutions.
</Callout>

### Skill Not Triggering

**Symptom**: Claude doesn't suggest using the skill when creating a skill

**Cause**: Description not specific enough or doesn't match user intent

**Solution**:
1. Make description more specific about "creating skills"
2. Include keywords like "skill development", "Claude skill", "SKILL.md"
3. Test with various phrasings: "I want to create a skill", "Help me build a Claude skill"

### Missing Resources

**Symptom**: Claude creates SKILL.md but no scripts or references

**Cause**: User didn't request specific resource types

**Solution**:
1. Always ask about resource needs during discovery
2. Document typical resource patterns in references/
3. Provide examples of skill directory structures

### Incomplete SKILL.md

**Symptom**: Generated SKILL.md is too short or missing sections

**Cause**: Not following the 6-step process completely

**Solution**:
1. Follow each step systematically
2. Ensure all major sections are included
3. Add practical examples for clarity

## Next Steps

To use skill-creator effectively:

1. **Clone the repository**: https://github.com/anthropics/skills
2. **Explore existing skills**: Study skill-creator and related skills
3. **Start creating**: Use the 6-step process for your first skill
4. **Iterate and improve**: Test your skills and refine based on feedback

### Related Resources

- **Anthropic Skills Repository**: github.com/anthropics/skills
- **Claude Code Documentation**: claude.ai/docs
- **Creating Your First Skill**: /tutorials/creating-first-skill

## Conclusion

skill-creator demonstrates excellent Claude skill design by:

- ✅ Providing a systematic approach to skill creation
- ✅ Managing context efficiently with progressive disclosure
- ✅ Offering reusable resources and templates
- ✅ Maintaining high quality through structured workflows
- ✅ Following proven design patterns from the community

The key insights from this skill can be applied to your own skill development projects to create consistent, high-quality skills that extend Claude's capabilities effectively.

---

## Summary

This analysis covered:

- ✅ Skill structure and anatomy (6-step process)
- ✅ Core workflow and execution flow
- ✅ Best practices and design patterns
- ✅ Real-world usage examples
- ✅ Integration strategies
- ✅ Troubleshooting guide

## Next Steps

Ready to apply what you learned?

1. **Study other skills** in the repository
2. **Create your own skill** using the 6-step process
3. **Share your skills** with the community
4. **Iterate and improve** based on usage

## ℹ️ Source Information

**Original Skill**: [skill-creator](https://github.com/anthropics/skills/tree/main/skill-creator)

- **Source**: Anthropic Skills Repository
- **Author**: Anthropic
- **Accessed**: 2025-01-17
- **License**: See LICENSE.txt for full terms

*This article was automatically generated based on skill analysis.*

---

## Appendix

### Directory Structure Details

The skill-creator skill follows the standard Claude skill structure:

**Required Files**:
- **SKILL.md**: The core skill definition with metadata and instructions

**Optional Directories** (skill-creator includes these):
- **scripts/**: No scripts in this skill (it's process-focused)
- **references/**: Contains article-templates.md
- **assets/**: No assets in this version

### Best Practices Checklist

When creating skills using skill-creator patterns:

- ✅ Use YAML frontmatter with name, description, and license
- ✅ Include discovery phase to understand requirements
- ✅ Design appropriate directory structure
- ✅ Follow progressive disclosure principle
- ✅ Write all instructions in imperative/infinitive form
- ✅ Include practical examples and expected outputs
- ✅ Document best practices and common pitfalls
- ✅ Test the skill before deployment
- ✅ Consider multi-language support if needed

```

### references/article-templates.md

```markdown
# Article Templates for Different Skill Types

This reference guide provides templates for different categories of Claude skills to ensure consistent article structure and coverage.

## Template Categories

### 1. Simple Metadata Skills

**Characteristics**: Only SKILL.md, no bundled resources
**Complexity**: Simple
**Focus**: Design patterns, trigger optimization, use cases

**Article Structure**:
```mdx
1. Introduction
2. Why This Skill Works (design principles)
3. SKILL.md Deep Dive (structure analysis)
4. Trigger Optimization (when to use)
5. Real Usage Examples
6. Integration Patterns
7. Conclusion
```

**Example Skills**: `todo-tracker`, `greeting-generator`

---

### 2. Script-Based Skills

**Characteristics**: Contains scripts/, process automation
**Complexity**: Moderate
**Focus**: Workflow automation, script functionality, error handling

**Article Structure**:
```mdx
1. Introduction
2. Problem This Skill Solves
3. Directory Structure (scripts/ emphasis)
4. Script Analysis (each script's purpose)
5. Workflow Deep Dive (execution flow)
6. Usage Examples (command-line demonstrations)
7. Error Handling & Edge Cases
8. Integration Patterns
9. Conclusion
```

**Example Skills**: `skill-creator`, `skill-packager`

---

### 3. Reference-Heavy Skills

**Characteristics**: Large references/ with domain knowledge
**Complexity**: Complex
**Focus**: Progressive disclosure, resource management, domain expertise

**Article Structure**:
```mdx
1. Introduction
2. Domain Overview
3. Progressive Disclosure Design
4. SKILL.md Structure
5. Reference Files Analysis
6. Loading Strategies (when to load references)
7. Usage Patterns
8. Performance Considerations
9. Real-World Applications
10. Conclusion
```

**Example Skills**: `api-contract-manager`, `database-schemas`

---

### 4. Agent-Based Skills

**Characteristics**: Uses subagents, complex workflows
**Complexity**: Complex
**Focus**: Agent patterns, task delegation, concurrent execution

**Article Structure**:
```mdx
1. Introduction
2. Why Use Subagents?
3. Agent Architecture Overview
4. SKILL.md Structure
5. Agent Configuration
6. Execution Flow
7. Error Recovery
8. Usage Examples
9. Scaling Considerations
10. Conclusion
```

**Example Skills**: `code-reviewer`, `multi-step-workflow`

---

### 5. MCP-Builder Skills

**Characteristics**: Integrates with MCP servers, tool definitions
**Complexity**: Complex
**Focus**: MCP integration, tool definitions, external services

**Article Structure**:
```mdx
1. Introduction
2. MCP Architecture Overview
3. Directory Structure
4. Tool Definition Analysis
5. Server Integration
6. Security Considerations
7. Usage Examples
8. Error Handling
9. Deployment Patterns
10. Conclusion
```

**Example Skills**: `mcp-builder`, `mcp-integrator`

---

## Template Selection Guide

### Select template based on:

1. **Resource Type**:
   - SKILL.md only → Template 1
   - Has scripts/ → Template 2
   - Has references/ → Template 3
   - Uses agents → Template 4
   - Uses MCP → Template 5

2. **Complexity**:
   - Simple skill (< 3 resources) → Use concise template
   - Complex skill (≥ 3 resources) → Use detailed template with more sections

3. **Target Audience**:
   - Beginners → Add more context and examples
   - Advanced users → Focus on architecture and patterns

---

## Section Depth Guidelines

### Article Length by Complexity:

| Complexity | Word Count | Sections | Examples |
|------------|-----------|----------|----------|
| Simple | 1500-2000 | 6-8 | 2-3 basic |
| Moderate | 2500-3500 | 8-10 | 3-4 practical |
| Complex | 3500-5000 | 10-12 | 4-5 comprehensive |

### Key Section Depth:

**Introduction** (always):
- What is this skill?
- What problem does it solve?
- Who is it for?

**Technical Deep Dive** (vary by complexity):
- Simple: Brief overview
- Moderate: Workflow analysis
- Complex: Architecture breakdown

**Examples** (vary by complexity):
- Simple: 1-2 command examples
- Moderate: Full workflow example
- Complex: Multiple scenarios with troubleshooting

---

## Writing Patterns

### Effective Skill Article Patterns

**Pattern 1: Problem-First Structure**
```mdx
<Callout type="question">
  "How do I consistently create high-quality Claude skills?"
</Callout>

This skill solves that by...
```

**Pattern 2: Before-After Demonstration**
```mdx
**Without this skill**:
- Manual, error-prone process
- Inconsistent results
- No validation

**With this skill**:
- Automated workflow
- Consistent quality
- Built-in validation
```

**Pattern 3: Progressive Disclosure**
```mdx
1. Start with overview (always visible)
2. Add details for those who want to know more
3. Provide complete implementation for advanced users
```

---

## Component Usage by Template

### Callout Placement:
- **Info**: After each major section heading
- **Warning**: Before common pitfalls
- **Tip**: After examples, for best practices
- **Question**: In introduction and transitions

### Cards Usage:
- Template 1: Design principles (2-3 cards)
- Template 2: Script purposes (3-4 cards)
- Template 3: Loading strategies (3-4 cards)
- Template 4: Agent patterns (4-5 cards)
- Template 5: Integration patterns (3-4 cards)

### Steps Usage:
- Template 1: 3-4 steps for basic workflow
- Template 2: 5-6 steps for execution flow
- Template 3: 4-5 steps for progressive loading
- Template 4: 6-8 steps for agent delegation
- Template 5: 5-7 steps for MCP integration

---

## Quality Checklist by Template

### All Templates:
- ✅ SourceAttribution component present
- ✅ All imports included
- ✅ Generic placeholders marked with {{}}
- ✅ Commands in code blocks with proper syntax highlighting
- ✅ Real skill URL in source attribution

### Template-Specific:
**Simple Skills**:
- ✅ Trigger examples included
- ✅ Multiple use cases shown
- ✅ Integration with at least 1 related skill

**Script-Based**:
- ✅ Each script documented
- ✅ Command-line examples work
- ✅ Error handling discussed

**Reference-Heavy**:
- ✅ Reference loading strategy explained
- ✅ Context size considerations noted
- ✅ When to load each reference documented

**Agent-Based**:
- ✅ Agent delegation pattern explained
- ✅ Concurrent vs sequential execution clarified
- ✅ Task splitting logic shown

**MCP-Builder**:
- ✅ Tool definitions examined
- ✅ Security implications discussed
- ✅ Deployment considerations included

---

## Related Resources

- **skill-article-writer/scripts/generate_article_outline.py**: Automated template selection
- **skill-article-writer/examples/**: Completed examples for each template type
- **Anthropic Skills Repository**: github.com/anthropics/skills

---

## ℹ️ Version Information

- **Created**: 2025-01-17
- **Template Version**: 1.0
- **Last Updated**: 2025-01-17

```