Skip to content
BranchesTags

Repository files navigation

skills — agent skill manager

skills is a zero-dependency Go binary that installs agent skills from GitHub subdirectories. It replaces gh skill install with something that actually works.

State model

skills manages four layers of state — from declarative config to what is actually on disk:

flowchart LR
  subgraph Manifest["📄 .manifest.json"]
    M[Declared intent:<br/>which skills, where,<br/>from what source]
  end
  subgraph Lock["🔒 .lock.json"]
    L[Resolved versions:<br/>pinned commit per skill]
  end
  subgraph Disk["💾 disk"]
    D[Actual files:<br/>~/.agents/skills/<br/>~/.codex/skills/<br/>~/.claude/skills/]
  end
  subgraph Mirrors["🔗 mirrors"]
    MR[Derived symlinks:<br/>shared→claude<br/>shared→opencode]
  end

  Manifest -->|skills sync| Lock
  Lock -->|download| Disk
  Manifest -->|sync/update| Mirrors
  Disk -.->|verify| Mirrors

  style Manifest fill:#1a1a2e,stroke:#e94560
  style Lock fill:#16213e,stroke:#0f3460
  style Disk fill:#0f3460,stroke:#53d769
  style Mirrors fill:#533483,stroke:#e94560
Loading
Layer File / Dir Role
manifest .manifest.json 期望状态 — what you want
lock .lock.json 已解析版本 — what you pinned
disk ~/.agents/skills/, etc. 实际安装结果 — what you have
mirrors (manifest field) namespace 派生关系 — cross-agent sharing

Install

Homebrew（推荐）

brew install cagedbird043/tap/skills-cli

Go (if you have Go installed)

go install github.com/cagedbird043/skills@latest

curl

curl -sfL https://cagedbird.cn/skills/install.sh | sh

Build from source

git clone https://github.com/cagedbird043/skills.git
cd skills
make install

Quick start

# List all skills defined in the manifest
skills list

# Reconcile all skills to disk
skills sync

# Reconcile a single skill to disk
skills sync drawio

# Install OMP-only skill into the active profile's native user dir
skills add DietrichGebert/ponytail skills/ponytail --target omp

# Report manifest/lock/disk/mirror drift
skills doctor

# Show skill details
skills info drawio

Manifest format

Create a .manifest.json that declares directories, mirrors, and skills. A complete example lives at examples/manifest.json:

{
  "version": 1,
  "directories": [
    { "name": "shared",  "path": "~/.agents/skills" },
    { "name": "codex",   "path": "~/.codex/skills" },
    { "name": "claude",  "path": "~/.claude/skills" },
    { "name": "opencode","path": "~/.config/opencode/skills" }
  ],
  "mirrors": [
    { "from": "shared", "to": "claude" },
    { "from": "shared", "to": "opencode" }
  ],
  "skills": [
    {
      "name": "anysearch",
      "target": "shared",
      "source": {
        "repo": "cagedbird043/agent-skills",
        "ref": "main",
        "path": "skills/anysearch"
      }
    }
  ]
}

Run skills sync. A .lock.json will be created next to your manifest recording the exact commit of each installed skill.

Field Description
directories Named agent namespace directories (shared, codex, claude, opencode...)
mirrors Cross-namespace symlink derivation: shared → claude = auto-symlink shared skills into claude
skills[].name Skill name, must match the source directory name
skills[].target Which directory to install into. Usually matches a directories[].name; reserved target omp installs into the active OMP profile's native user skills dir.
skills[].source.repo GitHub repo in owner/repo format
skills[].source.ref Branch or tag to track
skills[].source.path Path within the repo to the skill directory

Commands

Command Description
skills list List all skills with installation status
skills sync [name] Reconcile manifest + lock to disk (zero API calls if locked)
skills install [name] Legacy alias for sync
skills update [name] Check remote commits, update changed skills
skills doctor Report active manifest path plus manifest/lock/disk/mirror drift
skills info <name> Show source, path, commit, and disk location
skills completion <shell> Generate shell completion (zsh, bash)

Options

Flag Description
-m, --manifest <path> Path to manifest file
-q, --quiet Suppress normal output, errors only
--version Print version

Environment

Variable Description
SKILLS_MANIFEST Default manifest path (alternative to --manifest)
NO_COLOR Set to any value to disable colored output

Shell completion

# zsh
skills completion zsh > ~/.local/share/zsh/site-functions/_skills
# then add to .zshrc:
#   fpath=(~/.local/share/zsh/site-functions $fpath)

# bash
skills completion bash > ~/.local/share/bash-completion/completions/skills

Agent-native Skills

Start here

Skills

  • manifest-governance: Triggered when managing, synchronizing, or diagnosing agent skills via manifest, lock, and mirror configurations.

Do not read everything

  • Agent MUST start by reading README.md and AGENTS.md. DO NOT scan the entire repository recursively.

About

˗ˏˋ skills ˎˊ˗ Agent skill manager — install, list, verify skills from GitHub subdirs. Zero-dependency Go binary.

github.com/cagedbird043/skills

Resources

Readme
Activity

Stars

1 star

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages