Skrills

Skills support engine for Claude Code, Codex CLI, and GitHub Copilot CLI.

Installation | User Guide | CLI Reference | MCP Tutorial | FAQ | Changelog

Features

Skrills validates skills against Claude Code (permissive), Codex CLI (strict), and Copilot CLI (strict) rules. It syncs skills, commands, agents, MCP servers, and preferences across all three environments, preventing configuration drift. The validation engine derives missing YAML frontmatter from file paths and content to fix common errors automatically.

For optimization, Skrills analyzes token usage per skill and suggests reductions to fit context windows. It resolves skill dependencies with cycle detection and semantic versioning constraints. The built-in MCP server provides over 40 tools for validation, sync, and project-aware skill generation, while session mining improves recommendations based on actual usage.

Demo

See the quickstart tutorial for a detailed walkthrough, or the MCP tutorial for server setup.

Installation

macOS / Linux:

curl -LsSf https://raw.githubusercontent.com/athola/skrills/HEAD/scripts/install.sh | sh

Windows PowerShell:

powershell -ExecutionPolicy Bypass -NoLogo -NoProfile -Command ^
"Remove-Item alias:curl -ErrorAction SilentlyContinue; iwr https://raw.githubusercontent.com/athola/skrills/HEAD/scripts/install.ps1 -UseBasicParsing | iex"

crates.io: cargo install skrills

See installation guide for HTTP transport setup, systemd services, and advanced options.

Quickstart

# Validate skills for Codex/Copilot compatibility
skrills validate --target all --autofix

# Analyze token usage
skrills analyze --min-tokens 1000 --suggestions

# Sync from Claude to all other CLIs
skrills sync-all

# Start MCP server
skrills serve

# Interactive mode
skrills tui

See CLI reference for all 39 commands including skill lifecycle management.

Skill Management

Beyond validation and analysis, Skrills provides tools for managing skill lifecycles:

# Deprecate a skill with migration guidance
skrills skill-deprecate old-skill --replacement "new-skill" --message "Replaced by more efficient version"

# Rollback a skill to a previous version
skrills skill-rollback my-skill --version abc123

# Import skills from external sources
skrills skill-import https://example.com/skill.md
skrills skill-import ~/local/skills/

# Generate usage reports
skrills skill-usage-report --format json > report.json

# Calculate quality scores
skrills skill-score

# Browse and search available skills
skrills skill-catalog --filter "python"

# View skill performance metrics
skrills skill-profile my-skill

Why Skrills

Claude Code, Codex CLI, and Copilot CLI have different requirements for skill definitions. Codex and Copilot require YAML frontmatter with specific character limits (name max 100, description max 500), while Claude is permissive. Skrills catches these discrepancies at validation time, preventing runtime errors.

The sync system uses file hashing to respect manual edits, ensuring user changes aren't overwritten. Token analytics and dependency resolution help maintain a clean, efficient skill library within context limits.

Limitations

• No runtime skill injection: Skrills validates and syncs files; it does not inject skills into prompts at runtime
• Copilot command sync: Copilot CLI does not support slash commands, so command sync is skipped
• Empirical mining: Session history parsing works best with recent Claude Code / Codex CLI versions
• LLM generation: Requires ANTHROPIC_API_KEY or OPENAI_API_KEY for skill creation

Architecture

Crate	Purpose
server	MCP server, CLI, HTTP transport, security middleware
validate	Validation logic for Claude/Codex/Copilot compatibility
analyze	Token counting, dependency analysis, optimization
intelligence	Recommendations, project analysis, skill generation
sync	Multi-directional sync with adapters for each CLI
discovery	Skill discovery and ranking
state	Environment config, manifest settings, runtime overrides
subagents	Shared subagent runtime and backends
test-utils	Shared test infrastructure (fixtures, RAII guards, temp dirs)

See architecture docs for details.

Configuration

Create ~/.skrills/config.toml for persistent settings:

[serve]
auth_token = "your-secret-token"
tls_auto = true
cors_origins = "https://app.example.com"

Precedence: CLI flags > environment variables > config file.

See security docs for TLS setup and FAQ for environment variables.

TLS Certificate Management

For secure HTTPS transport, Skrills includes certificate management:

# Check certificate status
skrills cert status

# Auto-generate self-signed certificates for development
skrills serve --tls-auto

# Renew expiring certificates
skrills cert renew

# Install custom certificates
skrills cert install /path/to/cert.pem --key /path/to/key.pem

Documentation

Resource	Description
User Guide	Primary documentation (mdBook)
CLI Reference	All commands with examples
MCP Tutorial	Server setup and tool reference
Sync Guide	Cross-CLI sync workflows
Token Optimization	Context window management
FAQ	Common questions
Security	Auth, TLS, threat model
Changelog	Release history

Development

make lint test --quiet

Requires Rust 1.75+. See development guide for test coverage, CI, and contribution workflow.

Contributing

• Security issues: See security policy and threat model
• Bug reports: Include OS, skrills --version, and logs (--trace-wire for MCP)
• Pull requests: Follow process guidelines; update docs/tests with code

License

MIT