csk is a local skill manager for AI agent skills. It installs reusable skill packages from local git repositories into your project repositories with reproducible, content-hashed installs and multi-agent adapter support (Claude Code, Codex CLI, Cursor, Gemini).

The original MVP design lives in docs/mvp-design.md; later RFCs supersede parts of it.

Agent skills are useful, but managing them across many projects by hand falls apart fast: drift between machines, no version pinning, README files and tests leaking into the agent context, no cleanup when a skill is removed.

CocoaSkill makes per-project skill installation declarative and reproducible:

• One Skillfile.json per project, committed to version control.
• Pinned git refs (tag / branch / revision) and content-hashed installs.
• A whitelist-based stripped layout — README, tests, build files, and other non-skill content stay out of the agent's context.
• One canonical location (.agents/skills/) with per-agent adapter symlinks or copies into .claude/skills/, .codex/skills/, .cursor/rules/, .gemini/skills/.
• Skill-provided command shims exposed via a project-local .agents/bin/ directory on PATH.
• Optional global skills installed once under ~/.cocoaskills/global/ and exposed to supported agents outside any project checkout.

Pick whichever fits your machine. pipx is the recommended path on every platform.

pipx install cocoaskills

uv tool install cocoaskills

brew tap ivanopcode/csk
brew install cocoaskills

mise use -g pipx:cocoaskills@latest

curl -fsSL https://cocoaskills.org/install.sh | sh

The script detects Python, prefers pipx or uv tool, and falls back to pip install --user. Read it before piping if you do not trust the network.

python -m pip install --user cocoaskills

1. Pick or create a directory for skill git repositories. Example: ~/agents/skills/. Existing local skill repositories are read from this directory; missing repositories can be cloned automatically when a skill declaration provides git.

2. Bootstrap the global config:

   csk bootstrap

   This writes ~/.cocoaskills/config.json with your skills_root, preferred locale, and default agents.

3. Initialize CocoaSkill in each project:

   cd /path/to/project
   csk init

   This creates Skillfile.json and adds the CocoaSkill generated paths to .gitignore.

4. Declare which skills you want:

   {
     "schema_version": 1,
     "project": { "alias": "demo-ios" },
     "agents": ["claude_code", "codex_cli", "cursor"],
     "locale": "en",
     "skills": [
       {
         "name": "skill-tracker",
         "git": "git@gitlab.example.com:skills/skill-tracker.git",
         "tag": "v1.0.0"
       },
       {
         "name": "skill-metrics",
         "source": "internal/skill-metrics",
         "branch": "main"
       }
     ]
   }

   The optional locale field only affects skills that ship localized metadata (locales/metadata.json plus .skill_triggers/<locale>.md). Skills without localization files install unchanged. A skill that ships .skill_triggers/ must also ship locales/metadata.json covering the requested locale, otherwise the install of that skill fails.

5. Run csk install inside the checkout.

For multi-project sync, explicitly register projects with csk project add and run csk install --all or csk upgrade --all.

Global skills are user-wide baseline skills. They are installed under ~/.cocoaskills/global/ and linked into user-level agent directories such as ~/.claude/skills/ and ~/.codex/skills/.

csk global init
csk global add skill-metrics \
  --git git@gitlab.example.com:skills/skill-metrics.git \
  --tag v1.0.0
csk global install

Global commands are exposed through ~/.cocoaskills/global/bin. During csk global install, CocoaSkills also publishes forwarding shims into a safe user bin that is already on PATH, such as ~/.local/bin, so global commands work from any directory without per-project activation.

If no safe user bin is available, the install succeeds and prints a warning. In that case, add ~/.cocoaskills/global/bin to PATH, set CSK_GLOBAL_USER_BIN to a writable PATH directory, or install the shell hook:

eval "$(csk shell-init zsh)"

Inside a project, the shell hook still matters for project-local command shadowing: .agents/bin shims should come before global shims. Project-local skills with the same name shadow global skills. Global skills do not replace committed project Skillfile.json declarations.

Skills can declare commands and audit capabilities through csk-skill.json. Schema v2 supports multi-file runtimes: runtime_roots are copied into ~/.cocoaskills/runtime/<skill>/<commit>/ and excluded from agent prompt context. Schema v3 adds the capabilities envelope used by csk audit and strict install gates.

{
  "schema_version": 3,
  "runtime_roots": ["scripts"],
  "capabilities": {
    "network": ["gitlab.example.com"],
    "filesystem": "repo",
    "exec": ["review-cli"],
    "secrets": "none",
    "env_read": ["HOME"],
    "prompt_scope": "Review merge request metadata and produce local advice."
  },
  "commands": {
    "mr": {
      "type": "script",
      "unix_path": "scripts/mr"
    },
    "review-cli": {
      "type": "system",
      "command": "review-cli",
      "hint": "Install the review CLI through project bootstrap tooling"
    }
  }
}

system commands are only checked with shutil.which; CocoaSkills does not install system tools.

csk audit runs security checks against the same committed skill snapshot that csk install would use. Static detectors always run. Optional command and codex backends can add structured findings, but they do not decide whether a skill installs; the gate stays deterministic inside CocoaSkills.

csk audit
csk audit . --json
csk audit --global

Install gates are opt-in per command or through config:

csk install --audit
csk install --audit strict
csk global install --audit

Advisory audit prints warnings and continues. Strict audit blocks findings at or above the configured threshold. Schema v1/v2 skills do not declare capabilities; strict audit requires migrating them to schema v3 or pinning the content hash through the trust workflow when that workflow is enabled.

Backend safety rules:

• Local command backends receive raw skill files and are treated as trusted local tools.
• Local codex backends require oss=true and an explicit local_provider.
• Cloud backends require audit.allow_cloud=true and a public source policy match. File contents are redacted before they are sent to a cloud-capable backend.
• Unverifiable backend findings are shown in reports but cannot block strict installs.

Flags shared by install and upgrade:

• --dry-run — plan work without modifying files.
• --verbose — print resolved commits and installed command shims.
• --fix-gitignore — deprecated escape hatch; prefer csk init.
• --strict-tags — fail if a tag was locally moved to another commit.

Exit codes: 0 success, 1 one or more projects or skills failed, 2 configuration error, 3 lock contention.

Requires Python 3.11+.

git clone https://github.com/ivanopcode/cocoaskills.git
cd cocoaskills
python -m venv .venv
source .venv/bin/activate
python -m pip install -e ".[dev]"
pytest

Build artifacts locally:

python -m build
twine check dist/*

The runtime package is stdlib-only. Versioning is driven by setuptools-scm from git tags; the generated src/csk/_version.py is not committed.

• Skill authoring guide — practical contract for authoring CocoaSkills-compatible skill repositories, including csk-skill.json schema v3 capabilities, runtime_roots, system dependencies, audit behavior, and release checklist.
• Skill security audit RFC — design for schema v3 capabilities, deterministic audit gates, verdict cache, and future backend expansion.
• Audit LLM backends RFC — design for the command and codex audit backends, file-content redaction, timeout plumbing, and fail-open/fail-closed behavior.
• MVP design specification — v0.1 contract, partially superseded by the RFCs below covering manifests, refs, install pipeline, locking, adapters, security boundary, and test surface.
• CHANGELOG — release history in Keep a Changelog format.

Apache-2.0. See LICENSE.