Skillfile: A Package Manager for AI Coding Assistant Prompts

Hook

Your team's custom Claude Code skills live in Slack threads, personal dotfiles, and forgotten Notion pages. When a new engineer joins, they spend a day copying markdown files between directories. There's a better way.

Context

AI coding assistants have evolved from party tricks to critical development infrastructure. What started as casual ChatGPT sessions has matured into teams standardizing on Claude Code, Cursor, and similar tools with custom skills—markdown files containing prompts, context, and instructions that shape how AI helps write code. A frontend team might have a "React patterns" skill enforcing component conventions. A platform team might have "AWS CDK guidelines" or "database migration procedures." These skills represent institutional knowledge encoded for AI consumption.

But nobody built tooling for managing them. Engineers sync skills manually, copying .cursorrules files between machines. Teams share skills via Slack or Google Docs. When someone improves a prompt, the edit doesn't propagate. When you switch from Cursor to Claude Code, you manually translate file paths and directory structures. The problem compounds with scale: 5 skills across 3 developers using 2 tools means 30 manual sync operations when anything changes. It's dotfiles hell, except for AI configuration instead of bash aliases.

Technical Insight

Skillfile treats AI prompts as versioned dependencies with the same rigor as code libraries. The core abstraction is a declarative manifest—a Skillfile that declares what skills you want, where they come from, and where they install. A minimal example:

[[skill]]
name = "react-patterns"
source = "github:yourorg/ai-skills/react.md"
install-to = ["claude-code", "cursor"]

[[skill]]
name = "aws-cdk"
source = "gitlab:platform/prompts/cdk-guidelines.md"
install-to = ["claude-code"]
patch = ".skillfile/patches/aws-cdk.patch"

Running skillfile install resolves sources to specific Git SHAs, downloads content, applies any local patches, and copies files into tool-specific directories. The result is a Skillfile.lock that pins exact versions:

[[skill]]
name = "react-patterns"
source = "github:yourorg/ai-skills/react.md"
resolved-sha = "a3f8b92c..."
installed-to = ["/Users/dev/.claude-code/skills/react-patterns.md", "/Users/dev/.cursor/skills/react-patterns.md"]

This lock file enables reproducibility. A teammate clones your repo, runs skillfile install, and gets identical prompts with identical content. When upstream skills update, you explicitly upgrade with skillfile update, review diffs, and commit the new lock file—exactly like cargo update or npm update.

The patch system handles the inevitable reality that you'll customize upstream skills. You fork a community "Python testing" skill but need to add company-specific pytest fixtures. Instead of losing those edits on the next update, skillfile captures them:

# Edit an installed skill locally
vim ~/.claude-code/skills/python-testing.md

# Capture your changes as a patch
skillfile diff python-testing > .skillfile/patches/python-testing.patch

# Update the Skillfile to reference it
[[skill]]
name = "python-testing"
source = "github:community/skills/python.md"
patch = ".skillfile/patches/python-testing.patch"

Now when you skillfile update and the upstream skill changes, your patch reapplies automatically. If there's a conflict (upstream modified lines you also changed), skillfile install fails with a clear error and drops you into skillfile resolve, which presents a three-way merge interface. It's git-style patch management for markdown files.

The multi-source resolution architecture is particularly elegant. Sources can be GitHub paths (github:org/repo/file.md), GitLab including self-hosted (gitlab:instance.com:group/project/path.md), local filesystem paths (file:../shared-skills/api.md), or raw URLs (https://example.com/skills/deploy.md). GitHub and GitLab sources resolve to specific commit SHAs for pinning; URL sources hash content for change detection. This means teams can mix community skills from public repos with internal skills from private GitLab while individual developers reference local WIP skills—all in the same Skillfile.

The installation abstraction separates what from where. Skills and agents are entity types with different file layouts: skills typically install as {name}.md in a skills directory, while agents might need multiple files in a nested structure. The install-to field accepts predefined tool names (claude-code, cursor, antigravity) with baked-in path conventions, or arbitrary paths:

[[skill]]
name = "custom-workflow"
source = "local:./workflows/build.md"
install-path = "~/.config/my-ai-tool/prompts/"

This design means teams share a single Skillfile while individuals use different tools—Alice uses Cursor, Bob uses Claude Code, both run the same skillfile install and get appropriate installations.

The registry search feature integrates with community skill indexes (agentskill.sh, skills.sh, skillhub.club) and presents results in an interactive TUI. Running skillfile search "python testing" queries all registries, scores results, and lets you arrow-key through 110K+ skills with fuzzy filtering. Select one and it generates the Skillfile entry automatically. It's designed for CLI-native discovery without browser context switches.

Gotcha

The security model is deliberately minimal, which is concerning given these prompts control AI behavior. Skillfile downloads markdown from arbitrary sources and installs it with zero content verification—no checksums, no signatures, no sandboxing. A compromised GitHub repo or MITM attack on a URL source could inject malicious prompts that tell your AI to exfiltrate code or insert backdoors. The tool assumes you trust your sources completely. For community skills from unknown authors, you're relying on manual review of markdown content before installation. There's no automated scanning for prompt injection patterns or suspicious instructions.

Patch conflict resolution is entirely manual. When upstream changes collide with your local edits, skillfile resolve drops you into a text-based merge interface with conflict markers. For a single skill, this is fine. For teams maintaining patches on 20+ skills with frequent upstream updates, it becomes tedious merge drudgery. There are no automatic merge strategies ("always prefer local," "always prefer upstream") or AI-assisted conflict resolution—ironic for a tool managing AI configurations. You hand-edit every conflict, which doesn't scale well beyond a handful of actively maintained patches.

Verdict

Use if: You're managing more than five AI skills across multiple machines or team members, you're deploying prompts to multiple AI tools (Claude + Cursor + others), you need reproducible AI configurations for onboarding or CI environments, or you're tired of manually syncing markdown files and losing customizations. The lock file discipline and patch management pay off quickly at team scale. Skip if: You're a solo developer with a handful of static prompts—manual file copying is simpler. Skip if you need security guarantees around prompt content; this tool trusts its sources completely and offers no sandboxing. Also skip if you're uncomfortable with manual merge conflict resolution or prefer GUI-based configuration management. The sweet spot is engineering teams treating AI assistants as infrastructure who need dotfile-style discipline for prompt configurations.