Agent Skills Expert Skill

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

Core source code - Main API implementation
Documentation - README, docs directory
Examples - examples directory
Configuration files - pyproject.toml, package.json, etc.
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

Agent Skills: Agent Skills Expert

Skill Files