P8: Discoverable Through Agent Skill Bundles

Definition

Without a skill bundle, every fresh agent invocation begins the same way: pull --help, infer the idioms, try a command, parse the error, try again. A skill bundle (canonical names AGENTS.md or SKILL.md) collapses that loop — agent-discoverable through filesystem convention rather than through --help, loaded once, recognized thereafter.

Why Agents Need It

--help describes what is possible (the flag and subcommand surface); a skill bundle describes what to do (workflow knowledge, common compositions, recovery patterns). Workflow knowledge does not fit in after_help examples. The bundle is also where conventions that span multiple subcommands live — exit-code tables, output-channel discipline, retry semantics — context that --help for a single subcommand cannot carry on its own. Without one, the agent has nowhere to durably register what it learned, and re-pays the discovery cost on every fresh session.

Requirements

Evidence

• A top-level AGENTS.md or SKILL.md in the CLI's source tree, shipped in the release artifact, with YAML frontmatter declaring at least the tool name and a one-line capability summary.
• A skill subcommand group in the CLI (e.g., tool skill install, tool skill update, tool skill list).
• An installer that writes directly to the runtime cascade (~/.claude/skills/<tool>/, ~/.cursor/skills/<tool>/) rather than requiring the runtime to be running.
• Bundle content versioned alongside the CLI's release: the bundle ships from the same commit as the binary, not from a separate documentation tree that drifts.

Anti-Patterns

• A CLI shipping a skill bundle with no install path. The bundle sits unread until a human copies it manually.
• An install path that requires the agent runtime to be running. The runtime cascade is filesystem-resident; writing to it should not need an active session.
• A bundle whose contents drift from the CLI's actual surface — a skill bundle in a docs subtree maintained by a different cadence than the binary itself, naming flags or subcommands that no longer exist.

Requirement IDs p8-must-bundle-install, p8-should-bundle-exists, p8-may-install-all, and p8-may-bundle-update define the contract; behavioral checks land as the linter grows P8 coverage. Run anc check --principle 8 . against your CLI to see what's measured today.