What is Skrills?

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

The Problem

Claude Code, Codex CLI, GitHub Copilot CLI, and Cursor all use markdown-based “skills,” but they enforce different requirements. Claude Code has a permissive structure, Codex CLI and Copilot CLI demand strict YAML frontmatter, and Cursor uses .mdc rule files with mode-specific fields like globs and alwaysApply. 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 four 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-from-claude    # Claude as source of truth
skrills sync-from-cursor    # Cursor as source of truth
skrills sync                # Bidirectional sync

Run as MCP Server

You can expose these capabilities directly to your AI assistant by running Skrills as an MCP server, or launch the browser dashboard:

skrills serve                               # MCP server over stdio
skrills serve --http 127.0.0.1:3000 --open  # Browser dashboard with REST API

HTML Portal

Skrills can generate a self-contained HTML portal on demand via the html-portal-generator skill. The generated skrills-portal.html provides an interactive browser-based interface for exploring skills, validating content, analyzing tokens, converting between CLI formats, and browsing the full MCP tool and CLI command reference. The portal works offline on file:// protocol and can be uploaded into AI application portals. The file is git-ignored, so regenerate it per release rather than committing snapshots.

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-from-claude
   

Key Concepts

Skills

Skills are SKILL.md files containing instructions and metadata. By default Skrills scans ~/.codex/skills, ~/.claude/skills, ~/.copilot/skills, ~/.cursor/skills, the Claude Code plugin directories, and the shared ~/.agents/skills directory that Codex, Cursor and Copilot CLI load. Cursor rules under ~/.cursor/rules/ are not scanned by default.

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. Cursor uses .mdc rule files where the description field is required and mode is derived from globs or alwaysApply fields.

Architecture

Skrills is a Rust workspace of 14 crates. The cli crate builds the skrills binary; server holds the MCP server and the engine the subcommands call. The architecture overview lists every crate and its purpose.

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 ~/.skrills/bin (override with SKRILLS_BIN_DIR)
3. Runs skrills setup --yes --client <client> to register skrills as an MCP server, once for each client whose config directory (~/.claude, ~/.codex, ~/.copilot, ~/.cursor) exists, or for Claude Code when none does
4. With SKRILLS_UNIVERSAL=1, also syncs your Claude skills into ~/.agents/skills

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:

Set the variables on the sh side of the pipe; a variable placed before curl reaches only curl.

Examples

Install for Claude Code only:

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

Install a specific version:

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

Install the binary only, without running setup:

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

What the Installer Configures

MCP Server Registration

The installer runs skrills setup, which registers Skrills as an MCP server so your AI assistant can use it directly:

• Codex: a [mcp_servers.skrills] table in ~/.codex/config.toml. Setup does not write ~/.codex/mcp_servers.json; skrills doctor checks config.toml and inspects a legacy mcp_servers.json only if one exists.
• Claude Code: claude mcp add --scope user, which records the server in ~/.claude.json. If the claude command is missing or fails, setup writes ~/.claude/.mcp.json instead.
• Copilot: mcp_servers.json in COPILOT_HOME when set, else in an existing $XDG_CONFIG_HOME/copilot (or ~/.config/copilot on Linux), else in ~/.copilot.
• Cursor: ~/.cursor/mcp.json.

Set SKRILLS_NO_HOOK=1 to skip this step.

Hooks

Setup installs no hooks. skrills setup --uninstall --client claude removes the ~/.claude/hooks/prompt.on_user_prompt_submit hook that older releases created.

Skill Mirroring

The installer does not copy skills between clients. Set SKRILLS_UNIVERSAL=1 to have setup also sync your Claude skill directories into ~/.agents/skills. Use skrills sync-all to sync skills, commands and settings between clients.

Troubleshooting

“Command not found” after installation

Add the bin directory to your PATH:

export PATH="$HOME/.skrills/bin:$PATH"

Use the directory you set in SKRILLS_BIN_DIR if you changed it.

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:

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

validate exits non-zero when any skill has an error, cannot be read, or could not be auto-fixed, so a script or CI step can gate on the exit code. --watch is not implemented yet and is refused.

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
skrills sync-all --from claude --validate             # Refuse to sync skills that do not validate
skrills sync-all --from claude --autofix --dry-run    # Check what autofix would leave, write nothing

Options:

With --validate or --autofix, the --from skill tree is validated for the strictest of the targets being synced (Codex and Copilot are stricter than Claude and Cursor) before the first target is touched. Any remaining error aborts every target, with nothing written. --autofix rewrites the source skills in place, without a backup, before validating; under --dry-run it only checks what the fix would leave and rewrites nothing.

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 in ~/.codex/AGENTS.md:

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, Codex CLI, Copilot CLI, and Cursor):

skrills serve                             # MCP server over stdio
skrills serve --http 127.0.0.1:3000 --open      # Browser dashboard with auto-launch
skrills serve --http 127.0.0.1:8080             # HTTP on a specific address and port
skrills serve --http 127.0.0.1:3000 --tls-auto  # HTTPS with auto-generated cert
skrills serve --watch                     # Auto-reload on file changes
skrills serve --cache-ttl-ms 300000       # 5-minute cache
skrills serve --skill-dir ~/.custom/skills  # Custom skill directory

Options:

With --auth-token, the dashboard page and its static files load without the token, but every API call needs it. Open the dashboard as http://127.0.0.1:3000/#token=<TOKEN> (the fragment never leaves the browser), or enter the token when the page prompts after its first rejected request.

The MCP transport validates the inbound Host header and accepts only localhost, 127.0.0.1 and ::1 unless told otherwise. That is what stops a page on an attacker’s domain from resolving to your loopback address and driving the server through your browser. Binding a non-loopback address needs the hostname clients actually use:

skrills serve --http 0.0.0.0:8080 --allowed-hosts skrills.internal:8080

Supplied hosts are added to the loopback set, never substituted for it. The same list is settable in the config file as allowed_hosts under [serve], or through SKRILLS_ALLOWED_HOSTS.

recommend-skills-smart, analyze-project-context and suggest-new-skills take a project_dir from the client and read that directory, and create-skill reads one when passed. To limit which directories they may read, list the allowed roots in ~/.skrills/config.toml:

[serve]
project_roots = ["~/src", "/work"]

A project_dir outside every root is refused with an invalid_params error naming the setting. Both sides are canonicalized before the check, so .. segments and symlinks are judged by where they lead, and a project_dir that does not exist is refused too. ~ expands to your home directory. When project_roots is unset, any directory is accepted, and serve --http on a non-loopback address logs a warning at startup. The check applies only to a project_dir the client passes; when it passes none, the tools use the server’s working directory.

The MCP server exposes 36 core tools (48 with the default subagent and gateway features) for validation, analysis, sync, intelligence, and research directly to your AI assistant. The HTTP mode serves a browser dashboard with skills explorer, metrics, and activity feed.

Skrills can generate a self-contained HTML portal (skrills-portal.html) via the html-portal-generator skill. It works offline without a running server and includes a skills browser, validator with autofix, token analyzer, cross-CLI converter, and full CLI/MCP reference. Open it directly in any browser or upload it into AI application portals. The file is git-ignored, so regenerate it as part of release prep.

Working with Subagents

agent

Run a discovered agent by name with Codex:

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

The agent runs as codex exec --sandbox workspace-write "<prompt>": it can write only inside the current directory, and Codex refuses to start outside a git repository or trusted directory. Agent files can come from third-party plugin caches, so the sandbox stays on unless you pass --dangerously-bypass-sandbox, which runs Codex with --dangerously-bypass-approvals-and-sandbox (no sandbox, no approvals). Use it only for agent files you trust, in an environment that is sandboxed already.

Execution mode configuration (run-subagent MCP tool):

The settings below apply to subagents run through the MCP server, not to skrills agent. 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, when the run names no backend, skrills picks the binary in this order:

1. cli_binary (or SKRILLS_CLI_BINARY) when it names a binary rather than auto
2. The configured default backend (SKRILLS_SUBAGENTS_DEFAULT_BACKEND or default_backend): codex or claude
3. The current client, detected from SKRILLS_CLIENT or the CLI environment, then the server binary path
4. Default: claude

multi-cli-agent

Launch an agent through Claude Code or Codex, falling back to the other when the first choice is not installed:

skrills multi-cli-agent my-agent                    # Auto-detect the backend
skrills multi-cli-agent my-agent --backend codex    # Prefer Codex
skrills multi-cli-agent my-agent --dry-run          # Print the resolved command only

Codex runs with the same sandboxed command as skrills agent; Claude runs as claude --print "<prompt>". On timeout the command kills the CLI it started (not processes that CLI spawned) and exits with an error naming the limit.

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.

search-skills

Fuzzy-search installed skills by name, and optionally by description:

skrills search-skills commit
skrills search-skills review --include-description --threshold 0.2 --limit 5

Managing Skill Lifecycle

These commands share --format text|json and, where they read skills, --skill-dir <DIR> to limit them to one directory.

skill-diff

Compare one skill across Claude, Codex, Copilot, and Cursor:

skrills skill-diff commit
skrills skill-diff commit --format json -C 5

-C, --context <N> sets the context lines around each difference (default: 3).

skill-catalog

Browse every available skill:

skrills skill-catalog --search git --source codex --limit 20

Filters: --search <TEXT>, --source claude|codex|copilot|cursor, --category <TAG>, and --limit <N> (default: 50).

skill-import

Import a skill from a URL, git repository, or local path:

skrills skill-import https://github.com/org/skills.git --target codex --dry-run
skrills skill-import ./my-skill --force

--target is claude, codex, copilot, or cursor (default: claude). --force overwrites an existing skill; --dry-run writes nothing.

sync-pull

Pull skill updates from a remote source:

skrills sync-pull --source https://github.com/org/skills.git --skill commit --dry-run

--source is a git repository, HTTP endpoint, or registry; --skill limits the pull to one skill; --target takes the same values as skill-import (default: claude).

skill-deprecate

Mark a skill as deprecated:

skrills skill-deprecate old-skill --message "Merged into new-skill" --replacement new-skill

skill-rollback

Revert a skill to an earlier version:

skrills skill-rollback commit                  # List available versions
skrills skill-rollback commit --version abc123 # Roll back to that version hash

skill-score

Score skills on validation, completeness, and metrics:

skrills skill-score                            # Score every discovered skill
skrills skill-score commit
skrills skill-score --below-threshold 60       # Only skills scoring under 60

skill-profile

Show execution statistics for one skill, or overall when no name is given:

skrills skill-profile commit --period 7

--period <DAYS> sets the window (default: 30).

skill-usage-report

Generate a usage report:

skrills skill-usage-report --period 7 --format json --output usage.json

--format is text or json; --output writes to a file instead of stdout; --period <DAYS> defaults to 30.

pre-commit-validate

Validate skill files from a git pre-commit hook:

skrills pre-commit-validate --staged
skrills pre-commit-validate --target codex --skill-dir skills/

--staged checks only staged files. --target is claude, codex, copilot, all, or both (default: all).

Usage Analytics

export-analytics

Write usage analytics to a file:

skrills export-analytics                         # ~/.skrills/analytics_cache.json
skrills export-analytics --output backup.json --force-rebuild

--force-rebuild rebuilds from session data even when a cache exists.

import-analytics

Load analytics from an earlier export:

skrills import-analytics backup.json --overwrite

--overwrite replaces an existing cache file.

Setup and Diagnostics

doctor

Check your configuration:

skrills doctor

Verifies the Codex MCP registration in ~/.codex/config.toml, where skrills setup writes it, and identifies problems. A legacy ~/.codex/mcp_servers.json is inspected only when present.

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 Claude and Codex
skrills setup --client all                # Configure every supported client
skrills setup --reinstall                 # Reconfigure from scratch
skrills setup --uninstall                 # Remove configuration
skrills setup --universal                 # Also sync to ~/.agents/skills

Options:

tui

Launch the interactive terminal interface:

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

Provides a visual interface for sync management.

dashboard

Real-time terminal dashboard for skill monitoring. Requires a TTY:

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

cold-window

Run the cold-window real-time analysis surface, as a TUI, a browser dashboard, or both:

skrills cold-window --tui
skrills cold-window --browser --port 8888
skrills cold-window --browser --demo        # Built-in demo data

Options include --alert-budget <N> (default 100000, minimum 3), --research-rate <N>, --tick-rate-ms <MILLIS>, --no-adaptive, --no-bell, --skill-dir <DIR>, and --plugins-dir <DIR>. See Cold-Window Real-Time Analysis for the full reference.

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 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

These are MCP tools, not CLI subcommands. Ask the assistant to call them from a Claude Code or Codex session connected to skrills serve:

1. Call skill-loading-status to check which roots were scanned.
2. Call enable-skill-trace to install the trace and probe skills.
3. Restart the session, then call 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?

Codex reads the registration from ~/.codex/config.toml. skrills setup (which the installer runs) writes type = "stdio" when it adds the [mcp_servers.skrills] table, but leaves an existing table unchanged, so re-running the installer does not repair an old entry.

Manual fix: Add type = "stdio" under [mcp_servers.skrills] in ~/.codex/config.toml, then restart Codex. Run skrills doctor to confirm. It checks config.toml, and also checks a legacy ~/.codex/mcp_servers.json only if one exists; setup no longer writes that file.

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, GitHub Copilot CLI, and Cursor, analyzes token usage to identify optimization opportunities, and keeps configurations in sync between all four environments. For a detailed comparison, see the Project Comparison.

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

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

# Claude → ALL other CLIs (Codex, Copilot, and Cursor) - 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 ~/.agents/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?

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 loads user skills from files named exactly SKILL.md under ~/.agents/skills/<name>/. Skills synced by older skrills versions sit under ~/.codex/skills/.

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.

Cold-Window Real-Time Analysis

The cold-window is a continuously-refreshing analysis surface for your skrills ecosystem. It re-reads authoritative state from disk on every tick (no warm cache shortcuts), runs a four-tier alert policy with hysteresis and min-dwell over the snapshot, ranks hints with a recency-weighted scorer, and surfaces external research findings on a pull-only basis.

Two render targets, both consuming the same WindowSnapshot artifact:

• TUI: ratatui-based panes in skrills-dashboard::cold_window (alert pane, hint pane, research pane, status bar), mounted in a crossterm raw-mode loop. Run with --tui (v0.8.2).
• Browser: HTML page and Server-Sent Events stream in skrills-server::api::cold_window. Run with --browser (v0.8.0).

Both consume the same bus, so they can run together.

Quick start

Run the TUI in your terminal against your own skills:

skrills cold-window --tui --skill-dir ~/.claude/skills

By default the engine shows only real data: token attribution for the skills under --skill-dir (and SKRILLS_SKILL_DIR), and plugin health from ./plugins/*/health.toml. The default skill roots are not walked, so with neither set the token ledger stays empty. To see every pane populated, add --demo, which feeds invented token growth, hints and research findings that step through each alert tier:

skrills cold-window --tui --demo

Quit with q or Ctrl-C. Press ? for contextual help. Prefer a browser? Run the SSE surface instead (or alongside):

skrills cold-window --browser --port 8888

Open http://localhost:8888/dashboard in any modern browser. Either surface renders four panes:

• Status bar: tick cadence with adaptive label (tick: 2.0s [base], tick: 4.0s [load 0.78], tick: 1.0s [active edit]), token-budget progress with a colored bar (green → cyan → yellow → red), per-tier alert counts, optional research-quota remaining.
• Alerts: 4-tier list (Warning / Caution / Advisory / Status) sorted tier-then-recency, with per-tier coloring. Alerts carry a hysteresis band so re-arming requires re-crossing the matching *_clear value.
• Hints: ranked by MultiSignalScorer formula (frequency × IMPACT_WEIGHT + impact × ACTIONABILITY_WEIGHT) / (ease + 1) × exp(-ln 2 × age_days / HALF_LIFE_DAYS), so a hint one half-life (14 days) old keeps half its score. Pinned hints sort to the top regardless of score.
• Research: pull-only side panel. Findings from GitHub, Hacker News, Lobsters, papers, and TRIZ analogies arrive asynchronously through the tome dispatcher. Empty by default. The dispatcher respects a token-bucket quota.

The TUI arranges those panes to fit the terminal, re-flowing live on resize:

• Wide (≥ 80 columns): alerts over hints in a 60% left column, research filling the 40% right column.
• Medium (60-79 columns): the same two-column layout with a slimmer research column so the alert and hint text keep their width.
• Narrow (45-59 columns, e.g. a split pane): every pane stacks full-width top to bottom. A collapsed research pane shrinks to a fixed three-line badge so alerts and hints keep the room.
• Compact (< 45 columns, e.g. a phone SSH session): only the focused pane renders, and Tab switches which pane is visible. Hiding panes beats squeezing them into unreadable slivers.

Below a hard floor of 20x6 the panes give way to a one-line “terminal too small” guard. The status bar stays pinned to the bottom row in every tier, with the contextual key hints for the focused pane right-aligned on it. z zooms the focused pane to the full body at any tier: the escape hatch when one pane needs all the room.

Always-on in Zellij

Dedicate a Zellij pane to the TUI that respawns if it exits. Save as ~/.config/zellij/layouts/skrills.kdl and launch with zellij --layout skrills:

layout {
    tab name="cold-window" focus=true {
        pane command="bash" {
            // Loop respawns the TUI after a crash or reboot.
            args "-c" "until skrills cold-window --tui --skill-dir ~/.claude/skills; do echo restarting...; sleep 2; done"
        }
    }
}

Already inside a Zellij session? Open it in a split without a layout file: zellij run -d down -- bash -c 'until skrills cold-window --tui --skill-dir ~/.claude/skills; do sleep 2; done'.

Keybindings

The default surface is deliberately minimal: every data-rich or configuration view opens as a modal overlay (drill-down details, keybinding help), so depth never costs permanent screen space. The bottom hint line shows only the keys valid for the focused pane, and ? opens the full reference scoped to it.

Esc backs out one level at a time: it closes the topmost overlay, then clears zoom, then clears the hint filter. With none of those open it quits, the same rule the skill dashboard follows. (0.8.2 made Esc never quit; 0.9.1 restores quitting at the bare base surface so both TUIs agree.) Ctrl-C always quits; q quits after closing any open overlay. Every action is reachable without CTRL/ALT modifiers, so the TUI stays usable from phone keyboards over SSH.

Ctrl-C exits cleanly within the 2-second shutdown budget. The browser sees a status event with reconnecting… while the server drains.

Design model and research basis

The TUI follows the “lazygit/gitui model”: a small fixed set of panes as the default surface, every data-rich or configurable view behind a modal overlay or drill-down, a one-line contextual hint bar for discoverability, and width-conditional layout collapse instead of a separate mobile build. gitui’s in-tree popup stack and atuin’s select-to-reveal inspector are the direct implementation references.

Three principles shape the restraint:

• Details on demand. Shneiderman’s mantra (overview first, zoom and filter, then details) and dashboard surveys that name information overload as the dominant failure mode argue for a bounded default with depth behind interaction, not more panes.
• Density without decoration. Terminal users self-select for speed, so meaning is carried by text and semantic color (it survives a color-stripped buffer), with no animation or fade. The surface repaints on state change, and ratatui’s buffer diffing makes the idle repaint floor a zero-write no-op rather than screen-reader spam.
• Single-key reachability. On phones over SSH the keyboard layer, not width, is the real constraint, so every action is reachable without CTRL/ALT modifiers and the : palette bridges novice and expert use.

The design decisions and the alternatives weighed against them are recorded as TR-001 through TR-006 in docs/tradeoffs.md.

CLI flags

Architecture

A single producer (ColdWindowEngine in skrills-analyze::cold_window) emits one Arc<WindowSnapshot> per tick on a bounded tokio::sync::broadcast channel. Both render targets subscribe to the same bus. Drift between them is structurally impossible because the artifact is the contract.

┌────────────────────────────────────────────────────────┐
│  ColdWindowEngine (skrills-analyze::cold_window)       │
│   tick(input) → Arc<WindowSnapshot>                    │
│                                                        │
│   ↳ FieldwiseDiff       (snapshot diff)                │
│   ↳ LayeredAlertPolicy  (4-tier and hysteresis)        │
│   ↳ DefaultHintScorer   (intelligence::MultiSignal)    │
│   ↳ LoadAwareCadence    (load-ratio backoff)           │
└────────────────────┬───────────────────────────────────┘
                     │
        ┌────────────▼─────────────┐
        │  SnapshotBus              │
        │  broadcast<Arc<Snap>>     │
        └────────────┬─────────────┘
   ┌─────────────────┼─────────────────┐
   ▼                 ▼                 ▼
TUI panes        SSE handler     Tome worker
(dashboard)      (server)        (quota-gated)

Resource bounds (R11 mitigation): the broadcast channel caps at 16 queued snapshots. Lagging subscribers drop and the SSE handler emits a status banner (“subscriber lagged by N ticks”) rather than blocking the producer. The activity ring caps at 100 entries with oldest-evict.

Token thresholds

Defaults are research-backed:

• 20K total tokens → Advisory (Anthropic API quadratic-cost inflection per the Feb 2026 HN Expensively Quadratic analysis).
• 50K total tokens → Caution (Willison’s Too many Model Context Protocol servers range).
• 80% of --alert-budget → Warning.
• 100% of --alert-budget → Warning and kill-switch engaged. While it is engaged, cold-window keeps its pid in ~/.skrills/kill-switch.pid, and every sync that writes (sync-all, mirror, the MCP sync tools), in any process, refuses. The file is removed when cold-window exits; a file left by a process that has died is ignored and removed. Dry runs still preview. SKRILLS_KILL_SWITCH_FILE (an absolute path) moves the file; the Makefile test targets set it so a running cold-window does not fail the test suite’s syncs.

A learned baseline of recent token totals no longer raises the 20K and 50K tiers, since that hid steadily growing totals. When --alert-budget is at or below 50K, Advisory moves to 20% and Caution to 50% of the ceiling, so all four tiers can still fire in order. --alert-budget below 2 is refused, because 0 or 1 cannot hold ordered tiers.

All thresholds are configurable via builder methods on LayeredAlertPolicy if you embed the engine directly.

Browser security posture

Two layers of XSS defense:

1. The server html_escapes every user-derived string before it lands in a fragment.
2. The browser swap path uses DOMParser and replaceChildren, which parses <script> tags into nodes that do not execute when later attached to the document. Even if Layer 1 ever regresses, an injected payload can’t run.

When TLS is configured (axum-server and rustls), ALPN advertises h2. Multiple browser tabs in the same origin all stay subscribed past HTTP/1.1’s 6-connection-per-origin limit because HTTP/2 multiplexes streams.

Plugin participation (FR11)

Third-party skrills plugins opt into the cold-window by shipping a health.toml file alongside their .claude-plugin/plugin.json. Each tick the engine cold-walks the configured plugins root (--plugins-dir, default ./plugins) and parses every <plugin>/health.toml it finds. Schema:

plugin_name = "my-plugin"   # optional, defaults to directory name
overall = "ok"              # ok | warn | error | unknown

[[checks]]
name = "smoke"
status = "ok"
message = "all systems nominal"  # optional

[[checks]]
name = "deps"
status = "warn"

Plugins without a health.toml are silently excluded. A missing file is the opt-out signal, not an error. Malformed health.toml files (parse error, unknown status string) trigger a deterministic Caution-tier alert with a stable fingerprint (plugin-health-malformed::<plugin>) and exclude the plugin from the snapshot until the file is fixed (spec EC5). Hysteresis and min-dwell are skipped for these alerts because user configuration errors need immediate visibility.

Prior-art validation

The cold-window’s design draws explicitly from mature reference implementations.

The user-pain quotes that anchor the threshold defaults (20 K Advisory, 50 K Caution) come from the Expensively Quadratic HN thread and Simon Willison’s Too many MCPs post. Geoffrey Huntley’s measurement that the GitHub MCP alone “swallows another 55,000 of those valuable tokens” maps directly to the 50 K tier.

Known caveats

• 80 % Warning vs Anthropic’s 83.5 % auto-compact: skrills fires Warning at 80 % of --alert-budget, slightly ahead of Claude Code’s auto-compact trigger. Community evidence (anthropics/claude-code#28728, #46695) suggests 75 % may be safer for sessions you intend to compact. Per-tier thresholds are not configurable yet.
• Kill-switch override: there is no “ignore the kill-switch” flag in v0.8.0. If you hit 100 %, raise --alert-budget and restart. This matches the safer-than-sorry posture of cockpit Warning alerts in FAA AC 25.1322-1. If it proves too restrictive in practice, we may add an opt-in --allow-budget-override.
• SSE shutdown semantics: the browser surface merges a shutdown notify into the SSE response stream so Ctrl-C returns within the 2 s budget. Without the merge, a pending broadcast-await would block graceful shutdown indefinitely (axum #2673, hyper #2787). Future maintainers: do not “simplify” by removing the merge.

Dogfooding the surfaces

A dogfood-all Make target exercises every cold-window surface end-to-end against real fixtures. Useful when verifying a release candidate or after touching the engine, browser, or shutdown code:

make dogfood-cold-window-headless   # engine ticks 3 s, expects clean SIGTERM
make dogfood-cold-window-chaos      # --demo --no-adaptive and budget=3, kill-switch path
make dogfood-cold-window-browser    # HTML/SSE parity and 2 s shutdown budget
make dogfood-tui                    # tui TTY-or-graceful-refusal contract
make dogfood-dashboard              # dashboard TTY-or-graceful-refusal contract
make dogfood-skill-diff             # skill-diff --format json round-trips
make dogfood-all                    # everything above and the original dogfood

The browser target is the load-bearing one: it boots cold-window --browser on :18888, asserts the rendered HTML declares EventSource listeners for the four canonical event names (alert, hint, research, status), then opens a 2 s curl -N against /dashboard.sse and confirms the engine emits matching event: lines plus at least four data: payloads. After that it sends SIGTERM and asserts the process exits inside the 2 s graceful-shutdown budget. The contract being tested is “the HTML page’s listener set equals the SSE endpoint’s emitter set”, the same parity guarantee that the in-tree integration test crates/server/tests/cold_window_parity.rs verifies via the broadcast bus directly. Together they cover both the Rust-internal path and the externally-observable HTTP contract.

The tui and dashboard targets validate the TTY-guard contract: under a real terminal the process renders until the 3 s timeout fires (rc 124 / 143). Under a non-TTY environment (CI, redirected stdio) the process exits 1 with a clear requires a TTY message rather than crashing on a termios syscall against /dev/null. Both surfaces use the same guard pattern (tui_flow in crates/cli/src/tui.rs and the Commands::Dashboard arm in crates/cli/src/dispatcher.rs).

Hint patterns (ISA-18.2 inspired)

The hint scorer surfaces these operational patterns when it detects the matching signal in the snapshot:

1. Hysteresis flapping: if a Caution fires within min-dwell of the previous Caution on the same fingerprint, suggest raising the hysteresis floor by 5% (the signal is oscillating near the trigger boundary).
2. Research quota storm: if the research dispatcher drains

   80% of its hourly bucket in under the group interval, suggest widening the fetch interval or adding an inhibition rule for low-tier alerts.

3. Chattering Warning: if a Warning resolves and re-fires within the repeat interval, suggest adding a dead-band or shelving per ISA-18.2.
4. Cascade suppression: if an Emergency alert fires while a Critical on the same fingerprint is unacked, surface a keystroke hint to master-ack the superseded Critical.
5. Span-of-control overload: if the hint pane shows > 7 active hints simultaneously, suggest shelving advisories or raising the Caution floor (ISA-18.2 §6.4 operator limit).

Roadmap

• Production tick producer using analyze::tokens::count_tokens_attributed against real discovery output, covering MCP and conversation tokens as well as --skill-dir skills.
• Per-tier configurable thresholds (community evidence supports 75 % Warning; not yet scheduled).
• Clippy-style Applicability axis for hints (MachineApplicable / MaybeIncorrect / HasPlaceholders / Unspecified) orthogonal to severity (rust-clippy precedent).
• ISA-18.2 ack state machine for master-acknowledge (Normal → Unack → Ack → RTNUnack, plus Shelved / Suppressed / OOS).
• gRPC service surface for external clients. The wire-format crate skrills-snapshot is already designed proto-friendly per the brief.

Reference

• ADR 0007: Cold-Window Architecture
• architecture.md
• War-room decision: docs/archive/2026-04-26-cold-window-war-room.md

Sync Guide

Skrills synchronizes skills, commands, rules, MCP server configurations, and preferences between Claude Code, Codex CLI, GitHub Copilot CLI, and Cursor IDE. 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, Copilot, and Cursor). 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

# Claude → Cursor only
skrills sync-all --to cursor

# Cursor → Claude
skrills sync-all --from cursor --to claude

What Gets Synced

Skills

Skills are copied between skill directories:

• Claude: ~/.claude/skills/
• Codex: ~/.agents/skills/{name}/SKILL.md, the user skills directory Codex loads (frontmatter name set to the folder name, description required). Skills under the old ~/.codex/skills/ are still read as a source.
• Copilot: ~/.copilot/skills/ (same SKILL.md format as Codex)
• Cursor: ~/.cursor/skills/{name}/SKILL.md (frontmatter cut to name and description, which Cursor requires)

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)
• Cursor: ~/.cursor/commands/{name}.md

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 Code: user-scope servers in ~/.claude.json (not settings.json)
• Codex: [mcp_servers.*] tables in ~/.codex/config.toml
• Copilot: Uses mcp-config.json (separate from main config)
• Cursor: Uses .cursor/mcp.json

Tool filtering fields (allowedTools/disabledTools) are preserved during sync. When set, allowed_tools restricts which tools are available from a server and disabled_tools hides specific tools from the model.

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

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

Plugin Assets and Manifest Synthesis

Full-mirror sync copies each plugin’s tree into ~/.cursor/plugins/local/<plugin>/, keeping every file at its path within the plugin so skills resolve companion scripts at the relative paths they document. Claude’s .claude-plugin/ manifest directory is renamed to the .cursor-plugin/ name Cursor reads, so the plugin registers as installed. Skill bodies travel this path too: sync_skills is off for Cursor targets, because the flat ~/.cursor/skills copy it produces would duplicate plugin content. Unchanged files are skipped by content hash, a path that escapes its plugin directory is refused with a warning, and the executable bit is preserved on Unix. Stale entries under ~/.cursor/plugins/local/ are pruned automatically on each sync.

Each sync mirrors the newest cached version of a plugin (1.10.0 beats 1.9.21) over the previous one. The .skrills-mirror marker in each mirrored plugin lists the files sync wrote, and only those are ever removed: a file the new version no longer ships goes, while files the plugin creates at runtime stay. A flat ~/.cursor/skills/<name> copy of a skill the mirror now carries is removed when sync wrote it. Pass --keep-versions to keep both; --dry-run lists what would be removed. Plugin hook matchers are renamed to Cursor’s tool names (Bash to Shell, Edit and MultiEdit to Write).

Cursor also runs Claude plugin hooks from ~/.claude/plugins itself when Include Third-Party Plugins, Skills, and Other Configs is on, so each hook then runs twice, once from the Claude install and once from the mirror. Turn that setting off to run only the mirrored, newest version.

When a Claude plugin ships without .claude-plugin/plugin.json (some upstream plugins, including typescript-lsp and pyright-lsp from claude-plugins-official, ship only a README and source tree), full-mirror sync now synthesizes a minimal manifest instead of dropping the plugin from the target. Synthesis follows a fixed contract:

Synthesis is gated to full-mirror sync only (the default for --to cursor). Skill-mirror targets such as Codex, which only consume skills/ and never read plugin.json, leave manifest-less plugins as-is. Real manifests are never overwritten. Synthesis runs only when the plugin walk finds no plugin.json on disk.

To audit synthesized manifests after a sync, query the marker:

find ~/.cursor/plugins/local -name plugin.json \
  -exec jq -r 'select(._synthesized == true) | .name' {} \;

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

Shorthand Sync Commands

For convenience, shorthand commands sync from a specific CLI to all others:

skrills sync-from-claude     # Claude as source of truth
skrills sync-from-codex      # Codex as source of truth
skrills sync-from-copilot    # Copilot as source of truth
skrills sync-from-cursor     # Cursor as source of truth (converts .mdc back to SKILL.md)

These are equivalent to skrills sync-all --from <cli>.

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 refreshes Codex’s global ~/.codex/AGENTS.md (never an AGENTS.md in the working directory):

skrills mirror --skip-existing-commands

Use --dry-run to preview:

skrills mirror --dry-run

Cursor Rules

Cursor IDE stores project instructions as .mdc files in .cursor/rules/ with YAML frontmatter controlling when each rule applies. Skrills maps between Cursor rules and Claude/Copilot instruction formats:

# Sync rules from Cursor to Claude
skrills sync-all --from cursor --to claude

# Sync Claude instructions to Cursor rules
skrills sync-all --from claude --to cursor

Cursor-only frontmatter fields (globs, alwaysApply) are preserved in content bytes during Cursor-to-Claude sync but have no effect in Claude. See ADR 0006 for the mapping rationale.

Cursor Hooks

Hook event names are translated between Claude’s PascalCase and Cursor’s camelCase conventions:

The Notification event has no Cursor equivalent and is skipped during sync. See ADR 0006 for the full mapping rationale.

Claude-to-Cursor sync does not copy top-level hooks into ~/.cursor/hooks.json. Cursor loads Claude Code hooks from ~/.claude/settings.json itself and runs every matching hook from both files, so a copy would run each hook twice. The report lists hooks as skipped for that reason.

A mirrored plugin’s hooks/hooks.json is rewritten into Cursor’s layout: event names become camelCase, each nested hooks list is flattened into entries that carry their group’s matcher, and ${CLAUDE_PLUGIN_ROOT} becomes the mirror’s absolute path. Matchers are kept as written, so a hook that matches a Claude tool name Cursor does not use (such as Skill) never fires there.

Cursor-only events (afterFileEdit, beforeShellExecution) are preserved in raw content during Cursor-to-Claude sync.

Cursor Agents

Agent fields are translated:

• background (Claude) ↔ is_background (Cursor)
• tools (Claude) has no Cursor equivalent. An agent whose list holds none of Write, Edit, MultiEdit, NotebookEdit or Bash is written with readonly: true, Cursor’s only restriction. An agent that keeps a write tool can use every tool in Cursor, and the report names it.

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

The installer syncs no skills unless SKRILLS_UNIVERSAL=1 is set; see Installation for its variables.

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
• The installer also reads it to pick the client for skrills setup, where copilot, cursor, both and all are accepted too

# 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. With it set, skrills serve also saves analytics when the server exits, over stdio or HTTP, including when it exits with an error.

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

Skills synced to Codex are folders under ~/.agents/skills/. Other tools write there too, so remove the folders you no longer want rather than the whole directory. Skills synced by versions before 0.9.1 are under ~/.codex/skills/:

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 skills to ~/.agents/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 and 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

Tests are in three places. Unit tests are beside the code in #[cfg(test)] modules. Integration tests are under each crate’s tests/ directory: crates/server/tests/ covers the MCP server, HTTP transport and dashboard, crates/sync/tests/ covers cross-agent sync, crates/subagents/tests/ covers the subagent service, and crates/cli/tests/ drives the real skrills binary. Characterization tests for the shell scripts in scripts/ are under tests/unit/ and run under pytest.

make test            # every Rust test in the workspace
make test-unit       # #[cfg(test)] modules only
make test-integration
make test-scripts    # pytest tests/unit; needs pytest on PATH

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.
• Dashboard Navigation: Tests verify keyboard navigation edge cases including empty skill lists and lazy-loading boundaries.
• CLI Backend Resolution: Tests cover multi-cli-agent backend selection, binary probing, and fallback ordering.
• HTTP Transport: Tests verify port binding, TLS configuration, CORS setup, auth middleware, port fallback exhaustion, and Host validation (403 for a host outside the allow-list).
• CLI Dispatch: Tests under crates/cli/tests/ spawn the built binary, which is the only way to catch a defect in run() itself, such as a missing dispatch arm or a signal disposition that stops the process waiting on children.
• Crate Boundaries: crates/test-utils/tests/crate_boundaries.rs fails when a crate crosses a boundary recorded in ADR 0009 or ADR 0010 (see Development).
• Lint Scripts: pytest cases run each lint in a temporary tree and assert its exit code, including exit 2 when ripgrep itself fails, so a gate cannot fail open.

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.89+, preferably with rustup. 1.89 builds the libraries and binaries (the workspace sets rust-version = "1.89"). Running the tests needs Rust 1.93.1+, because the serial_test 4 dev-dependency requires it.
• 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

make test runs this command. make ci runs, locally, the checks the CI workflow (.github/workflows/ci.yml) gates on: fmt-check, lint, lint-md, lint-hygiene, test, test-scripts and test-install. CI itself calls cargo and the scripts directly, so keep the two in step. make precommit adds the dogfood contracts and verify-publish.

Release-Consistency Checks

Before tagging a release, run make release-consistency to verify five parity invariants across the workspace. Crates are versioned in lock-step; ADR 0004 (independent intelligence versioning) is superseded.

1. All crates/*/Cargo.toml versions agree.
2. plugins/skrills/.claude-plugin/plugin.json version matches the workspace crate version.
3. Every command path in plugin.json.commands exists on disk.
4. The top-level plugins/skrills/commands/*.md count equals plugin.json.commands.length.
5. .claude-plugin/marketplace.json plugin entries agree with the workspace and each entry’s source path exists on disk.

For a live inventory before running the parity tests, use make demo-release-consistency, which prints the actual on-disk versions and command counts before invoking the test suite.

The same tests are picked up by make test and make test-integration via the --test '*' filter, so CI also enforces the invariants.

Crate-Boundary Checks

crates/test-utils/tests/crate_boundaries.rs reads the workspace sources and fails when a recorded crate boundary is crossed: skrills-server exports a module outside its server set or re-exports another crate, a crate other than skrills_sync defines enum Platform (ADR 0009), or skrills-analyze depends on skrills-intelligence without optional = true (ADR 0010). If one fails, either undo the coupling or revise the ADR along with the test. Run them alone with cargo test -p skrills-test-utils --test crate_boundaries.

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. See 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.

• The process installs no SIGCHLD handler. Wait on every child you spawn: Command::status() and Command::output() do this for you, and a bare spawn() needs an explicit wait() or the child lingers as a zombie until skrills exits.
• Never set SIGCHLD to SIG_IGN or install a handler with SA_NOCLDWAIT. The kernel then reaps children itself, waitpid returns ECHILD, and every Command::status() or Command::output() in the process fails with “No child processes”. An earlier startup handler did exactly this, and analyze-project-context returned an empty git_keywords list because its git log could not be waited on.
• Two checks guard the invariant through the real binary, since unit tests call command functions directly and never pass through run(): crates/cli/tests/subprocess_wait.rs under cargo test, and the “subcommands can still run subprocesses” scenario in scripts/dogfood-contracts.sh.

Workflow Best Practices

Follow these practices to maintain code quality and development standards:

• Keep the Crate Boundary: crates/cli owns the command-line surface: the clap definitions, subcommand handlers, dispatcher, sync TUI, doctor and cold-window CLI. crates/server owns the MCP server and the engine those handlers call, and the leaf crates own their domains. Code both the MCP path and a subcommand need stays in crates/server, and setup.rs is there for that reason.
• 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, Codex CLI, GitHub Copilot CLI, and Cursor.

Core Differentiators

Validation Engine

Skrills validates skills against four targets with distinct requirements. Claude Code is permissive, accepting any markdown with optional frontmatter. Codex CLI and Copilot CLI are strict, requiring YAML frontmatter with name and description fields. Cursor uses .mdc rule files with description and mode fields (globs or alwaysApply). The --autofix flag automatically derives missing frontmatter, normalizes names to kebab-case, and scaffolds body sections when content is too short.

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 across Claude Code, Codex CLI, Copilot CLI, and Cursor. It analyzes token usage, synchronizes configurations bidirectionally between all four environments, and provides both a browser dashboard and a self-contained HTML portal for offline exploration.

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): Skill dependency resolution via YAML frontmatter, with circular-dep detection, semver constraints, and source pinning. New skill-loading-{status,selftest}, enable-skill-trace, disable-skill-trace diagnostics. Adopted rmcp 0.10 (BREAKING).
• 0.3.1 (2025-12-13): Introduced skrills-validate (Claude Code permissive and Codex strict frontmatter) and skrills-analyze (token counting and dependency analysis) crates.
• 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.9.1 (Unreleased)

• Cursor: skills synced to Cursor keep the name and description frontmatter Cursor needs to load them. A mirrored plugin’s hooks/hooks.json is rewritten to Cursor’s hook layout. Top-level Claude hooks are no longer copied, because Cursor already loads them from ~/.claude/settings.json. Agents with no write tool become readonly.
• Codex: skills go to ~/.agents/skills, the only user skills directory Codex documents, instead of ~/.codex/skills. This covers sync, mirror, sync-all, the TUI, the sync-from-claude and sync-all MCP tools, and create-skill for a Codex-only install. Discovery and skrills setup --universal use ~/.agents/skills in place of ~/.agent/skills, which no tool loads. sync-from-claude now reports warnings instead of the synced name list.
• Copilot: on macOS, sync and skrills setup write to ~/.copilot (or COPILOT_HOME), where Copilot CLI reads, instead of ~/Library/Application Support/copilot.
• Claude MCP servers: sync reads and writes them in ~/.claude.json, where Claude Code loads user servers, instead of ~/.claude/settings.json. Servers an earlier version wrote into settings.json are no longer read.
• Codex agents: go to ~/.agents/skills/agent-<name>. A Claude model is no longer replaced by gpt-4o on Codex or Copilot; the target keeps its own model.
• Sync safety: the Cursor plugin mirror no longer deletes or overwrites a plugin it skipped or a directory it does not own, one unwritable item no longer stops a whole phase, and concurrent syncs into one target wait on a lock file.
• Server: credentials in MCP server arguments and hook commands are redacted from the dashboard API, cold-window --browser checks Host, fetch-pdf refuses private addresses, an empty auth token is refused, and the dashboard works with --auth-token (open it at /#token=<TOKEN>).
• CLI: skrills doctor exits non-zero when it finds problems. --include-description, --include-quality and --suggestions turn off with =false. cold-window --alert-budget must be at least 3.
• Validation: autofix keeps every frontmatter field, writes YAML that parses, and no longer panics on long descriptions with multibyte characters.
• API: SyncError has a new KillSwitchEngaged variant, which breaks exhaustive matches outside this workspace.
• Codex agents run sandboxed: skrills agent and multi-cli-agent run codex exec --sandbox workspace-write; --dangerously-bypass-sandbox restores the old unsandboxed run.
• Kill switch across processes: while cold-window’s kill switch is engaged, syncs in every other process refuse to write.
• Skill roots: CLI commands, the dashboard and /api/skills scan ~/.claude only with SKRILLS_INCLUDE_CLAUDE=1, as the MCP server does.
• Sync: each skill gets one folder name in every target, skrills-written skill folders carry a .skrills-synced marker, JSON config rewrites keep key order, and marketplace skills sync when --include-marketplace is given.
• TUIs: Esc backs out of what is open, then quits, in both TUIs; cold-window master-ack holds until the alert resolves.
• Build: MSRV 1.89, YAML via serde_norway, tests run in parallel, and every shell script follows one style checked by scripts/shellcheck.sh (shellcheck plus shfmt).
• API: skrills_sync::Platform replaces platform strings, and skrills-server drops its deprecated items. Both break callers outside this workspace.
• Agent timeout: skrills agent and multi-cli-agent stop a run after --timeout seconds (default 1800, 0 for no limit).
• Setup: skrills setup --universal --include-marketplace also copies marketplace skills; off by default.
• Crates: skrills-server no longer exports discovery, sync, setup or config. They moved to skrills-discovery, skrills_sync, the new skrills-setup crate and the CLI (ADR 0009).

0.9.0 (2026-10-13)

• Security: Host is validated on every HTTP route, not only /mcp. setup --universal syncs skill directories only, instead of copying all of ~/.claude (credentials and transcripts included) into ~/.agent. serve --http reads auth_token from the config file itself, subagent CLI children no longer inherit server secrets, and skill generation sends the GitHub token only to GitHub. fetch-pdf, the tome clients and MCP create-skill are bounded. Third-party GitHub Actions are pinned to commit SHAs, and rustls, h2, quinn-proto and crossbeam-epoch advisories are closed.
• BREAKING: cold-window shows only real data unless --demo is passed. --alert-budget must be at least 2, and a ceiling at or below 50K scales the Advisory and Caution tiers to 20% and 50% of it. See Cold-Window Real-Time Analysis.
• BREAKING: Commands fail loudly: validate exits non-zero on errors, serve --http --watch and skill-catalog --category are refused, cert renew refuses a CA-issued certificate without --force, and tracing goes to stderr so --format json stdout stays parseable.
• Fix: sync-all --validate and --autofix work: the source skills are validated for the strictest target before any target is written, and any error aborts every target. See CLI Reference.
• Change: Copilot prompt files are written as .prompt.md (.prompts.md is still read). Sync writes are atomic, keep a .skrills-bak of user config files, merge MCP servers by name, and write CLAUDE.md inside a marked block.
• Migration: rmcp 1.8 to 3.4, with the advertised MCP protocol capped at 2025-11-25. The CLI moved from skrills-server into the skrills crate.
• Fix: setup, uninstall and doctor agree on where each client is registered (Codex in ~/.codex/config.toml). Subagent CLI runs honour timeouts and stop-run kills the child. The dashboard reads the shared ~/.skrills/metrics.db. Cursor plugin sync mirrors the whole plugin tree, not only its manifest.

0.8.2 (2026-05-30)

• BREAKING: Esc no longer quits the cold-window TUI: it closes the topmost overlay, then clears zoom, and does nothing at the base surface (lazygit/gitui/k9s convention). Quit with q or Ctrl-C. See Cold-Window Real-Time Analysis.
• Feature: Cold-Window TUI surface (skrills cold-window --tui): The cold-window panes now mount in a crossterm raw-mode loop, completing the surface the v0.8.0 panes were built for. --tui renders alerts, ranked hints, the research panel, and the token/budget status bar live in the current terminal, subscribing to the same engine bus as the browser surface; both can run together. Quit with q or Ctrl-C; --no-bell silences the WARNING-tier bell. First paint is asserted under the spec § 6 SC3 500ms budget (cold_window_tui_startup_under_five_hundred_ms, previously #[ignore]d for the missing launch path). See Cold-Window Real-Time Analysis.
• Feature: Responsive --tui layout: The panes re-flow live on resize across three width tiers: wide (≥ 80 cols) keeps the 60/40 two-column layout, medium (60-79 cols) slims the research column so alert/hint text stays readable, and narrow (< 60 cols) stacks every pane full-width with a collapsed research pane as a three-line badge. The status bar stays pinned to the bottom in every tier. Layout is a pure plan_layout function tested without a terminal. Also fixes ResearchPaneState::default to start collapsed (matching new()) instead of silently opening the pane on launch.

0.8.1 (2026-05-09)

• Fix: Synthesize plugin.json for manifest-less plugins: Plugins shipped without .claude-plugin/plugin.json (e.g. typescript-lsp, pyright-lsp) are no longer dropped during claude --to cursor full-mirror sync. read_plugin_assets now emits a minimal manifest with name / version from the cache layout, description from the README’s first prose line (or a documented fallback), empty component arrays, and a _synthesized: true audit marker. Real manifests are never overwritten; synthesis is gated to full_mirror=true so skill-mirror targets stay untouched. See Sync Guide → Plugin Assets and Manifest Synthesis.
• Testing: Pin manifest-synthesis contract: Three new and strengthened tests in crates/sync/src/adapters/claude/mod.rs lock description sourcing, no-README fallback, and full-mirror gating against silent regressions; the pre-existing read_plugin_assets_does_not_synthesize_when_real_manifest_present continues to guard real-manifest preservation.

0.8.0 (2026-04-28)

• Feature: Cold-Window Real-Time Analysis (skrills cold-window): New continuously-refreshing analysis surface. Each tick re-reads authoritative state, runs a 4-tier alert policy with hysteresis and min-dwell, ranks hints via a recency-weighted multi-signal scorer, attributes tokens per source (skill / plugin / MCP / conversation), and gates external research fetches through an AlertManager-style dispatcher with restart-resilient quota persistence at ~/.skrills/research-quota.json. v0.8.0 ships browser mode (--browser); the TUI panes are fully implemented as library code and mount in a follow-up. Token thresholds are research-backed: 20K Advisory, 50K Caution, 80% Warning, 100% kill-switch. See Cold-Window Real-Time Analysis for the user guide.
• Testing: Release-Consistency Invariants: Filesystem-walking parity tests guard against workspace version drift and plugin.json/marketplace.json manifest drift. Five invariants: crate versions agree, plugin.json version matches workspace, registered commands exist on disk, top-level command count matches plugin.json.commands.length, and marketplace.json plugin entries agree with the workspace and have valid source paths. Pattern adapted from claude-night-market v1.9.3.
• Makefile: release-consistency Target: Focused pre-tag verification entry point (make release-consistency).

0.7.7 (2026-04-15)

• Refactor: Manifest-Only Plugin Sync: write_plugin_assets now writes manifests to plugins/local/<plugin>/.cursor-plugin/plugin.json instead of mirroring the full cache. Cursor discovers plugin content natively from ~/.claude/plugins/cache/. Stale plugin directories are pruned automatically.
• NEW: Plugin-Aware Skill Writing: Skills from plugins write to plugins/local/<plugin>/skills/ so Cursor’s plugin system discovers them. Manifests are auto-created per plugin.
• NEW: PluginOrigin Type: Tracks which plugin an artifact came from (name, publisher, version). Enables plugin-aware writing in target adapters.
• NEW: Validation Cache: SQLite-backed cache for offline skrills validate with staleness indicators (fresh/recent/aging/stale).
• NEW: Network Detection: NetworkStatus module detects connectivity with configurable timeout for graceful offline degradation.
• NEW: GitHub Action: Reusable composite action (.github/actions/validate-skills/) validates skills in PRs with configurable targets, strictness, and annotation output.
• NEW: Interactive Sync Preview: SyncParams.interactive field enables per-file accept/reject before writing (scaffolded, CLI wiring pending).
• Refactor: strum Derives: NodeKind and EdgeKind use strum::EnumIter and strum::EnumCount instead of manual all() methods.
• Fix: cargo fmt: Resolved formatting violations in claude adapter, cursor tests, and knowledge graph timestamp parser.
• Fix: Marketplace Manifest: Updated .claude-plugin/marketplace.json from stale 0.6.1 to 0.7.7 with correct tool count (36) and Cursor mention.
• Testing: 8 manifest-sync and stale-plugin pruning tests. Snake_case normalization tests for async research tools. 21 validation cache tests. 5 network detection tests.

0.7.6 (2026-04-12)

• NEW: Plugin Assets Sync: Cursor sync now mirrors plugin runtime scripts, binaries, and source packages from ~/.claude/plugins/cache/ to ~/.cursor/plugins/cache/. Preserves directory hierarchy so skills can reference companion scripts at the same relative paths.
• NEW: PluginAsset Type: Sync schema type with publisher, plugin name, version, relative path, content, hash, and executable permission tracking.
• NEW: Claude Adapter read_plugin_assets(): Walks the plugin cache collecting all files except those handled by other sync paths (skills/, commands/, agents/) and runtime artifacts.
• NEW: Cursor Adapter write_plugin_assets(): Writes plugin assets with hash-based change detection and executable permission preservation.
• Testing: 18 new tests covering plugin asset read/write, exclusion rules, version picking, executable detection, and integration flows.

0.7.5 (2026-04-07)

• Refactor: Research Handlers: Serde-based enum parsing, module-level imports, and hardened error handling for research MCP tools.
• Fix: Error Reporting: search-papers now returns is_error: true when all sources fail. PDF downloads validate HTTP status. Unpaywall errors are logged.
• Refactor: Knowledge Graph Timestamps: Node.created_at uses OffsetDateTime with RFC 3339 serde instead of raw strings.
• Fix: Snake-Case Tool Names: All 36 MCP tools accept both kebab-case and snake_case names via universal normalization in call_tool() dispatch.
• Fix: Legacy Timestamp Fallback: parse_rfc3339 falls back to SQLite’s datetime('now') format for pre-0.7.5 knowledge graph databases, treating legacy timestamps as UTC.
• Refactor: Cache Directory Dedup: ResearchCache::open() delegates to Self::cache_dir(), eliminating duplicated path logic.
• Testing: Enum round-trip tests for NodeKind and EdgeKind, cache directory creation test, legacy and RFC 3339 timestamp parse tests.

0.7.4 (2026-04-02)

• NEW: Research MCP Tools: 9 tools expose the tome crate over MCP: search-papers, search-discussions, resolve-doi, fetch-pdf, query-knowledge-graph, add-knowledge-node, link-knowledge, track-citations, resolve-contradiction (27 → 36 tools).
• Fix: Paper Model: Refined Paper model fields and research handler argument parsing.

0.7.3 (2026-03-29)

• NEW: MCP Tool Filtering: allowed_tools/disabled_tools fields on McpServer synced across all four adapters.
• NEW: MCP Servers Dashboard: TUI and browser dashboards show MCP server name, source, transport, and tool filters. New /api/mcp-servers REST endpoint.
• Fix: Configurable Unpaywall Email: UnpaywallClient::new() accepts a custom email, replacing the hardcoded default.
• Fix: OffsetDateTime for Discussions: Discussion::created_at uses time::OffsetDateTime with RFC 3339 serde instead of a raw string.
• Fix: SQL Upsert: Knowledge graph and citation tracker INSERT OR REPLACE replaced with ON CONFLICT DO UPDATE to preserve timestamps and metadata.
• Refactor: Promoted split_frontmatter to shared adapter utilities for cross-adapter reuse.
• Testing: Parser tests for five tome API clients, Cursor adapter edge cases, sync error paths, serde roundtrip tests, MCP tool-filtering roundtrip tests, dashboard MCP panel tests, and API integration tests.

0.7.2 (2026-03-25)

• Fix: Cursor Sync Reliability: Hardened bidirectional sync for Cursor adapter across agents, commands, rules, and skills.
• NEW: Shorthand Sync Commands: /sync-from-cursor, /sync-from-claude, /sync-from-copilot slash commands.
• NEW: tome Research Crate: Academic paper search, citation extraction, knowledge graph, and PDF retrieval.
• CLI: --open enforces --http; all sync commands accept Cursor as source/target.
• Testing: Extended Cursor adapter and CLI test coverage.

0.7.1 (2026-03-21)

• NEW: multi-cli-agent Command: Agent launching with automatic Claude/Codex backend routing.
• NEW: --open Flag: Auto-launch browser dashboard on skrills serve.
• HTTP Transport: Port fallback (up to 10 consecutive ports) when default port is busy.
• Dashboard: Light-mode support for the browser dashboard.
• Testing: Edge-case coverage for dashboard navigation, CLI backend resolution, and port binding.

0.7.0 (2026-03-19)

• NEW: Cursor IDE Support: Full bidirectional sync for .cursor/ (rules, skills, commands, agents, hooks, MCP).
• NEW: Rules Sync: Maps Cursor .mdc files with mode derivation (alwaysApply, glob-scoped, agent-requested) to/from Claude and Copilot instruction formats.
• NEW: MCP Tools: sync-from-cursor and sync-to-cursor (25 → 27 tools).
• NEW: CLI Flags: --from cursor and --to cursor for sync commands.
• Refactor: Extracted shared adapter utilities and reworked orchestrator for four-way sync routing.
• Architecture: ADR 0006 documents the Cursor rules mapping strategy.

0.6.1 (2026-03-05)

• Fix: Tests now use distinct filenames instead of case-only differences to avoid collisions on case-insensitive filesystems (macOS APFS/HFS+).
• Internal: Bumped all workspace crate versions to 0.6.1 and updated MCP tool count to 25.

0.6.0 (2026-02-15)

• Discovery: Frontmatter-based skill deduplication across roots using name field and Jaccard similarity on descriptions. Skills with matching frontmatter identity are consolidated regardless of path differences.
• Dashboard: Sortable skills panel (press s to toggle alphabetical/discovery order), stateful list scrolling, and multi-location display showing all roots where a skill was discovered.
• Dashboard: Extracted SkillLocation struct to track per-skill discovery sources and paths. Metrics panel shows location count and source details.
• Fix: Corrected plugin.json command paths from ../commands/ to ./commands/.

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: Trimmed 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: 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.
• 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: 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