Skills Guide

Skills are reusable local workflows. A skill is rooted at a SKILL.md file and describes a repeatable task pattern that an agent can load when needed.

What a Skill Is

A skill typically contains:

Purpose — What task the skill helps with
Workflow — Step-by-step guidance for the agent
Boundaries — What the skill should and should not do
References — Related files or commands to inspect

Skills are not automatically active. The runtime exposes a catalog of available skills, and the agent opens the relevant SKILL.md only when a matching task appears.

Location

Repository-local skills commonly live under:

.codex/skills/<skill-name>/SKILL.md
skills/<skill-name>/SKILL.md

Example skills in this repository include:

ghx
github-issue-solve
github-pr-fix
github-review

How Agents Use Skills

The runtime exposes a skills catalog with name, description, and path
The agent chooses a skill only if it matches the current task
The agent reads the skill's SKILL.md
The agent follows the workflow with normal tool calls

This keeps skills explicit and avoids loading irrelevant guidance.

Managing skills with the CLI

Holon separates skill management into two layers:

Skill Library — A global catalog of known skills managed with holon skills add/remove/check/reconcile/catalog. Think of it as your local skill registry.
Agent Skills — Per-agent enablement managed with holon skills enable/disable/list. A skill must exist in the library before it can be enabled for an agent.

Skill Library (global)

The Skill Library is your local catalog of skills. Manage it with:

List the library catalog

holon skills catalog

Shows all skills registered in the local Skill Library.

Add a skill to the library

# Add from a local directory or SKILL.md file
holon skills add /path/to/skill-dir

# Add from a remote source
holon skills add https://github.com/user/repo/tree/main/skills/my-skill --remote

# Copy the skill into the user directory instead of referencing it
holon skills add /path/to/skill --copy

Remove a skill from the library

holon skills remove my-skill

Check library consistency

# Check all library entries against .skill-lock.json
holon skills check

# Check a specific skill
holon skills check my-skill

Note: Installing an already-installed global skill is idempotent — holon skills add skips the install and reports the existing entry without error. This is safe to repeat in scripts and automation.

Reconcile library with lock file

# Reconcile all library entries
holon skills reconcile

# Reconcile a specific skill
holon skills reconcile my-skill

Update skills from remote sources

holon skills update

Fetches remote skill sources and compares against the lock file (.skill-lock.json). Skills that have changed upstream are downloaded and updated. The update preserves the npx skills v3 lock format (source, subdir, mode, etag) for interoperability.

Agent Skills (per-agent)

Once a skill is in the library, enable it for a specific agent:

List enabled skills for an agent

# List for the default agent
holon skills list

# List for a specific agent
holon skills list --agent reviewer

Shows all skills currently enabled for the agent, including their name, scope (agent, workspace, or user), and source.

Enable a skill for an agent

# Enable for the default agent
holon skills enable my-skill

# Enable for a specific agent
holon skills enable my-skill --agent reviewer

# Enable and copy into the agent home
holon skills enable my-skill --copy

Disable a skill for an agent

# Disable for the default agent
holon skills disable my-skill

# Disable for a specific agent
holon skills disable my-skill --agent reviewer

Compatibility aliases: holon skills install and holon skills uninstall are still accepted but map to the new add/enable and remove/disable model. Prefer the new commands for clarity.

Skill `uses` shorthand

When adding a GitHub-hosted skill, you can use the uses shorthand syntax instead of the repository URL:

# Full URL form
holon skills add https://github.com/holon-run/holon/tree/main/skills/ghx --remote

# uses shorthand — same result
holon skills add holon-run/holon/skills/ghx@main

The uses form (owner/repo/path@ref) is normalized to the full GitHub URL internally. It also accepts owner/repo/path#ref as a compatible input.

Skill source types

Source	Flag	Example
Local path	(default)	`holon skills add ./skills/my-skill`
Remote URL	`--remote`	`holon skills add https://... --remote`

Command summary

Layer	Command	Purpose
Library	`holon skills catalog`	List library catalog
Library	`holon skills update`	Fetch and update skills from remote sources
Library	`holon skills refresh`	Refresh runtime catalog by rescanning local roots
Library	`holon skills add <source>`	Add a skill to the library
Library	`holon skills remove <name>`	Remove from the library
Library	`holon skills check [name]`	Check lock-file consistency
Library	`holon skills reconcile [name]`	Reconcile with lock file
Agent	`holon skills list [--agent]`	List enabled skills
Agent	`holon skills enable <name>`	Enable for an agent
Agent	`holon skills disable <name>`	Disable for an agent

Note: The --builtin flag and kind = "builtin" in template manifests have been removed in v0.26.0. Official Holon skills are referenced the same way as any other GitHub-hosted skill.

Managing skills via HTTP

The HTTP control plane separates library and agent operations:

Library endpoints

Method	Path	Purpose
`GET`	`/api/skills/catalog`	List library catalog
`GET`	`/api/skills/catalog/{skill_id}`	Get skill detail
`POST`	`/api/skills/catalog/add`	Add a skill to the library
`POST`	`/api/skills/catalog/refresh`	Refresh runtime catalog
`POST`	`/api/skills/catalog/remove`	Remove from the library
`POST`	`/api/skills/catalog/reconcile`	Reconcile with lock file
`POST`	`/api/skills/catalog/check`	Check consistency
`POST`	`/api/skills/_update`	Update skills from remote sources

Agent endpoints

Method	Path	Purpose
`GET`	`/agents/:agent_id/skills`	List agent skills
`POST`	`/control/agents/:agent_id/skills/enable`	Enable for agent
`POST`	`/control/agents/:agent_id/skills/disable`	Disable for agent

Deprecated: POST /api/control/agents/:agent_id/skills/install and POST /api/control/agents/:agent_id/skills/uninstall remain for compatibility but are superseded by enable/disable and add/remove.

Non-blocking install jobs

When a skill is installed through the HTTP API (e.g., from the Web GUI), the install runs as a background job instead of blocking the request. Job progress is available at GET /api/jobs/{job_id} and persists across page reloads via localStorage.

TUI integration

The Terminal UI provides skill management alongside the CLI:

Slash commands — Type /skills to view agent skills, /skill-catalog to browse the library, /skill-add <source> to add to the library, /skill-remove <name> to remove, and /skill-enable <name> / /skill-disable <name> to manage agent enablement directly from the chat input.
Skill name completion — The TUI auto-completes skill names when using slash commands.
Agent status sidebar — The agent detail view under "Skills" shows all discoverable skills with their scope (agent, workspace, user).

These TUI features let you manage skills without leaving the interactive session.

Writing a Good Skill

Keep skills:

Small — Focus on one workflow
Actionable — Give concrete steps the agent can execute
Scoped — Avoid broad project-overriding instructions
Durable — Encode reusable behavior, not one-off task notes

Good skill topics:

GitHub issue solving
PR review workflow
Release checklist
Incident triage
Project-specific test/debug loop

Poor skill topics:

Temporary meeting notes
One-off task plans
Large copied documentation dumps

Relationship to AGENTS.md

Use:

AGENTS.md for durable role, authority, and local conventions
Skills for reusable workflows
Work items for current tracked objectives

These are different layers:

Surface	Purpose
`AGENTS.md`	Standing instructions and boundaries
`SKILL.md`	Reusable workflow for a type of task
Work item	Current objective and progress