Pack Knowledge into Reusable Units with Harness Skills – A Deep Dive into the Skill System

What is a Skill?

Skill is a directory containing a SKILL.md file that defines reusable instruction units for the main Agent. The file consists of a YAML front‑matter block (metadata) and a markdown body that holds the actual commands or knowledge.

my-skill/
├── SKILL.md          # required overview
├── reference.md     # detailed API docs (loaded on demand)
├── examples.md      # usage examples (loaded on demand)
└── scripts/
    └── helper.py    # utility script – executed, not loaded

Reference vs Action Skills

Anthropic defines two Skill types:

Reference Skill – provides knowledge that is available throughout the session (e.g., API style guide). It is loaded at session start; the body is fetched only when the Skill is invoked.

Action Skill – performs a one‑off task such as deployment or PR summarisation. It is triggered explicitly and runs in its own sub‑agent context.

The decision rule is whether the instruction should be “always remembered by the model” (Reference) or “executed only when the user asks for it” (Action). For Action Skills the field disable-model-invocation: true locks the description out of the main context.

Dynamic Context Injection

The body can contain lines that start with !shell‑command. Before the Skill is sent to the model, Harness executes the command, captures its output, and substitutes the line with that output. This “pre‑rendering” step decouples data retrieval from model reasoning. !git diff HEAD When a PR‑summary Skill is called, Harness runs the three gh commands, inserts their outputs into the markdown template, and then feeds the completed prompt to the model.

Front‑matter Fields

Key fields control visibility and execution: description – short purpose text; always present in the main context unless disable-model-invocation: true. name – optional explicit name (defaults to directory name). disable-model-invocation – when true, the description is hidden from the model until the user explicitly invokes the Skill. user-invocable – when false, only the model can call the Skill. context: fork – runs the Skill body inside a separate sub‑agent window. agent – selects the sub‑agent type (Explore, Plan, etc.). allowed-tools – whitelist of tools the Skill may use (e.g., Bash(gh *)). argument-hint – provides a hint for slash‑command arguments.

Loading Timing

By default a Reference Skill’s description lives in the main context, while its body is loaded only when needed. Setting disable-model-invocation: true removes the description from the context, making the Skill invisible to the model until the user calls it with /skill-name.

Practical Examples

PR‑summary Skill – defined with name: pr-summary, it runs gh pr diff, gh pr view --comments, and gh pr diff --name-only, then asks the model to summarise the changes and list risks.

Pre‑commit Skill – placed in ~/.claude/skills/precommit, it executes !git diff --staged and !git diff --staged --name-only, then asks the model to report code quality, security issues, test coverage, and style violations.

Design Principles

The SKILL.md file acts as a navigation page, pointing to reference.md, examples.md, and scripts/. This progressive‑disclosure pattern keeps the main context lightweight while still giving the model access to rich, on‑demand knowledge.

Key Takeaways

Skill = reusable instruction package (directory + SKILL.md).

Reference Skills inject knowledge; Action Skills perform isolated tasks.

Dynamic !command injection runs before the model sees the prompt.

Front‑matter flags control when and who can invoke a Skill.

Combining context: fork with an agent lets a Skill run as a Subagent.