Skillpack

Current release: v0.1 (Python package 0.1.0). See the changelog for available features and release limitations.

Licensed under the MIT License.

Skillpack is a proposed package manager for reusable AI agent skills—something like pip for skills. Its purpose is to help developers and teams declare, version, and share the skill files their agents use.

The initial goal is to reproduce reviewed skill contents across Claude Code and Codex using a project manifest, immutable locks, and safe installation. Reproducing skill files does not guarantee identical agent behavior.

The working PoC currently installs GitHub skills into Codex, Antigravity, Cursor, and Claude Code. Ownership tracking and uninstall now work for newly installed skills; the manifest and cross-agent features below belong to the later MVP.

Planned MVP

• Declare Git-hosted skills in skills.toml.
• Resolve Git references to exact commits and record content hashes in skills.lock.
• Preview and sync locked skills into project-local agent directories.
• Preserve unmanaged files and detect local edits before changing installed skills.

Skillpack will consume existing SKILL.md packages without executing their scripts during installation. Dependency resolution and a hosted registry are deferred beyond the MVP.

Repository overview

This repository contains a Click CLI alongside the product plans, proposed architecture, and implementation backlog. The first Git PoC installs a skill from a GitHub folder URL into agent-specific project-local skill directories. Uninstall removes tracked, unchanged skills.

Run the PoC locally

Package installation

PyPI publication is being prepared; the Git tag alone does not publish a package. After the first public upload, install with python -m pip install skillpack-cli. In your target project, run skillpack init-sources to create writable discovery configuration, then skillpack discovery --source anthropic. Existing configuration is never overwritten. See release instructions for package validation, TestPyPI rehearsal, account setup, upgrades, and removal.

Requires Python 3.11 or newer and Git. The current Git PoC is intended for macOS/Linux.

python3 -m venv .venv
source .venv/bin/activate
python -m pip install -e .
skillpack --help
skillpack install --help
skillpack uninstall --help
skillpack list --help

The working install command is:

skillpack install https://github.com/anthropics/skills/tree/main/skills/skill-creator --agent codex
skillpack list
skillpack uninstall skill-creator --agent codex
# Or omit the name for a numbered selection:
skillpack uninstall --agent codex

Run this from the project where you want the skill installed. It clones the repository into a temporary directory, checks for SKILL.md, and copies the selected folder to .agents/skills/skill-creator. This is the repository-local layout described in OpenAI's skills guidance. References, assets, and scripts are copied together; Skillpack does not execute skill scripts.

This initial version supports https://github.com/OWNER/REPO/tree/REF/SKILL_PATH with a single-segment branch or tag such as main. It rejects symlinks and existing skill destinations. Install, list, and uninstall accept --agent codex, antigravity, cursor, or claude. Local-folder sources and locks remain follow-up work. Each install reads the current ref; it does not pin a reproducible version yet.

skillpack list shows project skill folders and ownership records (Codex by default; filter with --agent). It labels each skill as tracked or untracked; skills installed before ownership tracking remain visible but cannot be uninstalled automatically. Omitting the name from uninstall shows a numbered list; enter a number to remove that skill or 0 to cancel. EOF/Ctrl-C aborts selection. Passing a name still supports scripts without a prompt. Listing reports ownership records, not a content-integrity check; uninstall always checks files before removal.

Installation records file hashes and directories in .skillpack/state.json, which is excluded from Git. Uninstall checks that the folder still matches its record, stages removal, and restores it if updating state fails. Changed, added, missing, or symlinked content prevents removal. Untracked skills—including installations made before ownership tracking—are refused and require manual review/removal. No automatic adoption or force removal is available. Run one Skillpack operation at a time; concurrent operations and recovery after process interruption are outside this PoC.

Run the offline checks with python -m unittest discover -s tests -v.

The command scaffold is tracked in SP-001, the active Git experiment in SP-013, and current progress in PoC status; the fuller MVP configuration contract is tracked separately in SP-011.

Skills requirements in plain text

Use a UTF-8 text file with one individual GitHub skill-folder URL per line. Blank lines and full-line # comments are ignored. Repeated identical URLs are installed once; different URLs with the same folder name are rejected before changes begin. Inline comments, version constraints, collection expansion, and nested requirements files are not supported.

# skills-requirements.txt
https://github.com/dbt-labs/dbt-agent-skills/tree/main/skills/dbt/skills/adding-dbt-unit-test
https://github.com/anthropics/skills/tree/main/skills/frontend-design

skillpack install -r skills-requirements.txt --agent codex
skillpack list --agent codex
skillpack uninstall -r skills-requirements.txt --agent codex

--requirements is the long form of -r. Use either a single URL/name or a file, not both. The requirements-file location does not change the installation project: commands use your current directory. Commit the text file to share your requested skills; .skillpack/state.json remains local. Branches like main can change, so this is not a lockfile.

Batch uninstall does not download skills: it matches each URL to its ownership record and then uses the existing removal checks. It refuses different-source matches and untracked skills. Keep the same requirements URLs for removal. File syntax and name collisions are checked before processing; runtime operations are sequential, stop on the first error, and leave earlier successful operations applied. The error reports the completed count. Existing installations are not skipped or overwritten automatically.

Fresh-start example

The ready-to-use example requirements file includes two skills from each reference collection:

• dbt Labs skills: adding-dbt-unit-test and running-dbt-commands.
• Anthropic skills: frontend-design and skill-creator.

Those collection links contain multiple skill folders. Put the URL of each desired child skill in the file; a collection root itself cannot be installed as one skill. Installing the files does not install dbt or other tools those skills may expect.

After installing the CLI locally as described above, try the example in a fresh temporary project to avoid collisions with your existing skills:

source .venv/bin/activate
skillpack_demo_dir="$(mktemp -d)"
cp examples/skills-requirements.txt "$skillpack_demo_dir/skills-requirements.txt"
cd "$skillpack_demo_dir"
skillpack install -r skills-requirements.txt --agent codex
skillpack list --agent codex
skillpack uninstall -r skills-requirements.txt --agent codex
skillpack list --agent codex

Replace codex with antigravity, cursor, or claude to use another destination. Downloads require network access and Git. Each entry currently clones its repository separately.

Project tracking

See CONTRIBUTING.md for the branching strategy, pull request process, CI checks, and branch protection setup.

Follow the work in the Skillpack GitHub Project. User stories are tracked as repository issues, organized into two phases: Phase 1 — PoC (SP-001 and SP-012 through SP-020) and Phase 2 — MVP (SP-002 through SP-011).

References

• OpenAI plugins
• Skill installer for Codex

Alternatives:

• https://inference.sh/blog/skills/agent-skills-overview
• https://github.com/agentskills/agentskills
• https://github.com/agentplugins/agent-plugins-spec
• https://agentskills.io/home
• https://github.com/vercel-labs/skills/pulls
• https://github.com/anthropics/skills/tree/main/skills/xlsx
• https://github.com/dbt-labs/dbt-agent-skills/tree/main/skills/dbt/skills
• https://awesome-copilot.github.com/skills/

Supported agent destinations

Destinations are configured in src/skillpack/agents.py. All commands use the same mapping. Codex and Antigravity share the same directory and ownership records: installing through either makes the folder available to both, and uninstalling through either removes it from both. Existing Codex state remains compatible. Cursor also discovers .agents/skills, but this PoC manages its dedicated .cursor/skills directory when --agent cursor is selected; avoid duplicate copies of a skill in both locations.

skillpack install https://github.com/anthropics/skills/tree/main/skills/skill-creator --agent claude
skillpack list --agent claude
skillpack uninstall --agent claude

Path references: Antigravity, Cursor, Claude Code. Skillpack copies files unchanged; agent-specific tools and instructions inside a skill may still require adaptation. Tests validate file operations in temporary directories, not runtime behavior inside these applications.

Discover available skills

Edit skills-sources.json to configure named sources. Each alias maps to an object with a required repository url and an optional description:

{
  "anthropic": {
    "url": "https://github.com/anthropics/skills",
    "description": "Anthropic skill collection"
  },
  "anthropic-plugins": {
    "url": "https://github.com/anthropics/knowledge-work-plugins",
    "description": "Knowledge work plugins"
  }
}

Aliases are case insensitive and contain letters, digits, dots, underscores, or hyphens, starting with a letter or digit. Use distinct aliases for different repositories from the same owner. Duplicate aliases (including case variants), invalid URLs, and invalid descriptions are rejected before scanning. Additional metadata properties are retained but have no effect on discovery yet. JSON does not support comments.

The file includes 27 candidate repositories, including plugin/tool/specification repositories which may contain zero skills. No sources are searched outside the configured file. Listing a repository does not validate or endorse it. --source first selects an exact alias or configured full repository URL; otherwise it filters repository owner/name by substring. An exact alias takes precedence, so anthropic selects only that source, not anthropic-plugins. Install still takes individual skill URLs; alias-based installation is not implemented.

Legacy text files remain supported with --sources ./my-sources.txt: one repository URL per line, with blank lines and full-line # comments allowed. The default file is now skills-sources.json; projects using a text file must pass it explicitly.

# Explore one source first:
skillpack discovery --source anthropic
skillpack discovery --source microsoft --query azure
# Scan every configured source:
skillpack discovery
# Use another source file:
skillpack discovery --sources ./my-sources.json
# Machine-readable output:
skillpack discovery --source anthropic --format json

Discovery reads each repository's default-branch tree using GitHub's API and finds nested folders containing SKILL.md. It shows folder names, source repositories, and URLs compatible with the current installer. Search matches folder names/paths, not skill descriptions. It does not download/execute skill scripts, install files, or modify ownership state. Name/description validation remains separate future work.

To export a requirements file, only install after discovery succeeds:

skillpack discovery --source anthropic --query frontend --format requirements > discovered-skills.txt &&
  skillpack install -r discovered-skills.txt --agent codex

Diagnostics go to stderr. Source failures produce partial results and a nonzero exit code; do not treat the partial file as a complete catalog. Duplicate folder names prevent requirements export; narrow the source/query to resolve collisions. A source with no SKILL.md folders returns zero results. This PoC does not inspect submodules or support root-level SKILL.md packages.

Limits: 30 configured repositories, 30-second request timeout, and 16 MiB response cap. Truncated GitHub trees are reported as errors. GitHub API rate limits apply. When gh is installed, discovery uses gh api and its authenticated account (set up with gh auth login). Otherwise it uses Python HTTP requests; GH_TOKEN or GITHUB_TOKEN may be supplied for API authentication/private access. Git credential helpers alone do not authenticate the HTTP fallback. Tokens are not written to source files or state. Missing/inaccessible repositories are reported instead of silently removed from your list. Only URLs supported by the current install parser are emitted; unusual paths or default branches with slashes cause an explicit source error.

For another project, copy skills-sources.json into that directory or pass its absolute path with --sources. No separate source-management command is needed yet.

Arrow-key discovery browser

In a terminal, skillpack discovery automatically opens an interactive browser after scanning. Use ↑/↓ to move, Enter to view source/path/URL and an install command, Enter or i in the details view to choose an agent and install, b to return, and q, Esc, or Ctrl-C to quit. The list scrolls within the terminal height. Viewing alone installs nothing; installation begins only after pressing Enter/i in the details view and choosing an agent. Success or failure is shown in the browser, and existing skills are never overwritten.

skillpack discovery --source anthropic
skillpack discovery --source anthropic --interactive
skillpack discovery --source anthropic --no-interactive

Piped output, JSON, and requirements export remain noninteractive. --interactive requires a terminal and table output. Partial-source failures still return a nonzero status after browsing.

TODO

• Validaciones con regex // sanitization (sudo, rm)
• El uso privado puede ser lo más relevante (skills public no es tanto)