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.

In this section

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 with a file input 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 starts from the filesystem-backed skill layers implemented today, then applies the winning agent's skills/ directory as a final overlay when one effective agent is selected. Later rows override earlier rows when the same skill name is visible.

In short, bundled, marketplace, user, additional root, and workspace form the base stack, then Agent-local overlays on top. Agent-local is resolved from the winning AGENT.md directory only after AGH chooses the effective agent definition for that scope. It does not create a separate skill mode; it only overrides or augments the already-resolved base set.

Public surfaces

The operator and API surfaces resolve the same effective skill set:

• CLI: agh skill list|info|view|enable|disable --for-agent <name> [--workspace <ref>]
• HTTP/UDS: GET /api/skills?for_agent=<name>&workspace=<path-or-id>
• HTTP/UDS detail/content/mutate: the same optional for_agent and workspace query parameters apply to GET /api/skills/{name}, GET /api/skills/{name}/content, POST /api/skills/{name}/enable, and POST /api/skills/{name}/disable

If for_agent is omitted, AGH returns the base effective set for the selected global or workspace resolution context. If for_agent is present, AGH overlays the winning agent's skills/ tree and applies that agent's logical skills.disabled tombstones before returning the result.

Enabled extensions can also register runtime-owned skills into the live registry. Those overlays are not filesystem-backed, so they are documented as runtime registry behavior rather than as one more scan root.

Provenance And Shadow Audit

Every skill list/detail payload includes provenance.precedence_tier, which is the resolver tier that won for that skill: bundled, marketplace, user, additional, workspace, or agent_local. Marketplace metadata remains in slug, registry, version, and installed_at. Skills supplied by higher-level runtime packages can also carry installed_from_bundle or installed_from_extension so operators can trace the owning bundle or extension.

When more than one declaration uses the same skill name, AGH keeps the normal precedence order and records the losing declarations in provenance.shadowed_by. The full resolver view is available through the same operator and agent-manageable surfaces:

The shadows response lists the winner first and marks it with resolved_to_winner: true. Lower-precedence declarations remain visible with resolved_to_winner: false. AGH also writes a canonical skill.shadowed event whenever resolver reconciliation detects a shadow relationship, including daemon boot, workspace resolution, agent-local overlays, and extension/resource updates.

Resolution Flow

The daemon boot path is responsible for the global registry:

1. Load bundled skills.
2. Load global AGH skills from $AGH_HOME/skills/.
3. Start the global watcher when skills.enabled is true.

The session start path is workspace-aware:

1. Resolve the workspace snapshot.
2. Discover <workspace>/.agh/skills/ and any registered additional roots.
3. Overlay workspace-visible skills over the global registry.
4. Resolve the winning AGENT.md and, if it has a skills/ directory, overlay those skills last.
5. Apply agent-scoped logical tombstones from AGENT.md skills.disabled.
6. Build the prompt catalog from enabled skills.
7. Resolve MCP servers declared by active skills.

Prompt Injection

The prompt catalog has this shape:

<available-skills>
  <skill name="agh">Operate and extend AGH, the local-first agent operating system...</skill>
</available-skills>

Use `agh__skill_view` with `{ "name": "agh" }` 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` with `{ "name": "agh", "file": "references/network.md" }`
(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.

Runtime prompts do not repeat the full current-skill catalog after every turn when the resolved catalog is unchanged for the session. The first prompt, and any later catalog change, carries the full <current-available-skills> block; repeated turns carry a compact unchanged marker that keeps the previous block authoritative and points agents back to agh__skill_view for full instructions.

Important details:

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:

1. metadata.agh.mcp_servers inside SKILL.md.
2. 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:

1. top-level config MCP servers
2. provider MCP servers
3. agent MCP servers
4. 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

Related Pages

• SKILL.md Format documents the file format and schema.
• Marketplace shows how to search, install, update, and remove skills.
• Bundled Skill documents the agh skill 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.