skill command
graft skill manages the canonical skills store and the per-provider symlinks that make skills available to supporting tools (Claude Code, OpenCode, and Codex).
Command summary
| Command | Does | Output |
|---|---|---|
graft skill list | List canonical skills in .agents/skills. | Table. |
graft skill status | Show per-provider link state for each canonical skill. | Table. |
graft skill install <name|path> | Copy a skill into .agents/skills (if absent) and symlink it into supporting providers. | Table. |
graft skill sync | Re-apply: symlink all canonical skills into all supporting providers. | Table. |
All commands route through the EntryGate only.
graft skill list
Lists the canonical skills present in .agents/skills. A directory is a skill only when it contains a SKILL.md marker file; directories without the marker are ignored.
graft skill list
Output columns: name, dir (absolute path to the canonical skill directory).
Flags:
| Flag | Type | Default | Description |
|---|---|---|---|
-o, --output | string | table | Output format: json, yaml, or table. |
graft skill status
Reports the live filesystem link state of every canonical skill for every supporting provider. State is always computed live (lstat/readlink) — not from a database.
graft skill status
graft skill status --provider claude-code
Output columns: skill, provider, state, link_path.
Link states:
| State | Meaning |
|---|---|
linked | Symlink points at the canonical skill dir. All good. |
missing | No entry at the provider path. Run graft skill sync to fix. |
wrong-link | A symlink exists but points elsewhere. Run graft skill sync to fix. |
conflict | A real (non-symlink) dir or file is present. Use --override to replace it. |
Flags:
| Flag | Type | Default | Description |
|---|---|---|---|
--override | bool | false | Replace a non-symlink entry with a symlink. |
-p, --provider | string | — | Limit output to a single supporting provider. |
--yes / --install | bool | false | Non-interactive: auto-install missing referenced skills. |
-o, --output | string | table | Output format: json, yaml, or table. |
graft skill install <name|path>
Copies a skill into the canonical store at .agents/skills/<name>/ (if it is not already present), then symlinks it into every supporting provider's skills directory. The argument can be:
- A filesystem path to a skill directory that contains
SKILL.md(absolute or relative, starting with/,., or~, or containing a path separator). - A bare skill name already present in the canonical store — no copy-in is performed; Apply runs directly.
- A bare skill name found in a supporting provider's project skills directory — copied from there into the canonical store, then symlinked everywhere.
- A bare skill name found in any home-scope directory (e.g.
~/.claude/skills,~/.codex/skills,~/.agents/skills,~/.config/opencode/skills) — copied into the canonical store.
Install is idempotent: if the named skill already exists canonically, it is not overwritten.
graft skill install my-skill
graft skill install ./tools/my-skill
graft skill install /path/to/my-skill
graft skill install my-skill --provider claude-code
graft skill install my-skill --override
Flags:
| Flag | Type | Default | Description |
|---|---|---|---|
--override | bool | false | Replace a non-symlink entry at the provider path with a symlink. |
-p, --provider | string | — | Limit symlinking to a single supporting provider. |
--yes / --install | bool | false | Non-interactive: auto-install without prompting. --install is an alias for --yes. |
-o, --output | string | table | Output format: json, yaml, or table. |
graft skill sync
Re-applies all canonical skills: iterates every skill in .agents/skills and every supporting provider, creating or correcting the symlink at each provider's skills directory. This is the idempotent reconciliation pass.
graft skill sync
graft skill sync --provider claude-code
graft skill sync --override
Use graft skill sync after manually adding a skill directory to .agents/skills, or to repair missing / wrong-link states without running a full agent sync.
Flags:
| Flag | Type | Default | Description |
|---|---|---|---|
--override | bool | false | Replace a non-symlink entry with a symlink. |
-p, --provider | string | — | Limit to a single supporting provider. |
--yes / --install | bool | false | Non-interactive: auto-install missing referenced skills. |
-o, --output | string | table | Output format: json, yaml, or table. |
Config keys
The skills.* keys control the automatic skill apply hook that runs after graft init and graft sync agents.
| Key | Type | Default | Description |
|---|---|---|---|
skills.enabled | bool | true | Master switch for the init/sync hook. When false, the hook is disabled and skills are never applied automatically. |
skills.autoInstall | bool | false | When true, the hook installs missing referenced skills without prompting (equivalent to --yes). |
skills.providers[] | string[] | — | Restrict the hook to these supporting provider ids. Empty = all supporting providers. |
Read or write config with graft config get / graft config set. See Config reference.
Init/sync hook
graft init and graft sync agents automatically run a skill apply pass after success when skills.enabled is true. The hook:
- Runs
Applyacross all supporting providers (or those listed inskills.providers[]). - Respects
skills.autoInstallas the--yesequivalent. - Swallows all errors and logs them to stderr — a skill problem never fails an agent operation.
- Returns the resulting link states as part of the command summary.
To opt out entirely, set skills.enabled = false.
Legacy migration
The first time any graft skill command runs, graft checks for a legacy .agent/skills directory (singular) and migrates its contents into .agents/skills (plural). The migration is idempotent; skills already present canonically are not overwritten. The legacy directory is removed once it is empty.