SKILL.md

SKILL.md is the portable skill file AGH loads into the skill catalog. A skill directory contains the file, optional supporting resources, and optional sidecars:

<skill-name>/
  SKILL.md
  mcp.json
  resources/

AGH reads standard YAML frontmatter, then keeps the Markdown body available as procedural instructions for agents.

Quick Reference

Complete Annotated Example

---
# Required. Used as the skill catalog key.
name: docs-search

# Optional by parser, but missing descriptions log a warning.
description: Search repository documentation and return file-backed answers.

# Optional metadata.
version: "1.0.0"

metadata:
  agh:
    # Optional. Merged into session MCP servers when the skill is active.
    mcp_servers:
      - name: docs-files
        command: npx
        args: ["-y", "@modelcontextprotocol/server-filesystem", "."]
        env:
          LOG_LEVEL: "info"

    # Optional. Declares hooks owned by this skill.
    hooks:
      - event: session.post_create
        command: printf
        args: ["docs-search loaded\n"]
        mode: async
        timeout: 5s
---

# Docs Search

Use this skill when the user asks for an answer that must be grounded in repository docs.

## Workflow

1. Search the relevant docs before answering.
2. Prefer current source and active task documents over archived notes.
3. Cite the file path that supports each factual claim.

## Verification

Return the exact file paths you used and call out any stale or conflicting source.

Top-Level Frontmatter

Unknown top-level fields such as allowed-tools, user-invocable, and argument-hint are tolerated with warnings but ignored by the current AGH runtime. Do not use those fields for access control, invocation behavior, or permissions in AGH.

metadata.agh

AGH-specific runtime features are namespaced under metadata.agh so the file remains compatible with other AgentSkills readers.

Malformed metadata.agh values warn and are ignored when possible. Invalid hook declarations fail skill parsing because hooks must be safe to register.

metadata.agh.mcp_servers

Skill MCP behavior depends on skill source:

When multiple active skills declare the same trimmed server name, the later skill in source precedence replaces the earlier skill's server. The resolved skill MCP list is then merged into the session MCP list after config, provider, and agent MCP servers.

metadata.agh.hooks

Supported matcher fields are agent_name, agent_type, workspace_id, workspace_root, session_type, input_class, acp_event_type, turn_id, tool_name, tool_namespace, tool_read_only, decision_class, message_role, message_delta_type, compaction_reason, and compaction_strategy.

Marketplace skill hooks are trust-gated by [skills].allowed_marketplace_hooks, using the same slug, registry:slug, or hash forms as marketplace MCP trust.

Hook Event Names

Use current dot-form event names:

session.pre_create
session.post_create
session.pre_resume
session.post_resume
session.pre_stop
session.post_stop
input.pre_submit
prompt.post_assemble
event.pre_record
event.post_record
automation.job.pre_fire
automation.job.post_fire
automation.trigger.pre_fire
automation.trigger.post_fire
automation.run.completed
automation.run.failed
agent.pre_start
agent.spawned
agent.crashed
agent.stopped
turn.start
turn.end
message.start
message.delta
message.end
tool.pre_call
tool.post_call
tool.post_error
permission.request
permission.resolved
permission.denied
context.pre_compact
context.post_compact

Markdown Body

The body after frontmatter is the procedural instruction payload. The parser accepts an empty body, but an empty skill does not provide useful instructions.

Useful skill bodies usually contain:

AGH scans skill content for critical prompt-injection, destructive command, and credential extraction patterns. Critical warnings block the skill from loading. Warning-level findings are logged. Content over 50,000 characters produces an info warning.

MCP Sidecar

Place mcp.json next to SKILL.md when MCP configuration is generated or easier to maintain as JSON:

<workspace>/.agh/skills/workspace-files/
  SKILL.md
  mcp.json

{
  "mcpServers": {
    "workspace-files": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "."],
      "env": {
        "LOG_LEVEL": "info"
      }
    }
  }
}

If frontmatter and sidecar JSON declare the same server name, the sidecar replaces the whole frontmatter server object. See mcp.json for the shared JSON schema.

Skill-local sidecars are loaded only when they resolve inside the skill directory. AGH rejects SKILL.md, mcp.json, and hashed resource paths that escape the approved skill root through symlinks.

Marketplace Provenance Sidecar

Marketplace-installed skills include .agh-meta.json next to SKILL.md. Users normally do not author this file.

{
  "hash": "sha256-directory-hash",
  "registry": "clawhub",
  "slug": "@team/docs-search",
  "version": "1.0.0",
  "installed_at": "2026-04-16T12:00:00Z"
}

All fields are required. AGH recomputes the installed directory hash, excluding .agh-meta.json, and blocks marketplace skills whose stored hash does not match.

Discovery Limits

Higher-precedence skills with the same name override lower-precedence skills.

Live runtime-registered skills from enabled extensions are an additional overlay layer, but they are not discovered from scan roots. Use Skills Overview for the full active-registry precedence model.

RFC 002 Drift

Related Pages

• config.toml documents skill marketplace trust gates.
• mcp.json documents sidecar validation and replacement.
• Skills Overview explains catalog source precedence.