What is Skrills?

Skrills validates, analyzes, and synchronizes skills across Claude Code, Codex CLI, and GitHub Copilot CLI. It resolves compatibility issues between the three environments and provides tools to manage context usage effectively.

The Problem

Claude Code, Codex CLI, and GitHub Copilot CLI all use markdown-based “skills,” but they enforce different requirements. Claude Code has a permissive structure, while Codex CLI and Copilot CLI demand strict YAML frontmatter and impose character limits. Skills written for one tool often fail in the others.

Skrills solves this friction by validating frontmatter and schema compliance, syncing configurations and skills between all three CLIs, and analyzing token usage to prevent context overflow.

Core Features

Validate Skills

The validation engine checks compliance with Codex’s strict requirements. You can automatically fix missing frontmatter by running:

skrills validate --target codex --autofix

Analyze Token Usage

To prevent context window exhaustion, Skrills identifies heavy skills that might need optimization:

skrills analyze --min-tokens 1000 --suggestions

Sync Between Tools

Skrills mirrors your configuration between environments, verifying your tools are available everywhere:

skrills sync-all --from claude

Run as MCP Server

You can expose these capabilities directly to your AI assistant by running Skrills as an MCP server:

skrills serve

Quick Start

1. Install:

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

2. Validate:

   skrills validate
   

3. Sync:

   skrills sync-all --from claude
   

Key Concepts

Skills

Skills are SKILL.md files containing instructions and metadata. Skrills scans for these files in ~/.codex/skills, ~/.claude/skills, ~/.copilot/skills, and the universal ~/.agent/skills directory.

MCP (Model Context Protocol)

Skrills implements the Model Context Protocol, allowing assistants to invoke its tools (validation, analysis, sync) directly during a session.

Validation Targets

Validation rules depend on the target. Claude Code is permissive and accepts any markdown with optional frontmatter. Codex CLI and Copilot CLI are strict, requiring name and description fields in the YAML frontmatter.

Architecture

Skrills is a Rust workspace:

Next Steps

• Installation Guide
• Sync Guide
• MCP Token Optimization
• FAQ

Installation Guide

Quick Install (Recommended)

Most users should run this one-liner:

macOS / Linux:

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

Windows PowerShell:

powershell -ExecutionPolicy Bypass -NoLogo -NoProfile -Command "iwr https://raw.githubusercontent.com/athola/skrills/HEAD/scripts/install.ps1 -UseBasicParsing | iex"

The installer:

1. Downloads the correct binary for your system
2. Installs it to ~/.codex/bin (or detects your setup)
3. Registers skrills as an MCP server
4. Syncs your Claude skills to Codex (if both exist)

Verify Installation

skrills --version
skrills doctor        # Check configuration

Alternative: Install from crates.io

If you have Rust installed:

cargo install skrills

Alternative: Build from Source

Clone and build locally:

git clone https://github.com/athola/skrills.git
cd skrills
cargo install --path crates/cli --force

Customizing Installation

The installer accepts environment variables to customize behavior:

Examples

Install for Claude Code only:

SKRILLS_CLIENT=claude SKRILLS_BIN_DIR="$HOME/.claude/bin" \
  curl -LsSf https://raw.githubusercontent.com/athola/skrills/HEAD/scripts/install.sh | sh

Install a specific version:

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

Skip syncing Claude skills to Codex:

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

What the Installer Configures

MCP Server Registration

The installer registers Skrills as an MCP server so your AI assistant can use it directly. This configuration is stored in ~/.codex/mcp_servers.json for the Codex MCP registry and ~/.codex/config.toml for Codex configuration.

Hooks (Claude Code only)

For Claude Code, the installer creates a hook at ~/.claude/hooks/prompt.on_user_prompt_submit. This hook integrates Skrills features into the Claude Code workflow.

Skill Mirroring

By default, the installer copies your Claude skills to ~/.codex/skills/ so Codex can discover them. You can skip this step by setting SKRILLS_NO_MIRROR=1.

Troubleshooting

“Command not found” after installation

Add the bin directory to your PATH:

# For Codex (default)
export PATH="$HOME/.codex/bin:$PATH"

# For Claude
export PATH="$HOME/.claude/bin:$PATH"

Add this line to your shell profile (~/.bashrc, ~/.zshrc, etc.) to make it permanent.

MCP server not recognized

Re-run the installer or manually register:

skrills setup --client codex --reinstall

Then run skrills doctor to verify.

Wrong platform binary

If the installer picks the wrong architecture, specify it explicitly:

SKRILLS_TARGET=x86_64-unknown-linux-gnu \
  curl -LsSf https://raw.githubusercontent.com/athola/skrills/HEAD/scripts/install.sh | sh

Find your target triple with:

rustc -vV | grep host

Development Setup

For contributors, the Makefile provides common targets:

make build         # Release build
make test          # Run tests
make lint          # Run linting
make book          # Build this documentation
make book-serve    # Live preview on localhost:3000

Next Steps

• Run skrills validate to check your skills
• See CLI Usage Reference for all commands
• Check Runtime Configuration to customize behavior

CLI Reference

Commands organized by task.

Checking Your Skills

validate

Verify skills work with Claude Code, Codex CLI, or both:

skrills validate                              # Check all skills for both platforms
skrills validate --target codex               # Check Codex compatibility only
skrills validate --target codex --autofix     # Auto-fix missing frontmatter
skrills validate --format json --errors-only  # Machine-readable output

Options:

analyze

Find skills that consume too many tokens or need optimization:

skrills analyze                               # Analyze all skills
skrills analyze --min-tokens 1000             # Show only large skills
skrills analyze --suggestions                 # Get optimization tips
skrills analyze --format json                 # Machine-readable output

Options:

metrics

Get aggregate statistics about your skill collection:

skrills metrics                               # Summary statistics
skrills metrics --format json                 # Machine-readable output
skrills metrics --include-validation          # Include pass/fail counts (slower)

Options:

Output includes:

• Skill counts by source (claude, codex, marketplace)
• Quality distribution (high/medium/low based on quality scores)
• Dependency statistics (total edges, orphan count, hub skills)
• Token usage (total, average, largest skill)

Syncing Between Claude and Codex

sync-all

Sync everything between Claude Code and Codex CLI:

skrills sync-all --from claude                        # Copy everything from Claude
skrills sync-all --from claude --skip-existing-commands  # Keep local commands
skrills sync-all --dry-run                            # Preview without changing

Options:

sync-status

Preview what would change before syncing:

skrills sync-status --from claude

Individual Sync Commands

Sync specific items when you don’t want everything:

skrills sync                          # Skills only (alias: sync-from-claude)
skrills sync-commands --from claude
skrills sync-mcp-servers --from claude
skrills sync-preferences --from claude

Technical notes:

• skrills sync honors SKRILLS_MIRROR_SOURCE to change the source root
• Commands are copied byte-for-byte, preserving non-UTF-8 files without re-encoding
• Use --skip-existing-commands to preserve local command customizations

mirror

Copy Claude assets to Codex defaults and refresh the agent list:

skrills mirror                           # Full mirror
skrills mirror --skip-existing-commands  # Preserve existing commands
skrills mirror --dry-run                 # Preview changes (hashes sources, reports intended writes)

Running the MCP Server

serve

Start skrills as an MCP server (used by Claude Code and Codex CLI):

skrills serve                             # Standard startup
skrills serve --watch                     # Auto-reload on file changes (requires watch feature)
skrills serve --cache-ttl-ms 300000       # 5-minute cache
skrills serve --skill-dir ~/.custom/skills  # Custom skill directory

Options:

The MCP server exposes validation, analysis, sync, and recommendation tools directly to your AI assistant.

Working with Subagents

agent

Launch a saved agent by name:

skrills agent codex-dev                   # Run the codex-dev agent
skrills agent my-agent --dry-run          # Preview without running
skrills agent my-agent --skill-dir ~/.custom/skills  # Include custom skills

Execution mode configuration:

Subagent behavior comes from multiple sources (in priority order):

1. SKRILLS_SUBAGENTS_EXECUTION_MODE environment variable
2. execution_mode in ~/.claude/subagents.toml or ~/.codex/subagents.toml
3. Default: cli

When execution_mode=api and no backend is specified, skrills checks:

1. default_backend in the config file
2. SKRILLS_SUBAGENTS_DEFAULT_BACKEND environment variable
3. Default: codex

In cli mode, skrills uses cli_binary (or SKRILLS_CLI_BINARY), auto-detecting the current client via CLI env or server path (fallback: claude).

sync-agents

Update the available skills list for agents:

skrills sync-agents                       # Refresh AGENTS.md
skrills sync-agents --path custom.md      # Write to different file

Skill naming caveat:

Skills are named from the name: field in SKILL.md frontmatter. Treat these names as opaque strings—they may include punctuation like : for namespacing (e.g., pensive:shared).

When comparing skills between session headers and disk, don’t parse by splitting on :. Instead, extract the (file: …/SKILL.md) path or read the frontmatter directly.

Finding and Creating Skills

recommend

Discover skills related to one you use:

skrills recommend skill://skrills/codex/my-skill/SKILL.md
skrills recommend skill://skrills/codex/my-skill/SKILL.md --limit 5
skrills recommend skill://skrills/codex/my-skill/SKILL.md --format json

Returns three types of recommendations:

• Dependencies: Skills the target skill directly uses (highest priority)
• Dependents: Skills that use the target skill
• Siblings: Skills sharing common dependencies with the target

Options:

recommend-skills-smart

Get context-aware recommendations combining dependencies, usage patterns, and project context:

skrills recommend-skills-smart --project-dir .
skrills recommend-skills-smart --uri skill://skrills/codex/my-skill/SKILL.md
skrills recommend-skills-smart --prompt "deployment pipeline" --include-usage false

Options:

suggest-new-skills

Identify skill gaps in your collection:

skrills suggest-new-skills --project-dir .
skrills suggest-new-skills --focus-area testing
skrills suggest-new-skills --focus-area ci --focus-area deployment

Options:

create-skill

Generate a new skill via GitHub search, LLM generation, empirical patterns, or both:

skrills create-skill my-new-skill --description "Helps with testing"
skrills create-skill my-new-skill --description "..." --method github
skrills create-skill my-new-skill --description "..." --method empirical  # From session patterns
skrills create-skill my-new-skill --description "..." --dry-run  # Preview

Options:

The empirical method analyzes Claude Code and Codex CLI session history to extract successful tool sequences and failure anti-patterns. It clusters similar sessions and generates skills based on observed behavior.

search-skills-github

Find existing skills on GitHub:

skrills search-skills-github "testing workflow"
skrills search-skills-github "deployment" --limit 20

resolve-dependencies

Trace skill relationships:

skrills resolve-dependencies skill://skrills/codex/my-skill/SKILL.md
skrills resolve-dependencies skill://... --direction dependents
skrills resolve-dependencies skill://... --transitive false

Options:

analyze-project-context

Extract project characteristics for recommendations:

skrills analyze-project-context --project-dir .
skrills analyze-project-context --include-git true --commit-limit 100

Options:

Returns languages, frameworks, and keywords detected in your project.

Setup and Diagnostics

doctor

Check your configuration:

skrills doctor

Verifies Codex MCP configuration and identifies problems.

setup

Configure skrills for a specific client:

skrills setup --client codex              # Configure for Codex
skrills setup --client claude             # Configure for Claude
skrills setup --client both               # Configure for both
skrills setup --reinstall                 # Reconfigure from scratch
skrills setup --uninstall                 # Remove configuration
skrills setup --universal                 # Also sync to ~/.agent/skills

Options:

tui

Launch the interactive terminal interface:

skrills tui
skrills tui --skill-dir ~/.custom/skills

Provides a visual interface for sync management.

cert

Manage TLS certificates for HTTPS transport:

skrills cert status                       # Show certificate validity and expiry
skrills cert renew                        # Regenerate self-signed certificate
skrills cert install --cert my.pem --key my-key.pem  # Install custom certificate

Subcommands:

Note: Certificate management is currently CLI-only. There is no MCP tool or plugin skill for cert operations yet. Use the skrills cert subcommands directly from a terminal.

MCP Tools Reference

When running as an MCP server, skrills exposes these tools to your AI assistant:

Core Tools

Sync Tools

Intelligence Tools

Skill Tracing Tools

For debugging skill loading issues:

Subagent Tools

When subagents feature is enabled:

Note: run-subagent accepts execution_mode (cli or api) and an optional cli_binary override. When execution_mode=cli, backend is ignored.

MCP Tool Input Examples

sync-from-claude:

{}

resolve-dependencies:

{ "uri": "skill://skrills/codex/my-skill/SKILL.md", "direction": "dependencies", "transitive": true }

Smart Recommendation Workflows

Project-aware recommendations:

1. analyze-project-context → recommend-skills-smart → suggest-new-skills

GitHub-assisted skill creation:

1. search-skills-github → create-skill (use dry_run: true to preview)

Skill Loading Validation

Use trace/probe tools when you need a deterministic signal that skills are loading in the current Claude Code or Codex session.

Workflow:

1. Call enable-skill-trace (use dry_run: true to preview). This installs two debug skills and can instrument skill files by appending <!-- skrills-skill-id: ... --> markers (with optional backups).

2. Restart the session if the client does not hot-reload skills.

3. Call skill-loading-selftest and send the returned probe_line. Expect SKRILLS_PROBE_OK:<token>.

4. With tracing enabled and markers present, each assistant response should end with SKRILLS_SKILLS_LOADED: [...] and SKRILLS_SKILLS_USED: [...].

Use skill-loading-status to confirm which roots were scanned and whether markers are present. Use disable-skill-trace to remove debug skills when finished.

Common Workflows

Validate skills before committing

skrills validate --target both --errors-only

Find and optimize large skills

skrills analyze --min-tokens 2000 --suggestions

Set up a new machine

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

# Verify
skrills doctor

# Sync from your main setup
skrills sync-all --from claude

Debug skill loading

# Check status
skrills skill-loading-status

# Enable tracing
skrills enable-skill-trace

# Restart session, then validate
skrills skill-loading-selftest

CI-friendly validation

skrills validate --target codex --format json --errors-only

Frequently Asked Questions

Why does the installer URL with /main/ sometimes fail?

The installer URL using /main/ can fail if the repository’s default branch is not named main. To avoid this issue, use /HEAD/ in the raw URL:

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

How do I identify the correct release asset for my system?

To find the correct release asset, determine your system’s Rust/Cargo target triple (e.g., by running rustc -vV | grep host). Then, download the archive whose filename ends with that specific triple, for instance, skrills-x86_64-apple-darwin.tar.gz. Windows builds will have an .exe executable inside the archive.

How can I resolve the MCP startup failed: missing field "type" error in Codex?

Re-execute the installer (install.sh or install.ps1). The updated installer will automatically register skrills with type = "stdio" in both ~/.codex/mcp_servers.json and ~/.codex/config.toml.

Manual fix: Add type: "stdio" to the skrills entry in mcp_servers.json and type = "stdio" under [mcp_servers."skrills"] in config.toml. Then, restart Codex. Run skrills doctor to confirm that both files are correctly configured.

If the error persists with a third-party MCP server, consider proxying problematic servers through a schema normalizer like codex-mcp-wrapper.

How does skrills compare to other skill management tools?

skrills focuses on skill quality and portability. It checks skills for compatibility across Claude Code, Codex CLI, and GitHub Copilot CLI, analyzes token usage to identify optimization opportunities, and keeps configurations in sync between all three environments. For a detailed comparison, see the Project Comparison.

Is it possible to automatically synchronize skills between Claude, Codex, and Copilot?

Yes. Use skrills sync-all to sync everything (skills, commands, MCP servers, preferences):

# Claude → ALL other CLIs (Codex + Copilot) - no flags needed
skrills sync-all

# Claude → specific CLI only
skrills sync-all --to codex --skip-existing-commands

Add --skip-existing-commands to preserve local command files. The sync is byte-for-byte, so non-UTF-8 commands are preserved.

How do I validate skills for Codex compatibility?

Use the validate command:

skrills validate --target codex              # Check Codex compatibility
skrills validate --target codex --autofix    # Auto-add missing frontmatter

Does the MCP server expose all content from disk?

No. The MCP server only reads from configured directories, set either via --skill-dir flags or through default discovery paths. Use separate paths for trusted and untrusted skills.

What is the process for contributing new skills?

To contribute, add your new skills to your directory (~/.claude/skills/ or ~/.codex/skills/) and run skrills validate --target both to verify compatibility. For upstream contributions, follow the repository’s PR process.

Does the system work offline?

Yes. As long as you have the skrills binary and your skills stored locally, both the MCP server and CLI will function without an internet connection.

Why doesn’t Copilot have slash commands like Claude or Codex?

GitHub Copilot CLI uses a different architectural paradigm. Instead of slash commands (/command-name), Copilot has:

1. Skills (~/.copilot/skills/<name>/SKILL.md) - Reusable instruction sets that extend capabilities (same format as Codex)
2. Agents (~/.copilot/agents/*.md) - Autonomous actors with defined tools, targets, and behaviors

When syncing from Claude to Copilot:

• Skills: Sync normally (compatible formats)
• Commands: Skipped (no equivalent in Copilot)
• Agents: Sync with format transformation (Claude’s model/color → Copilot’s target: github-copilot)

If you want command-like reusable prompts in Copilot, create an agent instead:

# ~/.copilot/agents/my-prompt.agent.md
---
name: my-prompt
description: Does something useful
target: github-copilot
---

Your prompt instructions here...

What are the security considerations?

Skrills is designed with security in mind. The server communicates over standard I/O and operates with minimal file access privileges. It does not bundle any secrets, and you retain control over which skill directories are exposed. Always review third-party skills before using them.

Skill Validation

Skrills validates skills for compatibility with Claude Code, Codex CLI, and GitHub Copilot CLI. The three CLIs have different requirements for skill frontmatter, and Skrills checks that your skills work across all environments.

Validation Targets

Claude Code (Permissive)

Claude Code accepts any markdown file as a skill. Frontmatter is optional and can contain any fields.

Codex CLI (Strict)

Codex CLI discovers skills only from files named exactly SKILL.md under ~/.codex/skills/**/ (recursive, symlinks and hidden entries are skipped).

Codex CLI also requires YAML frontmatter with specific fields:

• name: Required, max 100 characters
• description: Required, max 500 characters

Skills without proper frontmatter will fail to load in Codex CLI.

GitHub Copilot CLI (Strict)

Copilot CLI follows the same validation rules as Codex CLI. Skills must be named SKILL.md and placed under ~/.copilot/skills/**/. The same YAML frontmatter requirements apply:

• name: Required, max 100 characters
• description: Required, max 500 characters

Using the Validator

Basic Validation

Validate all discovered skills against both targets:

skrills validate

Validate for a specific target:

skrills validate --target codex    # Strict Codex rules
skrills validate --target copilot  # Strict Copilot rules (same as Codex)
skrills validate --target claude   # Permissive Claude rules
skrills validate --target all      # All three targets
skrills validate --target both     # Claude and Codex (default, legacy)

Auto-Fix Missing Frontmatter

The --autofix flag automatically adds missing frontmatter by deriving values from the file path and content:

skrills validate --target codex --autofix

For safety, create backups before modifying files:

skrills validate --target codex --autofix --backup

Output Formats

Get machine-readable output for CI/CD pipelines:

skrills validate --format json

Show only skills with validation errors:

skrills validate --errors-only

Validate Specific Directories

Override the default discovery paths:

skrills validate --skill-dir ~/my-skills --skill-dir ~/other-skills

MCP Tool

When running as an MCP server (skrills serve), the validate-skills tool provides the same functionality:

{
  "name": "validate-skills",
  "arguments": {
    "target": "codex",
    "autofix": true
  }
}

Common Validation Issues

Common validation failures often stem from missing YAML frontmatter, specifically the name or description fields required by Codex. Other issues include names exceeding 100 characters or descriptions longer than 500 characters. You can resolve most of these automatically with the --autofix flag, or by manually adding the required fields.

Best Practices

Write skills with Codex/Copilot requirements in mind; if they pass strict validation, they will work everywhere. Integrate validation into your CI pipeline using skrills validate --target both --errors-only to catch issues early. When using --autofix, review the changes before committing, especially since generated descriptions might need manual refinement. Finally, run validation after syncing to verify that no incompatible changes were introduced.

Skill Analysis

Skrills analyzes skills for token usage, dependencies, and optimization opportunities.

Token Analysis

Basic Analysis

Analyze all discovered skills:

skrills analyze

Filter by Token Count

Show only skills exceeding a token threshold:

skrills analyze --min-tokens 1000

Include Optimization Suggestions

Get actionable recommendations for reducing token usage:

skrills analyze --suggestions

Output Formats

Get machine-readable output:

skrills analyze --format json

Analyze Specific Directories

Override default discovery paths:

skrills analyze --skill-dir ~/my-skills

Understanding Token Counts

Token counts provide an estimate of a skill’s impact on your context window. This helps you budget available context, identify candidates for refactoring, and compare efficient alternatives. Large skills can displace other important context, so keeping them lean is critical for performance.

Optimization Suggestions

The --suggestions flag identifies potential issues that bloat your context usage. It looks for skills exceeding 2000 tokens that might benefit from modular decomposition or removal of redundant content. It also flags verbose examples that could be simplified and suggests linking to external documentation instead of embedding large blocks of text.

MCP Tool

When running as an MCP server (skrills serve), the analyze-skills tool provides the same functionality:

{
  "name": "analyze-skills",
  "arguments": {
    "min_tokens": 1000,
    "suggestions": true
  }
}

Best Practices

Establish a budget for maximum skill token counts and review them regularly, especially after major updates. Focus your optimization efforts on frequently used skills where the savings will have the most impact. Always verify that skills still function correctly after any refactoring to reduce size.

Sync Guide

Skrills synchronizes skills, commands, MCP server configurations, and preferences between Claude Code, Codex CLI, and GitHub Copilot CLI. This enables you to maintain a single source of truth while using multiple CLIs.

Sync Direction

By default, sync-all syncs from Claude to all other CLIs (Codex and Copilot). No flags required.

# Claude → ALL other CLIs (simplest form)
skrills sync-all

# Codex → ALL other CLIs
skrills sync-all --from codex

# Claude → Codex only (specific target)
skrills sync-all --to codex

What Gets Synced

Skills

Skills are copied between skill directories:

• Claude: ~/.claude/skills/
• Codex: ~/.codex/skills/ (discovery root; skills must be **/SKILL.md)
• Copilot: ~/.copilot/skills/ (same SKILL.md format as Codex)

Codex skills are disabled by default; enable them in ~/.codex/config.toml:

[features]
skills = true

skrills sync                # Skills only
skrills sync-all            # Everything including skills

Slash Commands

Commands are synced byte-for-byte, preserving non-UTF-8 content:

• Claude: ~/.claude/commands/
• Codex: ~/.codex/prompts/
• Copilot: Does not support slash commands (skipped during sync)

skrills sync-commands --from claude --to codex
skrills sync-commands --from claude --to codex --skip-existing-commands

MCP Server Configurations

MCP server definitions are synchronized between configuration files:

• Claude/Codex: Share similar MCP configuration format
• Copilot: Uses mcp-config.json (separate from main config)

skrills sync-mcp-servers --from claude --to codex
skrills sync-mcp-servers --from claude --to copilot

User Preferences

Preferences and settings are synchronized:

• Copilot: Uses config.json with security field preservation

skrills sync-preferences --from claude --to codex
skrills sync-preferences --from claude --to copilot

Sync-All Command

The most common workflow is to sync everything at once:

# Sync from Claude to all other CLIs (no flags needed)
skrills sync-all

# Sync to a specific target only
skrills sync-all --to codex --skip-existing-commands

Options:

• --from: Source CLI (default: claude)
• --to: Target CLI (default: all other CLIs)
• --dry-run: Preview changes without writing
• --skip-existing-commands: Preserve local commands (Claude/Codex only)
• --validate: Run validation after sync
• --autofix: Auto-fix validation issues

Preview Changes

Before syncing, preview what will change:

skrills sync-status --from claude

This shows:

• Files that would be added
• Files that would be updated
• Configuration differences

Mirror Command

The mirror command syncs files and updates AGENTS.md:

skrills mirror --skip-existing-commands

Use --dry-run to preview:

skrills mirror --dry-run

MCP Tools

When running as an MCP server, these sync tools are available:

Environment Variables

• SKRILLS_MIRROR_SOURCE: Override mirror source root (default ~/.claude)

Best Practices

Always preview changes with a dry run before syncing to avoid unexpected overwrites. Sync regularly to keep configurations aligned and prevent drift. After syncing, run skrills validate to catch any compatibility issues immediately. To protect your local customizations, use the --skip-existing-commands flag. Finally, choose a primary CLI environment and consistently sync from it to maintain a clear source of truth.

Configuration

Customize skrills behavior through environment variables and configuration files.

Quick Reference

Environment Variables

Discovery Settings

SKRILLS_CACHE_TTL_MS

How long skrills caches discovered skills before re-scanning directories.

• Default: 60000 (60 seconds)
• Use higher values if your skills rarely change
• Use lower values during development

# Cache for 5 minutes (stable skill set)
export SKRILLS_CACHE_TTL_MS=300000

# Cache for 10 seconds (active development)
export SKRILLS_CACHE_TTL_MS=10000

SKRILLS_CACHE_PATH

Where to store the discovery cache file.

• Default: ~/.codex/skills-cache.json
• Useful for isolating test environments

# Use separate cache for testing
export SKRILLS_CACHE_PATH=/tmp/test-skills-cache.json

Sync Settings

SKRILLS_MIRROR_SOURCE

Which directory to copy skills from during sync operations.

• Default: ~/.claude
• Change this to sync from a different Claude installation

# Sync from a custom Claude setup
export SKRILLS_MIRROR_SOURCE=/path/to/other/claude
skrills sync-all

SKRILLS_NO_MIRROR

Skip automatic skill syncing during installation.

• Default: disabled
• Set to 1 to skip

# Install without syncing Claude skills
SKRILLS_NO_MIRROR=1 ./scripts/install.sh

Client Settings

SKRILLS_CLIENT

Force skrills to target a specific client instead of auto-detecting.

• Default: auto-detected from ~/.claude or ~/.codex presence
• Values: claude or codex

# Always target Claude
export SKRILLS_CLIENT=claude

Subagent Settings

SKRILLS_SUBAGENTS_EXECUTION_MODE

How subagents run: as CLI commands or through the API.

• Default: cli
• Values: cli or api

SKRILLS_SUBAGENTS_DEFAULT_BACKEND

Which backend to use for API-mode subagents.

• Default: codex
• Values: codex or claude

SKRILLS_CLI_BINARY

Which CLI binary to use for subagent execution.

• Default: auto (detects current client)
• Values: claude, codex, or auto

Configuration Files

Skills Manifest

Location: ~/.codex/skills-manifest.json

Controls skill discovery priority and caching:

{
  "priority": ["codex", "mirror", "claude", "agent"],
  "expose_agents": true,
  "cache_ttl_ms": 60000
}

Subagents Configuration

Location: ~/.claude/subagents.toml or ~/.codex/subagents.toml

execution_mode = "cli"
cli_binary = "auto"
default_backend = "codex"

The auto setting for cli_binary picks the right CLI based on:

1. SKRILLS_CLIENT environment variable
2. CLI environment indicators (CLAUDE/CODEX)
3. Server binary path
4. Fallback to claude

Practical Recipes

Speed up discovery for stable skills

If your skills rarely change, increase the cache time:

export SKRILLS_CACHE_TTL_MS=300000  # 5 minutes

Isolate test environments

Use separate caches when running tests in parallel:

export SKRILLS_CACHE_PATH=/tmp/test-$$.json
skrills validate --target codex

Sync from a different Claude installation

Point to a custom source directory:

export SKRILLS_MIRROR_SOURCE=/path/to/team/claude
skrills sync-all

Force a specific target client

Override auto-detection:

export SKRILLS_CLIENT=claude
skrills setup

Common Commands

skrills --version     # Check version
skrills --help        # List commands
skrills doctor        # Diagnose configuration

Understanding Skrills Data

Skrills stores minimal data on disk. This chapter explains what gets saved, where to find it, and how to reset things when needed.

What Skrills Saves

Your Skills

Skrills discovers skills from these directories:

When you run skrills sync or skrills mirror, skrills copies skills between these directories so both tools can access them.

Note: Codex skills require an experimental feature flag in ~/.codex/config.toml:

[features]
skills = true

Discovery Cache

To avoid scanning directories repeatedly, skrills caches skill metadata:

Location: ~/.codex/skills-cache.json

The cache refreshes automatically when:

• The time-to-live (TTL) expires (default: 60 seconds)
• You use the --watch flag with skrills serve

Manifest

The manifest controls which directories skrills searches and in what order:

Location: ~/.codex/skills-manifest.json

{
  "priority": ["codex", "mirror", "claude", "agent"],
  "expose_agents": true,
  "cache_ttl_ms": 60000
}

Analytics Cache

Usage analytics are stored when you run analytics-building commands with persistence enabled:

Location: ~/.skrills/analytics_cache.json

Enable automatic persistence with:

• --auto-persist flag on recommend-skills-smart
• SKRILLS_AUTO_PERSIST=1 environment variable

Manual persistence:

skrills export-analytics --output analytics.json
skrills import-analytics analytics.json

Subagent Configuration

Settings for launching subagents:

Location: ~/.claude/subagents.toml or ~/.codex/subagents.toml

execution_mode = "cli"
cli_binary = "auto"
default_backend = "codex"

What Skrills Does NOT Save

Skrills keeps these things temporary:

• Validation results — Run skrills validate each time
• Analysis results — Run skrills analyze each time
• User prompts — Never written to disk

Checking What’s Stored

See discovered skills

skrills validate --format json

Preview sync changes

skrills sync-status --from claude

Verify configuration

skrills doctor

Resetting Things

Clear synced skills

Remove skills that were copied from another tool:

rm -rf ~/.codex/skills/

Clear the cache

Force skrills to re-scan all directories:

rm ~/.codex/skills-cache.json

Full reset

Remove all skrills state and start fresh:

rm -rf ~/.codex/skills/
rm -rf ~/.codex/skills-mirror/
rm ~/.codex/skills-cache.json
rm ~/.codex/skills-manifest.json
rm ~/.codex/subagents.toml
rm ~/.claude/subagents.toml
rm ~/.skrills/analytics_cache.json

After a full reset, run skrills setup to reconfigure.

Legacy Files

Older versions of skrills used ~/.codex/skills-mirror/ to store a complete copy of Claude assets. Current versions sync directly to ~/.codex/skills/ instead. You can safely delete the mirror directory:

rm -rf ~/.codex/skills-mirror/

MCP Token Optimization

Overview

The Skrills MCP server minimizes token usage by returning targeted summaries rather than full skill metadata payloads.

MCP Tools Token Impact

When the subagents feature is enabled:

Best Practices

Prefer CLI for Batch Operations

For operations involving many skills, the CLI is more efficient than repeated MCP tool calls. A single CLI command like skrills validate --format json can replace hundreds of individual tool invocations.

Filter Output

Use filtering options to reduce payload size. For example, skrills validate --errors-only returns only the skills that failed validation, and skrills analyze --min-tokens 2000 limits the output to only the largest skills.

Preview Before Sync

Use skrills sync-status --from claude to preview changes before running a full sync. This shows the scope of changes without the overhead of a full write operation.

Efficient Workflows

Validation Workflow

# 1. Preview validation (errors only)
skrills validate --errors-only

# 2. Fix issues with autofix
skrills validate --target codex --autofix --backup

# 3. Verify fixes
skrills validate --target codex --errors-only

Sync Workflow

# 1. Preview changes
skrills sync-status --from claude

# 2. Sync if changes look correct
skrills sync-all --from claude --skip-existing-commands

See Also

• CLI Usage Reference
• Skill Validation
• Sync Guide

Security Considerations

This chapter summarizes security guidance from docs/security.md and docs/threat-model.md into an actionable playbook. It explains assets to protect, common attack methods, and critical configurations for a secure skrills deployment.

Assets Protected

• High-Value Data: Includes sensitive information like user prompts, configuration files, and skill content.
• Availability Assets: Core components vital for service continuity, including the MCP server process, the cache system, and filesystem skill roots.

Threat Model

Key Attackers:

• Malicious Skills: Untrusted SKRILL.md content used to inject harmful instructions into prompts.
• Supply-Chain Compromises: Vulnerabilities in compromised dependencies.
• Local Attackers: Users with filesystem access who try to tamper with skill files or configuration.

Primary Mitigations:

• Path canonicalization and skill-root allowlists to prevent directory traversal attacks.
• Strict size guards (e.g., --max-bytes) to limit the impact of malicious content.
• Future skill signing and allowlisting to reduce the skill injection attack surface.

Production Checklist

1. Operate as an unprivileged service account; configure strict file permissions (chmod 600) for sensitive configuration files.
2. Enable audit logging (once available) and review logs regularly.
3. Restrict skill sources: Only load skills from trusted directories.
4. Monitor skill content: Review skill files for suspicious content before use.

Secrets Management

• Store secrets securely in environment variables or integrate with a dedicated secrets manager; never commit them to version control.
• Apply chmod 600 permissions to configuration files containing sensitive data.
• Plan for regular credential rotations where applicable.

Deployment Patterns

• Stdio/Local Mode: Relies on process isolation and filesystem permissions. Store secrets in environment files, not directly within manifests.
• Claude Code Integration: The hook-based integration inherits Claude Code’s security model. Verify Claude Code itself is properly configured.

Future Security Enhancements

• Tamper-Evident Audit Logs: Tamper-evident audit log channel for skill loading events.
• Skill Signing/Allowlisting: Skill signing and allowlisting to harden the supply chain for SKILL.md content.

Observability and Audit Logging

skrills provides structured logging via the tracing crate for debugging and visibility.

Logging Overview

• Validation Events: Logs skill validation, autofix operations, and compatibility checks.
• Analysis Events: Logs token counting, dependency analysis, and optimization suggestions.
• Sync Operations: Logs skill mirroring, command sync, and configuration changes.
• Cache Operations: Cache hits, misses, and invalidation help diagnose performance and freshness issues.
• MCP Protocol Events: Tool invocations and responses are logged to debug integration issues.

Log Configuration

Set the RUST_LOG environment variable to control log verbosity:

# Enable debug logging for skrills
RUST_LOG=skrills=debug skrills serve

# Enable trace logging for detailed diagnostics
RUST_LOG=skrills=trace skrills serve

# Enable wire-level MCP tracing
skrills serve --trace-wire

Audit Logging

Key events to monitor include:

• Skill discovery and validation outcomes
• Sync operations and their results
• Cache invalidation events
• MCP tool invocations and their results

Best Practices

• Use structured logging with consistent field names for easier log aggregation
• Monitor validation errors to identify skill compatibility issues
• Track sync operations to detect configuration drift

Log Triage

• Index logs by skill_name, validation_target, and error for efficient searching
• Correlate Claude Code session events with skrills logs using timestamps

Performance Baseline and Tuning

The skrills MCP server has minimal overhead. Validation, analysis, and sync operations are designed to be efficient.

Expected Performance

The initial skill directory scan is cached to avoid repeated filesystem access. Validation processes skills in parallel where possible, and analysis uses approximate but fast token counting. Sync operations use content hashing to skip unchanged files and perform efficient byte-for-byte copies.

These figures are from measurements on an M1 Pro system with a typical skill set.

Tuning Recommendations

Cache TTL

Configure SKRILLS_CACHE_TTL_MS or cache_ttl_ms in the manifest to balance freshness with performance:

# Longer TTL for stable skill sets
export SKRILLS_CACHE_TTL_MS=300000  # 5 minutes

Validation Performance

Use filtering options to reduce work:

# Only check for errors
skrills validate --errors-only

# Target specific directory
skrills validate --skill-dir ~/my-skills

Analysis Performance

Filter to focus on relevant skills:

# Only analyze large skills
skrills analyze --min-tokens 1000

When to Investigate

Investigate performance if validation feels slow, which often indicates skill directories containing many files. If sync is slow, use sync-status to identify large change sets. Slow startup times might require increasing the cache TTL or reducing the number of monitored skill directories.

Testing and Coverage

Integration tests, located under crates/server/tests/, cover the MCP server functionality, skill discovery, validation, analysis, and sync operations.

Covered Areas

• MCP Server Flow: Tests cover skill loading, request handling, and response formatting.
• Validation: Tests verify skill validation for Claude Code and Codex CLI compatibility.
• Analysis: Tests cover token counting and dependency analysis.
• Sync Operations: Tests validate cross-agent sync functionality between Claude and Codex.
• Subagent Integration: Tests cover subagent service integration and backend communication.

Shared test utilities are available in the test modules for managing temporary directories, constructing test configurations, and handling test data.

CI Pipeline Notes

The integration-tests.yml workflow in our CI pipeline runs the test suite with path-based filtering, parallel job execution, cached builds, scheduled daily runs, and Codecov reporting.

Adding New Coverage

• Prioritize reusing existing test helpers for consistency.
• Include test cases for negative scenarios (e.g., invalid frontmatter, missing fields) as well as happy paths.
• Use tempfile::tempdir() for filesystem isolation in tests.

Development Guide

This guide provides development information for contributors.

Toolchain

• Rust: Install Rust 1.78+, preferably with rustup.
• Formatting and Linting: Use cargo fmt for formatting and clippy for linting to maintain code quality.
• Documentation: This project uses mdbook for documentation. Install it with cargo install mdbook --locked.

Make Targets

The project’s Makefile provides targets for development workflows:

# Code quality checks
make fmt
make lint
make check

# Testing
make test

# Building
make build
make build-min

# Documentation
make docs         # Builds the rustdoc API documentation
make book         # Compiles and automatically opens the mdBook
make book-serve   # Serves the mdBook at localhost:3000 with live-reloading

# Cleaning up
make clean

Demo Sandbox

The make demo-all target creates a sandboxed environment for CLI testing. It builds a release binary, sets up a temporary home directory with a demo skill, and runs commands to validate end-to-end behavior without affecting your actual home directory.

Testing

To run all tests, use:

cargo test --workspace --all-features

This command is aliased by make test and is part of the Continuous Integration (CI) pipeline, managed by make ci.

Public API Guardrails

The skrills-server crate is currently in its pre-1.0 development phase. Refer to the SemVer guidance in Public API and SemVer Policy and perform local public API checks before submitting changes. This verifies compliance with the API evolution policy.

Coverage

• Local Coverage: For local analysis, generate an HTML report with cargo llvm-cov --workspace --html, or an LCOV report for CI export with cargo llvm-cov --workspace --lcov --output-path lcov.info.
• CI Coverage: The coverage.yml workflow within our CI/CD pipeline runs the same coverage command and uploads the results to Codecov.

Public API and SemVer Policy

This project is currently in its 0.x release series. During this phase of rapid iteration, API evolution follows the principles in Rust RFC 1105.

• Documented Public API: The officially documented public API surface primarily includes the run entrypoint and the validation/analysis modules. All other components are internal and may change without notice.
• Best-Effort Compatibility: While we try to avoid introducing breaking changes to the documented public API, the interface is still evolving. New fields may be added, or existing behaviors adjusted, as the API stabilizes. All such breaking changes, should they occur, will be documented in docs/CHANGELOG.md.
• Feature Gates: The watch feature, which provides filesystem watching, is optional. It can be disabled for minimal builds to reduce binary size. The subagents feature enables multi-agent coordination capabilities.
• Tooling Guardrails: Our Continuous Integration (CI) pipeline includes a public-API check to detect accidental changes to the API surface. Contributors should run this check locally before submitting pull requests; refer to CONTRIBUTING.md for detailed instructions.

Until 1.0 is released, we strongly recommend pinning dependencies to an exact minor release. Always review the changelog for migration notes about releases that might affect the public API.

Development Process and Workflow Guidelines

This document outlines development processes and safety considerations to maintain a stable and reliable runtime environment.

Child Process Management

Effective child process management is critical to prevent system instability, like resource leaks or unexpected process termination.

• On Unix-like systems, a SIGCHLD handler configured with SA_NOCLDWAIT | SA_RESTART is installed during startup. This prevents “zombie” processes.
• When spawning new child processes, you must manage their exit status without directly using waitpid, or temporarily override and restore the SIGCHLD handler.
• Non-Unix builds currently use a no-operation (no-op) stub. If platform-specific child process spawning capabilities are introduced, equivalent safeguards must be implemented.

Workflow Best Practices

Follow these practices to maintain code quality and development standards:

• Centralize Shared Logic: All shared functionality and core logic must be in the crates/core module. The crates/cli crate should be a thin wrapper, focusing on command-line interface concerns.
• Changelog Updates: Ensure the changelog is updated for all user-visible changes, including new CLI flags, changes to output formats, AGENTS sync behavior, and priority rule adjustments.
• Pre-Publishing Checks: Before publishing, run cargo fmt to ensure code formatting and cargo test to confirm test integrity.

Development Checklist

Before finalizing and merging changes, consider the following checklist:

• Verify that no new zombie or unmanaged child processes are introduced.
• Confirm a changelog entry exists for all user-facing changes.
• Ensure all tests pass and code formatting adheres to standards.
• Confirm all new CLI flags are documented in both README.md and the project book.

Playbooks and Demo Scripts

These scripted walkthroughs are for team training and validating new builds.

Validation Workflow

Validate skills for cross-CLI compatibility:

# 1. Install skrills
./scripts/install.sh --client both

# 2. Validate all skills
skrills validate --target both

# 3. Fix Codex compatibility issues
skrills validate --target codex --autofix --backup

# 4. Verify fixes
skrills validate --target both --errors-only

Sync Workflow

Sync configurations from Claude to Codex:

# 1. Preview changes
skrills sync-status --from claude

# 2. Sync everything
skrills sync-all --from claude --skip-existing-commands

# 3. Validate synced skills
skrills validate --target codex

Analysis Workflow

Identify skills that need optimization:

# 1. Find large skills
skrills analyze --min-tokens 1000

# 2. Get optimization suggestions
skrills analyze --min-tokens 2000 --suggestions

# 3. Export for review
skrills analyze --format json > skills-analysis.json

Claude Code Integration

# Install with Claude hook support
./scripts/install.sh --client claude

# Verify installation
skrills doctor

# Sync skills from Claude to Codex
skrills sync-all --from claude

Codex Integration

# Install with Codex MCP support
./scripts/install.sh --client codex

# Verify MCP configuration
skrills doctor

# Validate skills for Codex
skrills validate --target codex

TUI Workflow

Interactive sync and management:

# Launch TUI
skrills tui

# Navigate with arrow keys
# Select items with Space
# Confirm with Enter

CI/CD Integration

Add to your CI pipeline:

# Fail on validation errors
skrills validate --target both --errors-only --format json

# Check for large skills
skrills analyze --min-tokens 3000 --format json

Project Comparison

This table compares skrills against alternative approaches for managing and deploying skills across Claude Code and Codex CLI.

Core Differentiators

Validation Engine

Skrills validates skills against two targets with distinct requirements. Claude Code is permissive, accepting any markdown with optional frontmatter. Codex CLI is strict, requiring YAML frontmatter with name and description fields. The --autofix flag automatically derives and adds missing frontmatter from the file path and content.

Token Analysis

Skrills analyzes skills to estimate token usage and track dependencies. It provides optimization suggestions for large skills, helping to maintain an efficient context window.

Bidirectional Sync

Skrills supports full bidirectional sync for skills, commands, MCP servers, and preferences. It uses byte-for-byte command sync to preserve non-UTF-8 content and includes a --skip-existing-commands flag to protect local customizations from being overwritten.

Planned Improvements

Future work includes signed artifacts and version pinning for synced skills to improve security and reproducibility. Additional goals include improved Windows path detection, default configurations, and skill dependency resolution to manage complex skill sets.

Summary

Skrills is a skills support engine focused on quality and portability. It validates skills for cross-CLI compatibility, analyzes token usage, and synchronizes configurations bidirectionally. The MCP server enables integration with both Claude Code and Codex CLI environments.

Release Artifacts and Distribution

This document provides an overview of the release and distribution process for the skrills project.

Build Targets

skrills is built to support the following target architectures:

• x86_64-unknown-linux-gnu
• aarch64-unknown-linux-gnu
• x86_64-apple-darwin
• aarch64-apple-darwin
• x86_64-pc-windows-msvc
• aarch64-pc-windows-msvc

Asset Naming Convention

Release assets follow the naming convention skrills-<target>.tar.gz. The executable binary is at the root of the archive and is named skrills (or skrills.exe for Windows builds).

Installers

The provided curl (for macOS/Linux) and PowerShell (for Windows) installation scripts automatically select the correct release asset by querying the GitHub API. These installers also register the MCP server by adding type = "stdio" to both ~/.codex/mcp_servers.json and ~/.codex/config.toml. The default GitHub repository is athola/skrills, but this can be overridden by setting the SKRILLS_GH_REPO environment variable.

Continuous Integration (CI)

GitHub Actions are configured to build and upload release assets when v* tags are pushed. At the same time, the mdBook documentation is automatically deployed to GitHub Pages in the CI pipeline.

crates.io Publishing

• Crates are published to crates.io in a defined dependency order: skrills-state, skrills-discovery, skrills-server, and skrills.
• Releases require the CARGO_REGISTRY_TOKEN to be configured in repository secrets. The release workflow validates this token and runs cargo publish --dry-run for all crates before actual publication.
• Pull requests that modify Cargo or workflow files automatically trigger a dry-run publish job. This helps catch potential publishing failures early.

Documentation

• Rust Documentation: Run make docs to generate and view the cargo doc documentation.
• Project Book: Run make book to build and open the mdBook documentation. For live reloading during development, use make book-serve.

Build Features

• The watch feature, which provides filesystem watching, is enabled by default.
• For minimal builds, run cargo build with the --no-default-features flag or use make build-min.

Maintainer notes regarding artifact layout can be found in docs/release-artifacts.md.

Recent Releases

• 0.3.2 (2025-12-15): Added dependency resolution system, enhanced analysis capabilities, and performance optimizations.
• 0.3.1 (2025-12-13): Added validation and analysis crates with comprehensive skill quality assurance.
• 0.3.0 (2025-12-04): Refactored for Claude Code hook-based integration. Improved MCP server stability, skill discovery, and documentation.
• 0.2.1 (2025-11-28): Added crates.io publishing automation with dependency validation.
• 0.2.0 (2025-11-26): Implemented crates.io publishing automation (with token validation and dry-runs), introduced deterministic embedding test overrides, and updated installation documentation.
• 0.1.14 (2025-11-25): Added doctor diagnostics, --trace-wire logging, schema hardening (for type = "object"), and updated installers to write type = "stdio" to both Codex configuration files (with a --local build flag).
• 0.1.13 (2025-11-25): The installer filters release archives more rigorously and uses source builds as a secondary option. CI jobs trigger based on relevant path changes.
• 0.1.12 (2025-11-25): Improved installer asset lookup robustness.
• 0.1.11 (2025-11-25): The release workflow now skips asset uploads if a release with the same tag already exists.
• 0.1.10 (2025-11-25): The GitHub release is created before asset uploads to prevent race conditions.
• 0.1.9 (2025-11-25): Corrected release upload include patterns for proper handling of platform archives.
• 0.1.8 (2025-11-25): Manifest flag respected for hiding agent documentation. Audit workflow cached, release include paths corrected.
• 0.1.7 (2025-11-25): Introduced release dry-run builds and implemented cache reuse in the CI pipeline.
• 0.1.6 (2025-11-24): Switched to supported archive options in the release packaging process.
• 0.1.5 (2025-11-24): ZIP flag set in Windows upload step for correct artifact generation.
• 0.1.4 (2025-11-24): Fixed CI upload inputs and stabilized environment-driven tests.

Changelog Highlights

0.5.6 (2026-01-28)

• Testing: Added BDD-style unit tests for skill management modules (deprecation, pre-commit, profiling, rollback, usage-report) covering serialization, parsing, and validation logic.

0.5.5 (2026-01-26)

• NEW: TLS Certificate Management: Added skrills cert subcommand with status, renew, and install operations. Certificate validity is shown on server startup.
• Refactor: Copilot Adapter: Split monolithic copilot.rs into focused modules (agents, commands, mcp, paths, preferences, skills, utils, tests) for improved maintainability.
• Testing: Added unit tests for certificate parsing including missing file handling, valid PEM parsing, and invalid PEM detection.

0.5.4 (2026-01-25)

• Testing: Added BDD-style tests for configuration loading and directory validation
• Documentation: Updated README command count to 37 and added skill management section

0.5.3 (2026-01-23)

• Docs: Streamlined README with navigation links and simplified installation section.
• NEW: Config File Support: Added --config flag and skrills.toml config file for persistent server settings.
• NEW: TLS Auto-Generation: Generate self-signed TLS certificates with --tls-generate for development HTTPS.

0.5.2 (2026-01-22)

• NEW: HTTP Transport for MCP Servers: Added support for HTTP-type MCP servers (like context7) which use type="http" with url and headers fields instead of command/args/env.
• Dependency Cleanup: Removed unused dependencies (pastey, sha2, flate2) from crates/server, regex from crates/intelligence, anyhow from crates/analyze, thiserror from crates/sync and crates/subagents.
• Dead Code Removal: Removed unused methods from SkillCache and unused imports from metrics and test modules.
• Bug Fix: Filter whitespace-only descriptions at extraction point (not just empty strings).
• Improved: Skill discovery summary log changed from debug to info level for better observability.
• Testing: Added 5 new tests for multi-word description matching (first/middle/last word, special characters, long descriptions).

0.5.1 (2026-01-21)

• Refactor: Skill Trace Commands: Split monolithic /skill-trace into three focused commands:
  • /skill-trace-enable - Enable tracing with instrumentation
  • /skill-trace-disable - Disable tracing and cleanup
  • /skill-trace-status - Check current tracing state
• Refactor: Test Utils Crate: Extracted shared test infrastructure into crates/test-utils/.
• Code Quality: Sorted command registrations alphabetically in plugin.json.
• Docs: Cleaned up docs/audit-logging.md.

0.5.0 (2026-01-20)

• NEW: GitHub Copilot CLI Support: Full bidirectional sync for ~/.copilot (skills, MCP servers, preferences).
• NEW: Agent Sync: Sync Claude Code subagents to Copilot with format transformation (removes model/color, adds target: github-copilot).
• NEW: CLI Flags: Added --from copilot and --to copilot for sync commands.
• NEW: MCP Tools: sync-from-copilot, sync-to-copilot, all 6 source→target skill sync combinations.
• NEW: Validation Target: --target copilot for skill validation.
• Testing: 20 Copilot sync integration tests.

0.4.12 (2026-01-16)

• Testing: Added 59 new tests across tool_schemas (20), sync report (20), and validation common (19) modules.

0.4.11 (2026-01-15)

• Refactor: Improved test infrastructure with RAII guards (EnvVarGuard, TestFixture).
• Bug Fix: Logging for silent failure path in skill validation; saturating_mul for timestamp overflow.
• Docs: Consolidated 14 documentation files from bulleted lists to flowing prose.

0.4.10 (2026-01-15)

• NEW: Confidence Type: Type-safe Confidence newtype with clamping (0.0-1.0) for recommendations.
• Improved: Observability: Added tracing for behavioral and comparative recommendation modules.
• NEW: Auto-Persist: --auto-persist flag and SKRILLS_AUTO_PERSIST env var for automatic analytics caching.

0.4.9 (2026-01-12)

• NEW: MCP Gateway: Context-optimized tool loading via lazy schema loading.
• NEW: Analytics Persistence: Export/import analytics via export-analytics and import-analytics.
• NEW: HTTP Security Options: Added --auth-token, --tls-cert, --tls-key, --cors-origins flags.

0.4.8 (2026-01-10)

• NEW: Skill Description Caching: Optional description field in SkillMeta for richer fuzzy search.
• Improved: Fuzzy Search: Matches against descriptions in addition to names.

0.4.7 (2026-01-09)

• Version bump to republish after v0.4.6 tag protection issue.

0.4.6 (2026-01-08)

• Bug Fixes: Address 14 issues including warnings for skipped deps, YAML line/column info, SAFETY comments.
• Testing: Add 282 new tests across multiple modules.
• Documentation: Add audit-logging.md covering security events and SIEM integration.

0.4.5 (2026-01-03)

• Testing: Added tests for tool handler functions.

0.4.4 (2026-01-02)

• NEW: Empirical Skill Creation: Generate skills from session patterns via --method empirical. Mines Claude Code/Codex CLI history for successful tool sequences and failure anti-patterns.
• NEW: Comparative Recommendations: Deviation scoring compares actual vs expected outcomes per skill category (Testing, Debugging, Documentation, etc.).
• NEW: Behavioral Analytics: Extract tool calls, file access patterns, and session outcomes from history.
• Improved: Install Script: User-scoped MCP registration (--scope user) with better error capture.

0.4.3 (2025-12-31)

• NEW: HTTP Transport: --http flag for HTTP transport instead of stdio.
• Runtime Configuration: HTTP flag is runtime-checked, not compile-time gated.
• Default: HTTP transport enabled by default in release builds.

0.4.2 (2025-12-29)

• NEW: Fuzzy Skill Search: Added search-skills-fuzzy MCP tool with trigram-based similarity matching for typo-tolerant skill discovery.
• Example: Query “databas” will find skills named “database” with high similarity scores.
• Parameters: query (search term), threshold (similarity cutoff, default 0.3), limit (max results).

0.4.1 (2025-12-27)

• Hashing: Switched file hash algorithm to blake2b-256 for improved performance and security.
• CI/CD: Improved error handling in publish verification workflow.
• Documentation: Added README for the intelligence crate.

0.4.0 (2025-12-24)

• NEW: Intelligent Skills: Added skrills-intelligence crate with project context analysis, skill recommendations, and skill creation.
• NEW: Project Context Detection: Automatically detect languages, frameworks, and project type from README and git history.
• NEW: Smart Recommendations: Context-aware skill recommendations based on project profile and usage analytics.
• NEW: Skill Creation: Create new skills via GitHub search or LLM generation with project context.
• NEW: Usage Analytics: Parse Claude Code and Codex CLI history for skill usage patterns.
• Security: Path traversal guard, GitHub query injection sanitization, CLI binary name validation.

0.3.5 (2025-12-21)

• NEW: Agent Discovery: Added list-agents MCP tool for discovering available agents with metadata caching.
• NEW: Run Events Polling: Added get-run-events MCP tool for polling-based event retrieval.
• NEW: Codex CLI Adapter: Subprocess execution of Codex CLI agents via CodexCliAdapter.
• NEW: Smart Routing: Automatic backend selection based on agent_id parameter.
• NEW: Model Mapping: Cross-platform model preference sync for consistent agent configuration.
• Error Handling: Structured CliError enum with better error messages; logging for silent failures.
• Testing: Comprehensive integration tests for subagent workflow.

0.3.4 (2025-12-19)

• NEW: Skill Recommendations: Added skrills recommend CLI command and recommend-skills MCP tool for suggesting related skills based on dependency graph relationships (dependencies, dependents, and siblings).
• Options: --limit for max recommendations, --include-quality for quality scores, --format for text/json output.

0.3.3 (2025-12-18)

• NEW: Metrics Command: Added skrills metrics CLI command and skill-metrics MCP tool for aggregate statistics including quality distribution, dependency graphs, and token usage.
• NEW: Makefile Targets: Added make status, make install, make test-coverage, make security, and make deps-update for developer workflows.
• Dependency Graph: Metrics include hub skill detection and orphan count from the dependency analysis.

0.3.2 (2025-12-17)

• NEW: Dependency Resolution: Skill dependency tracking via YAML frontmatter with semver constraints, circular dependency detection, and source pinning.
• NEW: Skill Loading Trace: Diagnostic tools for debugging skill loading (skill-loading-status, skill-loading-selftest, trace enable/disable).
• Dependency Syntax: Simple, structured, and compact syntax forms for declaring dependencies.
• Optional Dependencies: Configurable behavior for optional dependencies.
• Extended Validation: Dependency-related validation issues in the validate crate.
• BREAKING: rmcp updated to 0.10 (removed deprecated info() method).
• BREAKING: SkillSource enum now requires wildcard pattern matching.

0.3.1 (2025-12-13)

• NEW: Validation Crate (skrills-validate): Validate skills for Claude Code (permissive) and Codex CLI (strict frontmatter requirements). Includes auto-fix capability to add missing frontmatter.
• NEW: Analysis Crate (skrills-analyze): Token counting, dependency analysis, and optimization suggestions for skills.
• NEW: CLI Commands: Added skrills validate and skrills analyze commands for skill quality assurance.
• NEW: MCP Tools: Added validate-skills and analyze-skills tools to the MCP server.
• Architecture Pivot: Removed redundant skill-serving functionality now that Claude Code and Codex CLI have native skill support. Skrills now focuses on validation, analysis, and sync.
• Comprehensive Tests: Added 53 tests for bidirectional skill sync.
• REMOVED: Autoload functionality (autoload.rs, emit.rs).
• REMOVED: CLI commands: list, list-pinned, pin, unpin, auto-pin, history, emit-autoload, render-preview.
• REMOVED: MCP tools: list-skills, autoload-snippet, render-preview, runtime-status, set-runtime-options, pin-skills, unpin-skills, refresh-cache.

0.3.0 (2025-12-12)

• NEW: Subagents Module: Comprehensive subagent functionality with MCP server support via list-subagents, run-subagent, and get-run-status tools.
• NEW: Backend Support: Dual backend support for both Claude-style and Codex-style subagent execution.
• NEW: Sync Infrastructure: Cross-agent sync orchestration with SyncOrchestrator and adapters for Claude/Codex.
• Documentation: Added AGENTS.md with subagent usage examples.
• BREAKING: Removed the gateway crate and related functionality. Replaced with simpler MCP server integration.
• Security Fix: Updated rmcp from 0.9.1 to 0.10.0, replacing unmaintained paste with pastey.

0.2.2 (2025-12-04)

• Focus on Claude Code: Simplified integration to focus on Claude Code hook-based skill injection.
• Installer Improvements: Added --client claude flag and SKRILLS_CLIENT environment variable.
• Aligned workspace crates to version 0.3.0.

0.2.1 (2025-11-26)

• Publishing: Cargo publishing workflow with dependency validation and dry-run checks.
• Release: Automated crate publishing to crates.io.
• Testing: Improved test isolation in server module.
• Documentation: Updated formatting and clarity.

0.2.0 (2025-11-26)

• Refactoring: Reorganized from monolithic to modular architecture.
• Renaming: Project renamed from “codex-mcp-skills” to “skrills”.
• Modular Architecture: New workspace with discovery, state, and server crates.
• CI/CD: Added code coverage workflow and public API change checks.
• Documentation: Added Mermaid diagrams for architecture visualization.

0.1.x Releases

See full changelog for details on earlier releases including:

• 0.1.14: Doctor diagnostics, --trace-wire logging
• 0.1.13: Installer archive filtering improvements
• 0.1.12-0.1.0: Initial releases with installer, mdBook, and CI/CD setup