Skills Overview

Skills are reusable instruction sets for AGH agents. A skill is a directory with a SKILL.md file, optional resource files, and optional MCP sidecar configuration. AGH loads skill metadata at runtime, injects a compact catalog into the startup prompt, and lets the agent read the full skill only when it needs it.

Hand-drawn Skills poster showing skill discovery, precedence, prompt catalogs, MCP sidecars, and on-demand instruction loading with the octopus mascot.

In this section

Format

SKILL.md schema and authoring

Use this page for the YAML frontmatter, body conventions, MCP sidecars, and skill-local resource files.

Authoring

Marketplace

Discover and install community skills

Use this page to install, update, and remove ClawHub-sourced skills with `agh skill`.

Distribution

Bundled

Skills shipped in the AGH binary

Use this page when you need the names, scope, and triggers of skills that ship with AGH.

Built-in

What a Skill Contains

<scope>/skills/refactor-checklist/
  SKILL.md
  mcp.json
  references/
    review-template.md

SKILL.md has YAML frontmatter followed by Markdown instructions. The frontmatter gives AGH the skill name, description, version, and optional AGH-specific metadata. The Markdown body is procedural guidance for the agent. Resource files stay next to the skill and are read on demand with agh__skill_view --file <path> from inside a session, or with agh skill view <name> --file <path> from the operator CLI.

The runtime does not keep full skill bodies in list/detail payloads. This keeps prompts, APIs, and the web UI lightweight while preserving the full instruction set for explicit reads.

Source Hierarchy

AGH uses the AgentSkills hierarchy, then expands it with the runtime sources implemented today. Later rows override earlier rows when the same skill name is visible.

Precedence	Source	Directory or owner	Notes
1	Bundled	compiled into the binary from `internal/skills/bundled/skills/*/SKILL.md`	Lowest precedence. Always available when skills are enabled.
2	Marketplace	`~/.agh/skills/<name>` with `.agh-meta.json`	Installed by `agh skill install`. Load-time hash verification must pass.
3	User	`~/.agh/skills/<name>` and `~/.agents/skills/<name>`	Local operator-controlled global skills.
4	Runtime registered	extension-owned skills registered into the running registry	Used by enabled extensions. These overlay global skills while registered.
5	Additional root	`<additional-dir>/.agh/skills/<name>`	Visible to workspaces that registered additional roots.
6	Workspace	`<workspace>/.agh/skills/<name>`	Highest filesystem precedence for that workspace.

The short form is bundled -> global -> workspace -> session-specific runtime context. In the current codebase, direct session-level SKILL.md paths are not a public authoring surface. Session-specific behavior exists when AGH appends the bundled agh-network skill body to prompts for sessions that join an AGH Network channel.

Resolution Flow

Rendering diagram...

AGH loads global skills at boot, resolves workspace skills per session, appends only a compact catalog to the prompt, and resolves MCP servers for startup.

The daemon boot path is responsible for the global registry:

Load bundled skills.
Load global AGH skills from ~/.agh/skills/.
Load the user AgentSkills convention from ~/.agents/skills/.
Start the global watcher when skills.enabled is true.

The session start path is workspace-aware:

Resolve the workspace snapshot.
Discover <workspace>/.agh/skills/ and any registered additional roots.
Overlay workspace-visible skills over the global registry.
Build the prompt catalog from enabled skills.
Resolve MCP servers declared by active skills.

Prompt Injection

The prompt catalog has this shape:

<available-skills>
  <skill name="agh-session-guide">Operate AGH sessions from the CLI...</skill>
</available-skills>

Use `agh__skill_view <name>` to load full instructions for any skill, or
`agh skill view <name>` from the operator CLI when the tool path is unavailable.
Use `agh__skill_view <name> --file <path>` (or `agh skill view <name> --file <path>`) to read a
specific skill resource file.

When the runtime denies agh__skill_view for the active scope, agents fall back to agh skill view. The conditional guidance is part of the rendered catalog so the prompt never advertises a CLI fallback when the dedicated tool is callable.

Important details:

Behavior	Current implementation
Full body in prompt	Not injected by the catalog. The body is read on demand.
Description length	Descriptions are truncated to 200 runes in the prompt catalog.
Disabled skills	Omitted from the catalog.
Catalog order	Sorted by skill name after resolution.
Prompt position	Memory context is prepended, the `AGENT.md` prompt stays in the middle, and the skill catalog is appended.
Network sessions	Sessions with a network channel also receive the full bundled `agh-network` body.

Disabled skills are hidden from the prompt catalog. Current MCP and hook resolution still iterates the resolved skill list, so do not treat disabling a skill as a complete runtime kill switch for MCP or hooks.

MCP Relationship

Skills can declare MCP servers in two places:

metadata.agh.mcp_servers inside SKILL.md.
A skill-local mcp.json sidecar next to SKILL.md.

The sidecar accepts either mcpServers or mcp_servers. Server names are map keys in the sidecar, and the sidecar replaces same-name frontmatter servers.

At session start, AGH merges MCP servers in this order:

top-level config MCP servers
provider MCP servers
agent MCP servers
skill MCP servers

Marketplace skill MCP servers are blocked unless skills.allowed_marketplace_mcp contains one of the skill's consent keys: the marketplace slug, registry:slug, or the installed hash.

[skills]
allowed_marketplace_mcp = ["@author/postgres-tools"]

[skills.marketplace]
registry = "clawhub"

There is no interactive MCP consent prompt today. Consent is a static config allowlist.

Reload And Failure Behavior

Case	Behavior
`skills.enabled = false`	The registry, catalog provider, skill MCP resolver, watcher, and skill hooks are not wired.
Global skill edit	The watcher refreshes global skills on `skills.poll_interval`, default `3s`.
Workspace skill edit	Workspace skill cache uses file snapshots and is rechecked when a workspace is resolved. Cache entries expire after 10 minutes.
Missing global directory	Treated as empty.
Scan depth	AGH looks for `SKILL.md` files up to depth 4 under each scanned directory.
Scan limit	Each scanned directory is capped at 300 `SKILL.md` candidates.
Critical verification finding	The skill is blocked from loading.
Marketplace hash mismatch	The marketplace skill is blocked from loading.

SKILL.md Format documents the file format and schema.
Marketplace shows how to search, install, update, and remove skills.
Bundled Skills lists the skills shipped in the AGH binary.
Agent Definitions explains how agents and skill-aware MCP servers meet at session start.
Spawning follows the ACP startup path that receives skill MCP servers.

On this page