skillfile

Track AI skills and agents declaratively, like dependencies. Pin them. Patch them. Deploy everywhere.

Declare your skills in a manifest. Pinned to exact commits. Deploys to Claude Code, Cursor, Gemini, and 5 more. Customize without losing upstream updates. Search 110K+ skills from the terminal.

You found a great skill on GitHub and copied the markdown into .claude/skills/. Maybe you grabbed one from agentskill.sh. So what now?

• Each hub has its own install tool
• Nothing tracks what you installed
• No way to update when the author improves it
• Edit it? Your changes vanish on reinstall
• Switch to Cursor or Gemini CLI? Copy everything again

skillfile fixes all of that. One manifest, one lock file, every platform.

Install

cargo install skillfile

Or download a pre-built binary from GitHub Releases. Or build from source:

git clone https://github.com/eljulians/skillfile.git && cargo install --path crates/cli

Single binary, 3.5 MB, no runtime dependencies.

GitHub token recommended. skillfile uses the GitHub API to resolve commits. Without a token you're limited to 60 req/hour. Set GITHUB_TOKEN, GH_TOKEN, or run gh auth login.

Quick Start

skillfile init                                           # pick your platforms
skillfile add                                            # guided wizard
skillfile add github skill anthropics/courses skills/    # or add directly

That's it. Skills are fetched, locked to exact SHAs, and deployed. On a fresh clone, skillfile install reproduces the exact same setup.

Looking for skills to install? See awesome-agents-and-skills for a curated collection with a ready-to-use Skillfile.

Add skills from anywhere

Run skillfile add for a guided wizard, or use the explicit CLI for any source:

skillfile add                                            # wizard: GitHub, search, local, URL
skillfile add github skill anthropics/courses            # discover all skills in a repo
skillfile add github skill anthropics/courses skills/research  # add one specific skill
skillfile add local skill skills/my-custom/SKILL.md      # track a local file
skillfile add url skill https://example.com/skill.md     # add from a URL

When discovering from a GitHub repo, skillfile opens a split-pane TUI where you can browse entries, preview SKILL.md content, and multi-select what to install. Each selected skill becomes an independent manifest line you can pin, update, or remove individually.

Search community registries

Browse agentskill.sh, skills.sh, and skillhub.club without leaving the terminal. Results are sorted by popularity, deduplicated, and include security scores.

skillfile search "code review"                    # interactive TUI with preview
skillfile search docker --min-score 80            # only high-trust results
skillfile search testing --registry agentskill.sh # target a single registry

Customize without losing upstream updates

Edit an installed skill to fit your workflow, then pin it. Your changes survive upstream updates automatically.

vim ~/.claude/skills/browser/SKILL.md     # edit the deployed file
skillfile pin browser                      # capture your diff as a patch
skillfile install --update                 # update upstream, patch reapplied

# If upstream conflicts with your changes:
skillfile diff browser                     # see what changed
skillfile resolve browser                  # three-way merge in $MERGETOOL

Patches live in .skillfile/patches/ and are committed to version control. Your whole team gets the same customizations.

8 platforms, one manifest

Write your Skillfile once. Deploy to every AI coding tool you use.

Configure multiple platforms at once. skillfile install deploys to all of them.

Reproducible installs

Every GitHub entry is pinned to an exact commit SHA in Skillfile.lock. Commit this file. On any machine, skillfile install fetches the exact same bytes. install --update re-resolves to the latest upstream, and the lock diff shows exactly what changed in code review.

skillfile install                 # fetch locked content
skillfile install --update        # update to latest upstream
skillfile install --dry-run       # preview without fetching
skillfile status --check-upstream # see which entries have updates

Team workflow

Commit Skillfile, Skillfile.lock, and .skillfile/patches/ to your repo. That's it.

The most common team setup: write your own skills in the repo and mix in community ones. Everyone gets the same AI behavior.

# Write an in-house skill and track it
vim skills/our-coding-standards/SKILL.md
skillfile add local skill skills/our-coding-standards/SKILL.md

# Pull in a community skill too
skillfile add github skill anthropics/courses skills/research

# Commit everything
git add Skillfile Skillfile.lock skills/
git commit -m "Add coding standards and research skills"
git push

# Teammate clones and gets everything
git pull
skillfile install    # deploys all skills to their platform

Local skills live in your repo. You write and version them with git. GitHub skills are pinned to exact SHAs in the lock file. Both deploy to every configured platform. New teammate joins, runs skillfile install, and gets the same AI setup as everyone else.

Skillfile format

Line-oriented, space-delimited, human-editable. No YAML, no TOML.

# Platform targets
install  claude-code  global
install  gemini-cli   local

# GitHub-hosted skills and agents
github  skill  obra/superpowers  skills/requesting-code-review
github  agent  reviewer  owner/repo  agents/reviewer.md  v2.0

# Local files
local  skill  skills/git/commit.md

# Direct URLs
url  agent  my-agent  https://example.com/agent.md

Names are inferred from filenames when omitted. Full format specification in SPEC.md.

All commands

Environment variables

Security

skillfile is a file manager. It downloads markdown from sources you specify and places it where your AI tools expect it. It does not execute, verify, or sandbox the content.

The lock file pins entries to exact commit SHAs. The same SHA always produces the same bytes. install --dry-run lets you review what will be fetched. Patches make all local modifications visible in version control. But none of this tells you whether the content is safe.

Review what you install. The risk profile is the same as git clone.

Development

cargo test --workspace                     # unit + integration tests
cargo test --test functional -- --ignored  # network tests (needs GITHUB_TOKEN)
cargo clippy --all-targets -- -D warnings  # lint
cargo fmt --check                          # format check

PRs are very welcome!