Capstone: Build Your Skill Engineering Workflow

What This Capstone Builds

The previous twelve lessons covered each component of skill engineering independently. This capstone connects them. You will walk through building a review-pr skill — one that runs a structured pull request review checking security, tests, documentation, and breaking changes — from the initial idea through public distribution. Every stage references the lesson where that concept was covered in depth.

The walkthrough uses Claude Code as the primary platform with Hermes callouts at each stage where the syntax or approach differs. The design decisions are identical across platforms; only the implementation details change.

Stage 1: Search First (L12)

Before writing a line of SKILL.md, search the community registries. A high-quality existing skill is better than anything you can write in an afternoon.

hermes skills search "pull request review"
hermes skills search "pr review security"

Evaluate the results against the trust tier table from L12. If you find something at official or trusted tier that covers your use case, inspect it before deciding:

hermes skills inspect official/review-pr

In this walkthrough, the existing community skills are either too generic (no security checklist), abandoned (last commit 2025), or missing compatibility declarations. The gap justifies a new skill built to your team's standards.

Stage 2: Design Decisions (L3)

Three design questions determine the skill's shape before writing begins.

Reference skill or task skill? A PR review is a specific action — task skill. It should not auto-invoke silently on every session; it should activate when the user explicitly asks for a review.

Single responsibility check. One skill, one workflow: structured PR review. If a security audit and a changelog generation started appearing in the same skill, it would need to split.

Model and effort overrides? Yes. PR review benefits from deep reasoning. effort: high applies for the review turn only. context: fork isolates the review from session history — it sees only what the user provides, not accumulated context from unrelated work earlier in the session.

Hermes callout: Hermes uses requires_toolsets instead of context for isolation — declare requires_toolsets: [code_review] when a code review toolset is available in your deployment.

Stage 3: Write or Capture? (L4)

The team conventions and security checklist are specific enough that auto-capture would underspecify them. Hermes /learn and Claude Code's post-workflow capture produce good first drafts for procedural skills, but this skill encodes judgment calls — which security patterns to flag, what counts as a breaking change — that require hand-authoring.

Decision: write by hand. Treat any auto-generated draft as a first draft requiring a full description pass, explicit pitfalls section, and verification step.

Stage 4: Frontmatter (L2, L3)

Start with the agentskills.io portable fields (L2), then add the platform-specific fields that encode design decisions from Stage 2.

---
name: review-pr
description: Structured pull request review — checks security, tests, docs, and breaking changes
when_to_use: "Use when user asks to review, submit feedback on, or critique a pull request — not for general git questions or commit history"
version: 1.0.0
license: MIT
compatibility: "Requires gh CLI >=2.40. Claude Code: v2.1.196+. Hermes: any current version."
context: fork
agent: Explore
effort: high
paths: "*.diff,*.patch"
allowed-tools: Bash(gh *)
---

The paths field limits auto-invocation to diff and patch files (L7 tuning in advance). The when_to_use field gives Claude discriminating context: PR review, not general git questions. The compatibility field is the skill's contract with consumers — state the gh CLI version explicitly.

Hermes callout: Replace when_to_use with metadata.hermes.trigger_phrases for equivalent discriminating context. The context: fork and agent fields are Claude Code-only; use requires_toolsets for the Hermes equivalent of capability gating.

Stage 5: Add Hooks (L5)

After the review runs, the output should format as a GitHub comment template automatically — a persistent behavior for the rest of the session. Register it as a post-tool hook:

hooks:
  - event: post-tool
    match: {tool: "Bash", command_contains: "gh pr"}
    actions:
      - type: note
        message: "Review complete. Format output as GitHub comment template."

This hook stays active for the entire session after the user invokes /review-pr. That means every subsequent gh pr command will trigger the formatting note — a useful session-wide behavior, but one that should be documented clearly in the skill description so users know what they're activating.

Hermes callout: Use hermes hooks add within the skill procedure to register an equivalent gateway hook. The behavior is the same — persistent through the session — with Hermes-specific hook syntax.

Stage 6: Supporting Files (L3)

Heavy reference material belongs in references/, not in SKILL.md. Material in references/ loads only when the skill explicitly fetches it — it doesn't cost tokens on every invocation.

review-pr/
+-- SKILL.md
+-- references/
    +-- security-checklist.md     # OWASP top 10, injection patterns, auth checks
    +-- breaking-changes-guide.md # API versioning rules, deprecation signals

The SKILL.md procedure instructs Claude to fetch @references/security-checklist.md when reviewing security-sensitive changes, and @references/breaking-changes-guide.md when the diff touches public API surfaces. Both files load on demand, not on every review.

Stage 7: Test (L6)

Run the baseline A/B test from L6: collect five realistic PR review prompts, run each in a fresh session with the skill enabled and then with it disabled, compare outputs.

Install the skill-creator plugin and write evals for the most important scenarios:

/plugin install skill-creator@claude-plugins-official

Three eval cases cover the core scenarios: a PR with a SQL injection pattern (should flag security), a PR with no tests added (should flag test coverage), and a general refactor with no issues (should pass cleanly without false positives). The benchmark output shows the quality delta between with-skill and without-skill on each case.

Hermes callout: Use hermes chat --toolsets skills -q "review this PR" to run a single-turn test verifying the skill activates at the correct disclosure level. Run skill_view at levels 0, 1, and 2 to confirm the three-tier progressive disclosure is wired correctly.

Stage 8: Measure and Tune (L7)

After one week of real use, check /skill-doctor (Claude Code v2.1.252+). Look for two numbers: invocation frequency and context cost. If invocation is low, the when_to_use field may be too narrow — run a description A/B test with skill-creator to find phrasing that triggers on more realistic PR review prompts without firing on unrelated git questions.

If the skill fires during general git operations, the paths field is the fix: tighten the glob, or add a more discriminating when_to_use clause. Tuning precision is cheaper than living with false-positive invocations that waste effort and context budget.

Stage 9: Version and Changelog (L8)

The skill shipped at version: 1.0.0. Initialize a CHANGELOG.md in the skill directory:

## 1.0.0 — 2026-09-16
Initial release. Checks security (OWASP top 10), test coverage, documentation gaps, and breaking changes. Requires gh CLI 2.40+.

When the security checklist expands to cover a new vulnerability class, that's a minor bump: 1.1.0. When the procedure restructures or required inputs change, that's a major bump: 2.0.0, with a migration note in the description. Consumers checking for updates read CHANGELOG.md rather than diffing SKILL.md line by line.

Stage 10: Structure for Sharing (L10)

Prepare the public repository structure:

my-skills/
+-- README.md         # Install instructions + what each skill does
+-- CHANGELOG.md      # Library-level changes
+-- review-pr/
    +-- SKILL.md
    +-- CHANGELOG.md
    +-- references/
        +-- security-checklist.md
        +-- breaking-changes-guide.md

The README states the install command explicitly: hermes skills tap add owner/repo then hermes skills install owner/repo/review-pr. For Claude Code users: copy review-pr/ into .claude/skills/. The compatibility field in the frontmatter declares prerequisites; the README repeats them in prose so consumers can verify before installing.

Stage 11: Publish (L10, L12)

Push the repository to GitHub as a public repo, then submit to the Skills Hub:

hermes skills publish review-pr --to github --repo owner/my-skills

The skill enters the Hub at community tier. It goes through automated security scanning — the exfiltration, injection, destructive, and supply-chain checks from L12. Results land in the Hub's append-only lock file. Once listed, anyone can discover it via hermes skills search "pull request review" and install it with one command.

Announce in your team channel with the install command. Monitor invocation via /skill-doctor or Curator stats over the following weeks. When someone files an issue noting that the skill fires on commit message edits (not just PRs), that's Stage 8 data feeding back into Stage 4 — the lifecycle continues.

Every Track Concept in One Skill

Walk back through the stages and the lessons they touched:

• L1 — skills as software with a lifecycle; this skill will go through experiment, validated, stable, and eventually deprecated
• L2 — portable frontmatter fields separate from platform-specific extensions
• L3 — task skill vs. reference skill; single responsibility; token budget discipline via references/
• L4 — write by hand rather than capture when team judgment calls are encoded in the procedure
• L5 — hooks that install persistent session behavior on invocation
• L6 — baseline A/B test plus skill-creator evals for measurable quality assurance
• L7 — /skill-doctor data feeding back into description and paths tuning
• L8 — semantic versioning and CHANGELOG keeping the skill's history legible
• L9 — naming conventions and lifecycle stages for the personal library that now contains this skill
• L10 — public repository structure and self-contained install instructions
• L11 — distributing via project skills or managed settings if this goes to a team
• L12 — trust tiers, the evaluation checklist, and automated scanning on the receiving end

A production-quality skill is not written in one sitting. It goes through eleven deliberate stages from idea to published. The platform callouts at each stage show that the decisions — when to search first, how to design for single responsibility, how to test, how to version — are the same on Claude Code and Hermes. Only the syntax changes. The engineering discipline is the same skill either way.