ClaudeSkills Engine

A Python implementation of the Claude Agent Skills system — a sophisticated prompt-based meta-tool architecture that extends LLM capabilities through specialized instruction injection.

🎯 Overview

ClaudeSkills Engine is a complete Python implementation of the Claude Agent Skills system, enabling LLMs to discover, load, and execute specialized skills through a meta-tool architecture. Skills are self-contained instruction sets that extend agent capabilities with domain-specific knowledge and workflows.

Key Features

• 🔍 Progressive Skill Discovery: Load minimal metadata first, full prompts on demand
• 🛡️ Permission Scoping: Fine-grained tool permissions per skill with path restrictions
• 📦 Multi-Source Loading: Support for built-in, project, and user skill directories
• 🔄 Context Injection: Separate conversation and execution contexts with dynamic modification
• 🎨 Pattern Support: Built-in implementations of common skill patterns
• 🔧 Extensible Architecture: Easy to add new tools, patterns, and skill types
• 📝 Portable Paths: Use {baseDir} placeholders for skill portability

🚀 Quick Start

Installation

Using uv (recommended):

uv pip install -e .

Or using pip:

pip install -e .

For development with testing and linting tools:

uv pip install -e ".[dev]"

Basic Usage

from engine import ClaudeSkillsEngine

# Initialize engine
engine = ClaudeSkillsEngine(builtin_skills_dir="skills")

# List available skills
skills = engine.list_skills()
for skill in skills:
    print(f"{skill.name}: {skill.description}")

# Execute a skill
result = engine.execute_skill("script-automation", args="analyze /path/to/directory")
if result.success:
    for message in result.messages:
        print(message.content)

Command Line Interface

# List all available skills
python examples/demo.py list

# Show detailed information about a skill
python examples/demo.py show script-automation

# Execute a skill
python examples/demo.py execute script-automation --args "analyze /path/to/directory"

# View the Skill tool's dynamic prompt
python examples/demo.py prompt

# Validate a skill's structure
python examples/demo.py validate script-automation

📚 What Are Skills?

Skills are self-contained instruction sets that extend an LLM's capabilities. Each skill consists of:

• Metadata (frontmatter): Name, description, tool permissions, version, etc.
• Instructions: Detailed prompt content that guides the agent's behavior
• Resources: Supporting files, scripts, or reference materials

Skills use a meta-tool pattern: the Skill tool dynamically generates prompts listing available skills, and when invoked, injects the full skill instructions into the conversation context.

🏗️ Architecture

Core Components

engine/
├── engine.py          # Main engine orchestrator
├── skill.py           # Skill class and YAML frontmatter parser
├── skill_loader.py    # Multi-directory skill discovery
├── skill_tool.py      # Meta-tool implementation
├── context.py         # Execution context management
├── tools/             # Core tool implementations
│   ├── read.py        # File reading
│   ├── write.py       # File writing
│   ├── bash.py        # Shell command execution
│   ├── grep.py        # Pattern searching
│   ├── glob.py        # File pattern matching
│   ├── git.py         # Git operations
│   └── browser.py     # Browser automation
└── patterns/          # Reusable skill patterns
    ├── script_automation.py
    ├── read_process_write.py
    ├── search_analyze_report.py
    └── command_chain.py

Skill Discovery

Skills are loaded from three directories (in priority order):

1. User Skills: ~/.config/claude/skills/ (highest priority)
2. Project Skills: .claude/skills/ (project-specific)
3. Built-in Skills: skills/ (default examples)

Permission System

Skills can restrict tool usage through the allowed-tools frontmatter field:

allowed-tools: "Read, Write, Bash(python {baseDir}/scripts/*:*)"

This enables:

• Tool whitelisting: Only specified tools are available
• Path restrictions: Limit Bash/command execution to specific paths
• Security: Prevent unauthorized file access or command execution

📖 Example Skills

The repository includes several example skills demonstrating different patterns:

1. Script Automation

Location: skills/script-automation/

Executes Python/Bash scripts for complex operations that require deterministic logic or multi-step processing.

Pattern: Script Automation

Use Case: Data processing, file transformations, complex calculations

2. Read-Process-Write

Location: skills/read-process-write/

Demonstrates file transformation workflows: read input, process content, write output.

Pattern: Read-Process-Write

Use Case: Format conversions, data transformations, batch processing

3. Search-Analyze-Report

Location: skills/search-analyze-report/

Performs codebase analysis, pattern detection, and generates reports.

Pattern: Search-Analyze-Report

Use Case: Code reviews, architecture analysis, documentation generation

4. Command Chain

Location: skills/command-chain/

Executes multi-step command sequences with dependencies and error handling.

Pattern: Command Chain Execution

Use Case: Build pipelines, deployment workflows, sequential operations

5. PDF Processor

Location: skills/pdf-processor/

Complete working example using the Script Automation pattern to extract and process PDF content.

Use Case: Document processing, content extraction, batch operations

6. API Scaffolder

Location: skills/api-scaffolder/

Generates API scaffolding code based on specifications.

Use Case: Rapid prototyping, code generation, boilerplate creation

7. Code Reviewer

Location: skills/code-reviewer/

Analyzes code for issues, suggests improvements, and generates review reports.

Use Case: Code quality checks, best practices enforcement, automated reviews

🛠️ Creating Your Own Skills

Skill Structure

Create a directory for your skill and add a SKILL.md file:

---
name: my-skill
description: A brief description of what this skill does
when-to-use: When you need to do X, Y, or Z
allowed-tools: "Read, Write"
version: 1.0.0
license: MIT
---

# My Skill

## Overview

Detailed explanation of the skill's purpose and capabilities.

## Instructions

Step-by-step instructions for the agent to follow when using this skill.

### Step 1: Identify Requirements

Analyze the user's request to determine...

### Step 2: Execute Actions

Use the available tools to...

## Examples

Example use cases and expected outcomes.

Frontmatter Fields

• name (required): Unique skill identifier
• description (required): Brief description for skill discovery
• when-to-use (optional): Guidance on when to use this skill
• allowed-tools (optional): Comma-separated list of allowed tools with optional path restrictions
• version (optional): Skill version number
• license (optional): License information
• model (optional): Specific model requirement
• disable-model-invocation (optional): Disable direct model calls
• mode (optional): Enable mode command support

Path Placeholders

Use {baseDir} in paths to make skills portable:

allowed-tools: "Bash(python {baseDir}/scripts/*:*)"

The {baseDir} placeholder is automatically replaced with the skill's directory path at runtime.

Skill Locations

Place your skill in one of:

• Built-in: skills/your-skill/ (for repository skills)
• Project: .claude/skills/your-skill/ (project-specific)
• User: ~/.config/claude/skills/your-skill/ (personal skills)

🎨 Patterns

The engine includes implementations of common skill patterns:

Script Automation

Offload complex operations to Python/Bash scripts stored in the skill directory.

Implementation: engine/patterns/script_automation.py

Read-Process-Write

Transform files through a read → process → write pipeline.

Implementation: engine/patterns/read_process_write.py

Search-Analyze-Report

Search codebase, analyze patterns, generate reports.

Implementation: engine/patterns/search_analyze_report.py

Command Chain

Execute sequential commands with dependencies and error handling.

Implementation: engine/patterns/command_chain.py

🔧 Tools

Core tools available to skills:

Tool	Description	Permission Syntax
Read	Read file contents	Read
Write	Write content to files	Write
Bash	Execute shell commands	Bash or Bash(path:pattern)
Grep	Search patterns in files	Grep
Glob	File pattern matching	Glob
Git	Git operations	Git
Browser	Browser automation	Browser

Tool Permission Examples

# Allow all tools
allowed-tools: "Read, Write, Bash, Grep, Glob"

# Restrict Bash to specific scripts
allowed-tools: "Read, Write, Bash(python {baseDir}/scripts/*:*)"

# Multiple path restrictions
allowed-tools: "Bash(python {baseDir}/scripts/*:*), Bash(bash {baseDir}/tools/*:*)"

🧪 Testing

Run the test suite:

pytest

Or with uv:

uv run pytest

Run specific test files:

pytest tests/test_skill.py
pytest tests/test_patterns.py

📖 Documentation

• Claude Agent Skills Deep Dive: Comprehensive architecture documentation
• Anthropic Skills Announcement: Official introduction
• Equipping Agents for the Real World: Technical deep dive

🤝 Contributing

Contributions are welcome! When adding new skills:

1. Create a skill directory in skills/
2. Add a SKILL.md file with proper frontmatter
3. Include example scripts or resources as needed
4. Test your skill using python examples/demo.py validate <skill-name>
5. Update this README if adding a new pattern or significant feature

📄 License

See individual skill licenses in their respective directories. The engine codebase follows the project's main license.

🙏 Acknowledgments

• Inspired by Anthropic's Claude Agent Skills system
• Built as a reference implementation and learning resource
• Designed for extensibility and educational purposes

Note: This is a Python reference implementation of the Claude Skills system. For production use with Claude, refer to Anthropic's official documentation and tooling.