Agent Skills and Harnesses: A Practitioner Guide

Agent skills and harnesses are the two main ways teams shape a coding agent without changing the model. A skill is a folder of markdown instructions (and optionally files and scripts) that the agent loads when relevant. A harness is the configuration around the model loop: hooks, slash commands, sub-agents, permissions and rules.

This guide covers four projects as examples: Superpowers and mattpocock/skills (skills and methodology), ECC (a large harness configuration) and Context Mode (a context tool). Capabilities are as stated in each README on 17 October 2026. We have not benchmarked them, and you should not take any vendor figure as a result you will see.

• Inconsistency. The same prompt produces different workflows on different days or for different engineers.
• Repeated instructions. Teams paste the same conventions into every session.
• Context pressure. Long instructions and verbose tool output crowd out the task.
• No guardrails by default. An agent with shell access needs policy enforced by something other than the model's good behaviour.

Skills and harness configuration move that behaviour into files you can review, version and test.

Skills are markdown instructions loaded on demand. In Claude Code's convention a skill is a directory containing a SKILL.md file whose frontmatter has a name and a description. The client keeps the short descriptions available to the model and loads the full body only when a skill is judged relevant or invoked, so many skills can exist without all being in context. Other clients document similar conventions; check yours.

The harness is everything around the model loop: the system prompt and project instruction file (for example CLAUDE.md or AGENTS.md), permission rules, slash commands, sub-agents with their own context, and hooks. A hook is a command the client runs on an event such as before or after a tool call. Hooks are deterministic: unlike an instruction, the model cannot decide to skip them.

Typical flow: the user prompt arrives; the client assembles system prompt, instruction file and skill descriptions; the model chooses to load a skill or call a tool; hooks fire around tool calls; results return to the context. Every step that adds text costs tokens on every subsequent turn until the context is compacted or cleared.

Prerequisites: a supported agent client, a git repository to work in, and a sandbox or throwaway checkout for first trials. Installation differs per project and client and changes between releases, so use each README rather than commands copied from a third party:

• Superpowers: README lists install steps per client, plus an update section.
• mattpocock/skills: README describes the skills and how to adopt them.
• ECC: README describes installing selected components; prefer a subset.
• Context Mode: README states a minimum Claude Code version and a plugin or manual setup.

Before you install anything: read it, pin a tag or commit, and note what it will write to your home directory or repository. See the vetting checklist on the Agent Stack page.

The generic structure of a project-level skill looks like this:

.claude/skills/release-notes/
├── SKILL.md                    # frontmatter + instructions (always small)
├── templates/
│   └── changelog-entry.md      # loaded only when the skill asks for it
└── scripts/
    └── list-merged.sh          # optional helper; review it like any script

Writing one small skill teaches more than installing a large pack. We will create a release-notes skill.

1. Pick a task you do repeatedly and can check (release notes qualify: the output can be compared to the git log).
2. Create a directory for the skill in your client's skills location and add SKILL.md.
3. Write a description that says what the skill does and when to use it. The description is how the model decides to load it, so be specific.
4. Write numbered steps, rules and an output format. Keep it short; move reference material into separate files loaded only when needed.
5. Test it on three past releases where you know the right answer. Fix the instructions where the output differs.
6. Commit it. Review changes to it in pull requests.

---
name: release-notes
description: Draft release notes from merged changes since the last tag. Use when the user asks for release notes, a changelog entry, or a summary of what shipped.
---

# Release notes

## When to use
The user asks for release notes or a changelog entry for a version or date range.

## Steps
1. Find the previous release tag with `git describe --tags --abbrev=0`.
2. List merged changes since that tag with `git log <tag>..HEAD --merges --oneline`.
3. Group changes: Added, Changed, Fixed, Security, Internal.
4. Write one line per change in the user's voice: what changed for the reader, not how.
5. Flag anything that looks breaking. Do not guess; list it under "Needs confirmation".

## Rules
- Only use information from the git history and linked pull requests. Do not invent features.
- Do not run commands that modify the repository.
- Output Markdown only, matching the format in templates/changelog-entry.md.

## Output
A Markdown section headed with the version and today's date, followed by grouped bullet lists.

Notes on the design: the description names triggering phrases; the steps use read-only git commands; the rules forbid invention and mutation; the output is specified. A helper script is optional, and if you add one it is code you now maintain and must secure.

For comparison, the shape of a hook configuration (keys vary by client):

// Shape of a hook configuration (illustrative; check your client's docs for exact keys)
{
  "hooks": {
    "PreToolUse": [
      { "matcher": "Bash", "hooks": [ { "type": "command", "command": "./scripts/check-command.sh" } ] }
    ]
  }
}
// The command runs as your user, on your machine, each time the event fires.

A good small skill produces consistent structure, fewer follow-up corrections and less repeated prompting. It does not make the model more capable. A larger methodology such as Superpowers aims to change the workflow (for example planning before coding); whether that improves outcomes on your tasks is an empirical question. Do not expect the same effect across models, languages or codebase sizes. Use the measurement lab to find out.

• Instruction files: keep global rules in CLAUDE.md or AGENTS.md; keep task procedures in skills.
• MCP servers: a skill can describe when and how to use a server's tools; the server provides the capability.
• CI: run the same tasks headlessly in CI to catch regressions when skills or models change.
• Observability: log token usage and tool calls per run (see add observability).
• Context tools: Context Mode and similar tools address input size; skills address behaviour. They interact, so test them together.

• Versioning. Keep team skills in git. Pin third-party packs to a tag or commit. Record the model version used in your evaluations.
• Team rollout. Start with one or two engineers on one repository. Compare against a baseline before wider adoption. Document how to turn each skill off.
• Drift. Model updates change how skills are interpreted; upstream packs change under you. Re-run your task set after each model or pack update.
• Ownership. Give each skill an owner and review date. Delete skills nobody uses.
• Budgeting. Set per-session token and spend caps (see production agent pattern).

• Prompt injection via skills. A skill is trusted instruction. A compromised or careless one can tell the agent to exfiltrate files, disable checks or run commands. Content the agent reads (issues, web pages, dependencies) can also carry injected instructions; see prompt injection via RAG.
• Hooks run shell. They fire on events, as your user. A malicious or buggy hook can read or alter anything you can.
• Visibility. Tools like Context Mode that sit on tool output see everything the agent reads, including secrets. Check where their local state is stored and exclude it from version control.
• Secrets. Keep credentials out of the repository, environment of the agent process where possible, and any memory or log a tool writes.
• Mitigations. Read before install; pin versions; sandbox; least-privilege permissions; deny destructive commands; require human approval for irreversible actions (human-in-the-loop).
• Licences. Context Mode uses the Elastic License 2.0, which is source-available rather than OSI open source; check it against your use.

• Skill never loads. The description does not match how users phrase the task. Rewrite it with concrete trigger phrases.
• Skill loads when it should not. Description too broad. Narrow it.
• Instructions ignored. Too many competing instructions, or an earlier instruction conflicts. Reduce, deduplicate, put the critical rule first.
• Hook blocks legitimate work. Log hook inputs and exit codes; make failure messages explicit.
• Behaviour changed overnight. A pack updated or the model changed. Check pinned versions and rerun your task set.
• Context exhausted early. Audit what loads at session start; remove or lazy-load.

Debug by reading the transcript: which skills were offered, which loaded, which tools ran, and what each hook returned. See agent tool error cascade.

Every skill description, rule and hook output that enters context is paid for on each turn. Large packs have a standing cost even when unused if their descriptions or rules load at start. Skills that cause more planning and review turns add tokens and wall time; they may save time elsewhere by reducing rework. Context tools can reduce input tokens when tool output is large, and add overhead per call.

Do not estimate; measure. Record input tokens, output tokens and wall time per task with and without the tool, then price them with the LLM cost calculator. Cost per successful task is the number that matters, not tokens alone. See cost blowup after launch.

• Plain instruction file. Simplest; always loaded, so keep it short.
• Your own skills. Fit your process and are easy to audit; you maintain them.
• Third-party packs. Fast start and ideas to borrow; more to audit and more drift.
• Large harness configs (ECC style). Broad capability, large trust and context footprint. Take a subset.
• Fine-tuning or a different model. Changes capability, not workflow; far more expensive to iterate.

• The task is small and a clear prompt already works.
• Your security policy forbids third-party code in the agent's execution path.
• You have no way to measure results; you will adopt on vibes and not know when it stops helping.
• You would install a pack to avoid thinking about your own process.

• obra/superpowers
• mattpocock/skills
• affaan-m/ECC
• mksglu/context-mode
• Your agent client's own documentation for skills, hooks and permissions. We have not reproduced exact configuration keys because they change.

• Agentic AI Engineering path
• Lab: build an agent loop
• Lab: build an eval pipeline
• Lab: measure agent skills
• Project: research agent