agent-skills-expert

name	agent-skills-expert
description	Expert for creating and managing Claude Code Agent Skills. Create skills with git submodule + sparse-checkout for source references, write SKILL.md with proper frontmatter, and follow best practices. Use when creating new skills, adding source references to skills, or managing skill configurations.

Agent Skills Expert

Expert for creating and managing Claude Code Agent Skills. Helps create skills that follow official specifications, including using Git Submodule + Sparse Checkout for source code references.

📚 Core Concepts

What is an Agent Skill?

Agent Skill is an extensible capability module for Claude Code, containing:

• SKILL.md - Skill definition file (required)
• Supporting files - Documentation, scripts, templates, etc. (optional)
• source/ - Source code reference directory (optional, using git submodule)

Skill Storage Locations

• Personal Skills: ~/.claude/skills/skill-name/
• Project Skills: .claude/skills/skill-name/

🔧 Skill Creation Workflow

1. Basic Skill Structure

skill-name/
├── SKILL.md              # Required: Skill definition
├── examples.md           # Optional: Example code
├── quick-reference.md    # Optional: Quick reference
├── SOURCE_STRUCTURE.md   # Optional: Source structure documentation
├── scripts/              # Optional: Helper scripts
└── source/               # Optional: Source code references
    └── repo-name/        # Git Submodule

2. SKILL.md Specification

---
name: skill-name                    # Required: lowercase letters, numbers, hyphens, max 64 chars
description: Brief description...   # Required: Skill description, max 1024 chars
allowed-tools: Read, Grep, Glob     # Optional: Restrict available tools
---

# Skill Name

## Instructions
Clear usage instructions...

## Examples
Concrete usage examples...

Description Best Practices:

• Explain what the skill does
• Explain when to use the skill
• Include keywords for Claude to discover

3. Adding Source References (Git Submodule + Sparse Checkout)

Step 1: Add Submodule

cd ~/.claude/skills
git submodule add https://github.com/org/repo.git skill-name/source/repo-name

Step 2: Configure Sparse Checkout

cd skill-name/source/repo-name

# Initialize sparse-checkout
git sparse-checkout init --no-cone

# Set content to keep
git sparse-checkout set \
    /README.md \
    /docs/ \
    /src/ \
    /examples/

Step 3: Create SOURCE_STRUCTURE.md

Document the source structure, including:

• Sparse checkout configuration
• Directory structure explanation
• Key file locations
• Maintenance guide

📋 Sparse Checkout Configuration Guide

Principles for Selecting Content to Keep

1. Core source code - Main API implementation
2. Documentation - README, docs directory
3. Examples - examples directory
4. Configuration files - pyproject.toml, package.json, etc.
5. Tests - Test cases showing usage patterns

Content to Exclude

• Large resource files (images, videos)
• Build artifacts
• CI/CD configuration (usually not needed)
• Historical release notes

Common Sparse Checkout Patterns

Python Projects:

git sparse-checkout set \
    /README.md \
    /LICENSE \
    /src/ \
    /docs/ \
    /examples/ \
    /tests/ \
    /pyproject.toml

JavaScript/TypeScript Projects:

git sparse-checkout set \
    /README.md \
    /LICENSE \
    /src/ \
    /docs/ \
    /examples/ \
    /package.json \
    /tsconfig.json

Rust Projects:

git sparse-checkout set \
    /README.md \
    /LICENSE \
    /src/ \
    /docs/ \
    /examples/ \
    /Cargo.toml

🛠️ Maintenance Operations

Update Submodule

cd skill-name/source/repo-name
git pull origin main

Modify Sparse Checkout Configuration

cd skill-name/source/repo-name

# Add new directory
git sparse-checkout add /new-dir/

# Reconfigure
git sparse-checkout set /dir1/ /dir2/ /file.md

View Configuration

cd skill-name/source/repo-name
git sparse-checkout list
du -sh .  # Check size

Troubleshooting Recovery

# Completely reset submodule
cd ~/.claude/skills
git submodule deinit -f skill-name/source/repo-name
rm -rf .git/modules/skill-name/source/repo-name
git submodule update --init skill-name/source/repo-name

# Reconfigure sparse-checkout
cd skill-name/source/repo-name
git sparse-checkout init --no-cone
git sparse-checkout set /directories-to-keep/

📝 Template Files

SKILL.md Template

See templates/SKILL_TEMPLATE.md

SOURCE_STRUCTURE.md Template

See templates/SOURCE_STRUCTURE_TEMPLATE.md

✅ Checklist

Creating New Skill

• Create skill directory mkdir -p ~/.claude/skills/skill-name
• Create SKILL.md (with correct frontmatter)
• Write clear description (include trigger keywords)
• Add usage instructions and examples
• Test that skill is correctly discovered

Adding Source References

• Add git submodule
• Configure sparse-checkout
• Verify reasonable size (typically <100MB)
• Create SOURCE_STRUCTURE.md
• Update source access instructions in SKILL.md
• Commit all changes

Maintenance

• Regularly update submodule
• Check if sparse-checkout configuration is still appropriate
• Update documentation to reflect latest structure

🔗 Related Resources

• GIT_SPARSE_CHECKOUT_TUTORIAL.md - Detailed Sparse Checkout tutorial
• CLAUDE_CODE_SKILL_TUTORIAL.md - Official skill tutorial
• Agent Skills Official Documentation

📊 Existing Skills Reference

Skill	Source Reference	Sparse Checkout
langgraph-python-expert	✅	✅ (~66MB)
lib-slint-expert	✅	❌
vscode-extension-builder	✅	✅
uv-expert	✅	❌
rust-cli-tui-developer	✅	❌

---

Last updated: 2024-12-23