hraness

agent skills are procedures, not prompts

versioned, released, and checked

Drafted by an AI agent at Ben Guo's direct request from the Hraness source repositories, and checked against those sources before publication.

An agent skill is usually introduced as a clever prompt in a directory. That framing is why most skills rot: prompts are suggestions, and suggestions drift, break silently, and get copied until nobody knows which version is authoritative. The skills that survive are treated as procedures. A procedure has a trigger, ordered steps, explicit boundaries, validation commands, and a stopping condition. It can be versioned, released, and checked like any other artifact.

Hraness publishes a working example as the skillpack repository: 33 canonical SKILL.md files organized into four packs, distributed to Codex, Cursor, Copilot, and skills.sh-compatible hosts. The interesting engineering is not the prompts; it is everything around them.

the skill file is the product

The pack’s own description of its pipeline is the model in one line:

request → one bounded owner → canonical SKILL.md → repository commands and gates → evidence

Each SKILL.md is the canonical source. The Codex plugin manifests, the .cursor-plugin adapters, the Copilot marketplace metadata, and the skills.sh.json registry file are thin adapters over the same sources. That layering is the difference between “a prompt library” and a distributed artifact: fix a procedure once and every host gets the fix on the next install, because no adapter carries its own copy of the logic.

The four packs divide by audience, not by topic: hraness-engineering for understanding, testing, verifying, documenting, measuring, or safely refactoring one repository concern; code-orchestrator for explicitly multi-phase delivery plans; semantic-algos for explicitly requested reasoning transforms; and skillpack-admin for auditing and adopting the distribution itself. Each pack’s entry in the README names what it is for and, equally important, what it is not for.

Portability is a property of the directory, not the host. Every plugins/<plugin>/skills/<skill>/ directory is independently portable into an Agent Skills-compatible runner, so a procedure written once travels to whatever host the next task runs in. The README is equally careful about the boundary the other way: repository instructions, validation commands, scheduling, CI, and delivery policy remain controlling, and a skill does not replace them.

anatomy of a procedure

A durable skill file has a recognizable shape, and the conventions in the monorepo’s own skills/ directory state it plainly:

  • Frontmatter carries only name and description. The description is a routing contract: when to use the workflow and when not to.
  • Instructions are imperative and exact about triggers, output paths, destructive behavior, and validation.
  • Deterministic repeated logic lives in a tested script, not in prose the model must re-derive each run.
  • Detailed reference material stays outside SKILL.md until the workflow needs it.

The deep-review skill in this site’s monorepo is a fair example: its frontmatter names the requests that trigger it (“what should I buy/use/do” guides, researched recommendation pages), and its body is a numbered procedure. Frame the reader’s decision. Harvest sources community-first in a stated order. Classify every claim by confidence tier. Keep the source ledger in kb/ so a later agent can re-audit it. Nothing in it asks the model to be clever; it asks the model to execute a method and name its evidence.

The discipline shows up even in the smallest conventions. The repository’s skills guide requires frontmatter with only name and description, imperative instructions, deterministic repeated logic moved into a tested script, and reference material kept outside SKILL.md until the workflow needs it. Some skill directories are thinner still: the KB, Direct, and Ghostget workflows ship as discovery-only loaders whose frontmatter routes to a SKILL.md inside the pinned installed package, so the repository cannot drift from the released procedure.

The phase-delivery pack shows the other half of procedure-ness: phase-orchestrator, phase-implementer, phase-reviewer, and phase-final-reviewer are separate skills because delegation is a boundary. The reviewer skill instructs the reviewing agent to inspect the plan and the actual change before reading the implementer’s notes, to treat those notes as claims to check, to patch only bounded low-risk findings, and to report a clear no-op rather than invent findings. Its final response is a fixed six-heading contract ending in Blockers and risks. That is not a prompt. That is a job description with a form at the end.

routing is tested

Skill libraries fail in a second, quieter way: two skills overlap, and a request gets routed to whichever the model fancied that day. Skillpack treats routing as a testable property. catalog/routing-fixtures.json contains fixtures that exercise adjacent skills pairwise, so a request like “audit this distribution” versus “audit this repository’s dependencies” retains one primary owner. catalog/catalog.json is the discoverable inventory the tests run against.

The same instinct shows up in the skills’ stated boundaries. semantic-algos is explicit-only: it does not silently take over coding tasks. code-orchestrator is not a compute scheduler and does not replace CI or merge policy. Every skill says what it refuses, because a procedure without a refusal condition is a prompt waiting to be misapplied.

Even the README’s first demonstration is a routing table rather than a feature list: “map this repository’s user-visible features and proof paths” routes to repository-feature-map, and “execute this existing multi-phase plan with implementers and reviewers” routes to phase-orchestrator. Each request names one bounded owner, the same ownership property the fixtures test mechanically.

provenance and release

A pack assembled partly from adapted upstream work carries its lineage in machine-checked files: sources.lock.json pins exact upstream revisions, catalog/provenance.json records local path inventories, and THIRD_PARTY_NOTICES.md carries the attribution. The licensing is stated with unusual honesty: the semantic-algos material is included with attribution and permission rather than claimed as MIT-licensed, and because its permission grant is not a recognized permissive open-source license it is deliberately absent from the Cursor marketplace manifest. Provenance decides distribution, not the other way around.

Distribution runs through immutable releases. Consumers install the pinned v0.2.2 release (codex plugin marketplace add hraness/skillpack --ref v0.2.2); the skills.sh-compatible path is npx skills add hraness/skillpack; and the Cursor adapter is a manual copy or symlink of a selected plugins/<name> directory into $HOME/.cursor/plugins/local followed by a reload. Three install surfaces, one canonical source; that is the entire reason the adapters must stay thin. The repository’s own bun install --frozen-lockfile plus bun run check gates host manifests, registry files, portability, provenance, and offline administration canaries. A change to a skill is a source change that ships through the same review and release mechanics as code, because it is code: it directs behavior, so it gets the same custody.

The pack also ships the tools to administer itself, with the same procedure discipline. skillpack-admin’s audit script is read-only by definition; the adopt script previews by default and requires an explicit --target before it writes anything, with --apply gated on a reviewed plan and --repair creating a sibling backup rather than deleting extra destination files. Even the installer is a procedure: inspect first, plan second, mutate third, and keep the evidence.

when a prompt is enough

The procedure framing is not always warranted. A one-off instruction in a conversation, a creative brief, a question asked once: these are prompts, and treating them as procedures would be bureaucracy. The crossover point is repeatability plus consequence. If the same request will recur across sessions or agents, and if getting it wrong costs real work, it earns a procedure: named triggers, ordered steps, a validation command, a refusal boundary, and a place in the checked inventory.

There is also a maintenance argument for procedures that pure prompts lack. A procedure can name its validation command, which means a repository gate can prove the skill still works after the surrounding machinery changes. A prompt can only be re-read. The skillpack repository’s bun run check exists precisely so that a host-manifest change, a renamed skill, or a broken adapter is a failing test rather than a silent documentation bug discovered by the next user.

The test to apply is simple. If you cannot write down when the skill should not run, you have a prompt. If you cannot say what evidence closes it, you have a hope. A skill that survives is neither: it is a procedure with a release number.

sources

  • skillpack: 33 canonical SKILL.md sources, four packs, thin host adapters, routing fixtures, and provenance locks.
  • The monorepo behind this site (projects): the repository-local skills/ conventions and the deep-review and phase-delivery skills described here.
  • skills.sh: the registry view of the same pack.