Esc
  • SuggestedWhat is HCP?
  • SuggestedBuild a pack
  • SuggestedPack classes
  • SuggestedSpecification
  • SuggestedCLI reference
.md

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.

On this page

The pack Skill is HARNESS.md, the one screen that teaches humans and agents to call this pack's commands correctly. Like Agent Skills 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:

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.

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>

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). 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, 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).