---
title: "Skill"
description: "How to write the one screen of HARNESS.md an agent gets right on the first try, what lint checks in it, and where hosts pick it up on activate."
canonical: https://harnesscontextprotocol.io/docs/concepts/skill
---

# Skill

> How to write the one screen of HARNESS.md an agent gets right on the first try, what lint checks in it, and where hosts pick it up on activate.

The pack Skill is `HARNESS.md`, the one screen that teaches humans and agents
to call this pack's commands correctly. Like [Agent Skills](https://agentskills.io)
it is short, led by examples and aware of anti-patterns, though it teaches
invocation only and is never a product manual. A person deciding whether to use
the pack reads it too, but write it for the agent that will run the commands
unattended.

## Skill file

A pack without a Skill is machine-readable but not teachable, so lint requires
`HARNESS.md`:

```text
HCP pack "weather" missing HARNESS.md skill
```

A Skill fits on one screen in this order: title, lead, hot-path table,
examples, setup (only when Binding is not `public`), anti-patterns, and
pointers that link out instead of inlining vendor manuals. Start from the
template, or copy a filled one.

<Tabs items={['Template', 'Example: ledger']}>
<Tab value="Template">

````md title="HARNESS.md"
# HCP — <Pack name>

<One sentence: what the pack does.> <One sentence: Binding posture — "No login." or
"Run `connect` once; see Setup.">

## Hot path

| Command | CLI | Policy |
|---------|-----|--------|
| `<verb>` | `<bin> <verb> <args> --json` | read |
| … | … | … |

## Examples

```bash
<bin> <verb> "<arg>" --json
<bin> <write-verb> <arg> --confirm --json
```

## Setup (only if Binding is not public)

```bash
<bin> setup status --json
<bin> setup all -y --json
<bin> connect <provider> --json
```

## Anti-patterns

- <Wrong thing agents do, and the right thing instead>
- …

## See also

- <one or two links; never inlined vendor manuals>
````

</Tab>
<Tab value="Example: ledger">

```md title="HARNESS.md"
# HCP — Ledger

Banking-class wrap: onboard, connect, doctor, one domain read, one gated write.
Local workspace land. Secrets never in this Skill.

## Hot path

| Command | CLI | Policy |
|---------|-----|--------|
| `setup.status` | `ledger setup status --json` | read |
| `setup.apply` | `ledger setup all -y --json` | write |
| `connect` | `ledger connect demo --json` | write |
| `status` | `ledger status --json` | read |
| `list` | `ledger list --json` | read |
| `transfer` | `ledger transfer 2.80 --to demo-transit --confirm --json` | write + confirm |

## Anti-patterns

- Env-flag mocks (`LEDGER_MOCK`)
- Transfer without `--confirm`
- Mixing operator bins onto this pack
- MCP as the install path
```

</Tab>
</Tabs>

### The lead

Hosts do not paste the whole Skill into context. The reference `HarnessAgent`
puts the first ~480 characters of each activated pack's Skill in a stable
prefix and loads the rest on demand through `hcp__read_skill`
([Context optimization](/docs/hosts#context-optimization)). So the lead, two
sentences, must stand alone and say what the pack does, whether it needs login
("No login." or "Run `connect` once.") and which command to run first.

Bad: *"Ledger is a comprehensive financial capability pack that exposes a
range of operations…"*

Good: *"Gated-write wrap: onboard, connect, one domain read, one confirmed
transfer. Run `ledger setup status --json` first."*

### Hot path and examples

The hot-path table lists exactly the manifest's 5 to 12 commands with their CLI
form, and its Policy column shows the agent which ones write before it plans.
Examples use real commands with real-looking arguments and `--json`, and show
the confirm flag on gated writes so the agent copies it. Leave `hcpx exec` out:
the Skill teaches the domain bin, and the envelope Invoker belongs in runtime
docs. Give `connect` its own Setup heading, because agents that see it in the
hot-path table re-link on every turn.

### Anti-patterns

This is the most useful part of the file: three to six bullets, each naming a
concrete mistake, such as a wrong Binding mode, a wrong land, interactive flags
or a tight loop, and its fix.

- Env-flag mocks such as `LEDGER_MOCK=1`. Use `mode: mock` in the envelope instead.
- `transfer` without `--confirm`. The runtime refuses it anyway.
- Polling `plan` in a loop. Call `follow` once.
- Running `setup all` without `-y` on the agent path. It prompts and hangs.
- Mixing operator bins onto this pack. Operator commands belong in a second pack.

## On activate

`hcpx install` and `hcpx activate <id>` copy `HARNESS.md` to
`$HCP_HOME/skills/<id>/SKILL.md`, so hosts that speak Agent Skills discover it
without HCP-specific code. `hcpx adopt` copies no pack Skills into the host and
writes one protocol Skill instead, which tells the agent to read a pack's Skill
with `hcpx skill <id>`.

## Rules

- Only declared commands, since the Skill, the manifest, Policy and the CLI are
  four faces of one `verb_key`. Lint fails when a named command never appears
  in the Skill as a backticked `verb_key`, or when the first column of a table
  above `## Anti-patterns` names a command the manifest does not declare.
- Mention Sense only when the manifest declares stimuli.
- No secrets, tokens or client ids, even fake ones, because they get copied.
  Lint fails on key, password, secret or token assignments.
- No host-absolute paths, since Skills are portable. `~/.hcp/…` is fine; lint
  fails on `/Users/…`, `/home/…`, `/root/…`, `/opt/…` and `/srv/…`.
- MCP stays an export. Lint fails when the teaching part (everything above
  `## Anti-patterns`) presents MCP as the way to install or invoke the pack;
  naming it under Anti-patterns is fine.
- No UI widget catalogs, since hosts render, and no product strategy, roadmap
  or marketing.

The lint rules come from
[RFC 0002](https://github.com/harnesscontextprotocol/hcp-protocol/blob/master/rfcs/0002-skill-four-faces.md),
a draft the reference SDK implements. `hcpx check` adds quality rules on top,
such as the title line, the length of the lead and the anti-patterns section
([Skill rules](/docs/packs/check#skill)).

## Related

- [Landscape](/docs/introduction/landscape): Skills and Agent Skills
- [Specification: Skill](/docs/specification/skill)

## Sitemap

- [Documentation](https://harnesscontextprotocol.io/docs)
- [Packs](https://harnesscontextprotocol.io/packs)
- [Glossary](https://harnesscontextprotocol.io/docs/reference/glossary)
- [llms.txt](https://harnesscontextprotocol.io/llms.txt)
- [llms-full.txt](https://harnesscontextprotocol.io/llms-full.txt)
- [OpenAPI](https://harnesscontextprotocol.io/openapi.json)
- [MCP](https://harnesscontextprotocol.io/mcp)