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

§5 Skill

Normative requirements for HARNESS.md: presence, content constraints, the copy on activate, and drift with the manifest.

On this page

The Skill is HARNESS.md at the pack root.

5.1 Presence#

  1. A pack MUST contain HARNESS.md. Runtimes MUST fail lint otherwise (missing_harness).
  2. HARNESS.md MUST be UTF-8 Markdown.
  3. The manifest field harness (inline Skill text) is deprecated. When both are present, HARNESS.md takes precedence.

5.2 Content#

  1. The Skill MUST NOT contain credential material of any kind, including placeholders formatted as credentials.
  2. The Skill MUST NOT contain host-absolute filesystem paths as normative steps.
  3. The Skill MUST NOT present an MCP tool list as the way to invoke the pack.
  4. Every command the Skill teaches MUST be a verb_key declared in the manifest.
  5. The Skill MUST NOT describe triggers the manifest does not declare.
  6. The Skill SHOULD fit on one screen and SHOULD follow this order: title, lead, hot-path table, examples, setup (if Binding is not public), anti-patterns, pointers.
  7. The title SHOULD be # HCP — <Name>.
  8. Examples SHOULD use the CLI face with --json and SHOULD show --confirm / --apply on gated writes.

5.3 Lead#

  1. The lead is the text between the title and the first ## heading.
  2. Runtimes and hosts MAY truncate the lead for stable context. The reference default is 480 characters.
  3. Authors SHOULD write the lead so that, truncated, it still states what the pack does, whether it needs login, and the first command to run.

5.4 Copy on activate#

  1. On activate, a runtime SHOULD copy HARNESS.md to a Skill location hosts discover. The reference location is $HCP_HOME/skills/<pack_id>/SKILL.md.
  2. The copy MUST be byte-identical to HARNESS.md or a faithful rendering; a runtime MUST NOT inject credentials, host paths, or policy into it.
  3. Host adoption (hcp adopt) MAY copy the Skill again into a host-specific location.

5.5 Drift#

Informative. Skill ↔ manifest ↔ Policy drift is a lint concern under the four-faces rule (§12.4). Runtimes SHOULD warn when a Skill's hot-path table names a command the manifest lacks or omits one it declares.

5.6 Relationship to Agent Skills#

Informative. HARNESS.md follows the Agent Skills principles of progressive disclosure, examples, and anti-patterns. It is intentionally scoped to invocation. When copied to SKILL.md it is a valid Agent Skill body; frontmatter, if a host requires it, is added by the runtime at copy time from manifest fields.