# Skill Builder > Build and publish production-ready Hermes skills — research, author, review, ship. - Skill: `rkelln/skill-builder` (Agent Skill) - Install (CLI): `npx skillmds@latest add rkelln/skill-builder` - Raw SKILL.md: https://api.skillmd.com/api/skills/rkelln/skill-builder/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Research & Search - Author: RKelln (https://skillmd.com/u/rkelln) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/rkelln/skill-builder --- # Skill Builder Build production-ready Hermes skills from idea to publication. This skill orchestrates the full pipeline: research existing solutions, author the SKILL.md, test it, run an independent review, and publish. **Prerequisites:** Install `skill-research` first — Phase 1 delegates to it. Install `requesting-code-review` if you want structured review output. **How this differs from existing skill-builders:** Most skill-creator skills (Hermes and otherwise) focus on the authoring step. This one adds pre-build research (don't reinvent) and independent review (don't ship broken). If you only need the authoring step, ClawHub's `create-skill` or GitHub's `re-sianturi/skill-builder-for-hermes` may suffice. ## When to Use - User says "build a skill for X" or "create a skill that does Y" - User has an idea for a reusable agent capability - User wants to publish a skill for others to use ## Hermes Skill Conventions Before building, know the rules. These are hard-won from shipping skills. ### Portability - Use `SKILL_DIR` for self-references. Define it early: *"SKILL_DIR refers to the directory containing this SKILL.md file."* - Scripts use `HERMES_HOME` env var (fallback `~/.hermes`), never hardcoded paths - Cron scripts go in `$HERMES_HOME/scripts/` — copy them there in setup docs ### Structure - YAML frontmatter: `name`, `description` (brief, one-line), `version`, `platforms`, `metadata.hermes.tags`, `metadata.hermes.category` - **Description is the skill's trigger mechanism.** The description appears in the `` block the agent scans every turn. If it doesn't contain the user's likely trigger words, the skill will never load. Include the exact phrases users will say: `"Handle 'research [URL]' and 'read [URL]' requests"` not `"Orchestrate research sessions."` Include a direct instruction: `"Load this skill whenever the user sends a URL with research intent."` Test: would a busy agent scanning 100+ skill descriptions recognize that this skill matches the user's message? - Optional frontmatter: `author`, `license`, `metadata.hermes.related_skills`, `metadata.hermes.requires_toolsets`, `metadata.hermes.fallback_for_toolsets`, `required_environment_variables` - Sections: When to Use, Quick Reference (if useful), Procedure (phased), Pitfalls, Verification ### Safety and Tone - **Never include pipe-to-interpreter patterns.** No `curl | python3`, `curl | bash`, `curl | tar`, or any pipe from network to interpreter/archiver. Skills that include these teach unsafe habits. Always show download-to-file first, then process the local file. If a skill fetches content from the network, include a ⚠️ safety banner. - No PII (usernames, machine names, home paths other than `~/.hermes`) - No vendor-lock (model names in examples, not requirements) - No marketing language ("revolutionary", "game-changing", "powerful") - Instructional tone — tell the agent what to DO ### Scripts - Prefer Python stdlib when possible (no pip install step for users) - Read-only detection scripts are safer (no accidental writes) - If your script hashes files, match Hermes' `_dir_hash` — see the implementation in the Pitfalls section below ### Conditional Activation Skills can declare when they should or shouldn't appear based on available tools. Consider adding these to frontmatter if your skill is a fallback for when another tool is unavailable: ```yaml metadata: hermes: fallback_for_toolsets: [web] # Show only when web tools unavailable requires_toolsets: [terminal] # Show only when terminal available ``` ## Quick Reference | Phase | Tool / Command | |-------|---------------| | Research | `hermes skills search`, `hermes skills inspect`, GitHub topics | | Mine | Clone adjacent repos, read sub-files, extract reusable features | | Author | `write_file` to `~/.hermes/skills///SKILL.md` | | Test | Load with `/skill `, exercise the procedure | | Review | `delegate_task` with fresh subagent context | | Publish | `hermes skills publish --to github --repo /` | ## Procedure ### Phase 0: Pre-Create Overlap Check (MANDATORY — do not skip) **Core principle: ONE skill per capability (output format × tool). Genres and projects are REFERENCE FILES, not skills.** Hermes has a documented tendency to over-develop skills: given several projects that want beautiful HTML / typeset PDF output (Keeper, Covenant, fiction, essays), it created 8-10 near-duplicate skills (literary-html, literary-typst, literary-typesetting, fiction-typesetting, fiction-typography, markdown-publishing, markdown-to-typst…) instead of one generalized skill per output format with genre-specific reference files. This wastes context (all get listed in the skill index), splits maintenance, and makes the index harder to scan. The correct shape: ``` markdown-html/ <- ONE skill for HTML output ├── SKILL.md <- generalized procedure └── references/ ├── literary-essay.md <- genre conventions └── project-manifesto.md ``` Before ANY `skill_manage(action='create')` call, run the overlap check. This is a hard gate: 1. Run `skills_list()` (or `ls ~/.hermes/skills/`) and read every existing skill's name + description. 2. Classify the proposed skill against existing ones: - **DUPLICATE** — same output/tool/use case as an existing skill. → Do NOT create. Tell the user the existing skill and offer to improve that one instead. - **ADJACENT** — same output/tool, different use case or audience (fiction vs essay vs manifesto). → Do NOT create. **The genre variation becomes `references/.md` inside the existing skill** (one file per genre, with a pointer line in SKILL.md), or is merged in via `skill_manage(action='patch')`. Never a new skill for a genre. - **PARTIAL** — proposed skill is a subset of an existing skill. → Do NOT create. The existing skill already covers it. - **NONE** — genuinely no overlap (different output format or different tool). → Green light to create. 3. If the user explicitly pushes back ("no, I want a separate skill"), create it — but record the overlap in the description frontmatter so future scans can find it (`description: "... Overlaps with : covers ."`). **Probe:** compare on output format + tool + use case. Two skills that produce HTML from markdown are duplicates even if one says "literary" and the other says "fiction". If the only difference is genre, style, or tone, it's a DUPLICATE — and the genre belongs in a reference file. **Post-create review (also mandatory):** after ANY skill creation (or any session that created 2+ skills), re-scan the library and ask: "could this have been a reference file inside an existing skill?" If yes, say so to the user and offer to restructure before the skill propagates. New skills created in one sitting are a burst signature — audit them as a group before declaring done. ### Phase 1: Research (don't reinvent) Load the `skill-research` skill (must be installed) and search all registries: 1. Run 3-5 `hermes skills search` queries with different phrasings 2. Check `https://github.com/topics/hermes-skills` 3. Inspect top candidates with `hermes skills inspect ` 4. Classify findings: DUPLICATE, ADJACENT, PARTIAL, or NONE If a DUPLICATE exists: tell the user and offer to install it instead. If ADJACENT or PARTIAL: proceed to Phase 1b — mine them for reusable features. If NONE: green light. Proceed to Phase 2. ### Phase 1b: Mine Adjacent Skills (extract reusable features) Adjacent and partial skills aren't just competitors — they're free research. Before writing your own skill, pull them down and mine them for value: 1. Clone the repo for the most comprehensive adjacent skill(s): ```bash cd /tmp && git clone --depth 1 ``` 2. Read the SKILL.md and all sub-files (look for `references/`, `*.md` siblings, `scripts/`, `examples/`). Adjacent skills often have multiple sub-files. 3. Identify what to integrate into your skill: - **Features you missed** — sub-commands, flags, workflows not in your plan - **Pitfalls they found** — error tables, gotchas, known failure modes - **Agent-specific patterns** — how they solve the "agent can't see PDFs" problem, verification methods, CLI introspection tricks - **Conversion/migration tables** — if the tool interoperates with others 4. **Do NOT** copy their skill wholesale or import their scripts. Extract the knowledge and re-express it in your skill's voice and structure. 5. Report to the user: what you found, what you're integrating, what you're intentionally leaving out and why. Be specific about omissions — e.g., "left out package publishing (niche), search scripts (require embedded data files), and academic specifics (covered by separate skill)." This shows you made conscious tradeoffs, not that you missed things. This step turns 5 existing skills from "competition" into "research budget." It is not optional — if ADJACENT or PARTIAL skills exist, mine them first. ### Phase 2: Author the SKILL.md Write the skill to `~/.hermes/skills///SKILL.md`. **Frontmatter template (required fields):** ```yaml --- name: description: "" version: 1.0.0 platforms: [linux, macos, windows] metadata: hermes: tags: [<3-8 relevant tags>] category: --- ``` **Optional frontmatter fields** (add as needed): ```yaml author: license: MIT metadata: hermes: related_skills: [] requires_toolsets: [terminal] fallback_for_toolsets: [web] required_environment_variables: - name: API_KEY prompt: Description of what this key is for ``` **Body structure:** 1. One-paragraph overview 2. "## When to Use" — trigger conditions 3. "## Quick Reference" — optional, one-table command reference 4. "## Procedure" — numbered phases with exact commands 5. "## Pitfalls" — known failure modes and fixes 6. "## Verification" — how to confirm it worked For tool-oriented skills (CLI tools, APIs, compilers), add a "### Common Error Messages" subsection under Pitfalls — a 3-column table (Error / Cause / Fix) that maps exact error strings to their causes and fixes. This turns the skill into a self-service debugger. **Scripts:** Place in `scripts/` subdirectory. Document with exact invocation commands. If needed for cron, add a "## Cron Job Setup" section. **References:** Only create `references/` if agents NEED them to operate. Human-only reference material should be inline or omitted. ### Phase 3: Test the Skill Before review, load and exercise the skill: 1. Load it: `/skill ` in a Hermes session, or use the skill as instructed 2. Walk through the Procedure steps as an agent would 3. Verify every command in the skill actually works 4. Fix any broken commands, missing steps, or unclear instructions Testing catches things you missed while authoring. Don't skip this. ### Phase 4: Independent Review Spawn a critical subagent review. This is a Hermes `delegate_task` tool call (not raw Python — run it directly, not inside a code block): ``` delegate_task( goal="Review this skill for publication readiness. Check: PII, hardcoded paths, factual accuracy, completeness, tone, clarity, safety, self-consistency. Be critical.", context="Skill at ~/.hermes/skills///", toolsets=["terminal", "file"] ) ``` **Bound the reviewer explicitly.** A report-only review subagent has terminal access and can reach side-effect CLIs (e.g. `hermes kanban complete`, `hermes cron create`). The child-context env guard on kanban CLI mutations is strippable (`env -u HERMES_DELEGATED_CHILD_CONTEXT`) and has been stripped in the wild — a reviewer once completed the task it was reviewing. Add to the reviewer's goal text: "You are report-only. Do NOT modify any file, do NOT run any `hermes` CLI command that mutates state (kanban, cron, config), and do NOT use env -u to bypass guards. Return findings only." Verify afterward by reading the live transcript tail if anything looks off. Address every finding before proceeding. If the reviewer flags something, fix it. If you disagree, explain why. Common issues to catch before the reviewer does: - `SKILL_DIR` used but not defined - Hardcoded paths anywhere - Pipe-to-interpreter patterns (`curl | python3`, `curl | tar`) — always download to file first - Model name recommendations - Dead references to non-existent files - Missing `mkdir -p` in setup commands - Description too long or self-contradicting advice ### Phase 5: Publish **Before publishing, run a safety scan** on the staged changes. A quick grep catches PII, hardcoded paths, and vendor-lock language that reviews can miss: ```bash git diff --cached | grep -qiE "(api_key|secret|token|password).*=.*['\"][a-zA-Z0-9_-]{20,}" && echo "WARNING: possible secret" git diff --cached | grep -qE "^\+.*/home/[^/]+/(?!\.hermes)" && echo "WARNING: hardcoded user path" git diff --cached | grep -qiE "model.*(required|must|should use)" && echo "WARNING: vendor-lock" ``` If any warnings fire, fix before pushing. This is cheap insurance — catching a leaked credential or environment-specific path before it hits a public repo. Then publish to GitHub: **Path A: `hermes skills publish` (preferred, needs fork scope)** ```bash hermes skills publish --to github --repo / ``` This requires a GitHub token with `repo` and `fork` scopes. Fine-grained tokens often lack fork permission — if you get "token lacks permission to fork repos", use Path B. **Path B: Direct git push (fallback)** ```bash # Clone the empty repo, copy skills in, push cd /tmp && gh repo clone / cp -r ~/.hermes/skills// /skills/ cd && git add -A && git commit -m "Add " git remote set-url origin git@github.com:/.git # use SSH git push origin main ``` SSH push bypasses token scope issues. Verify SSH works first: `ssh -T git@github.com` **Path C: Add to existing taps repo (most common)** When you already have a taps repo and are adding a new skill (or updating existing ones), clone, copy, update the README, and push: ```bash cd /tmp && gh repo clone / cp -r ~/.hermes/skills// /skills/ ``` Also copy any meta-skills you updated during the build (skill-builder, skill-research, etc.) — they live in the same taps repo: ```bash cp -r ~/.hermes/skills/hermes/skill-builder /skills/ ``` Then update the README to list the new skill with a one-paragraph description matching the format of existing entries. Add install instructions if this is a prerequisite for other skills. Finally: ```bash cd && git add -A && git commit -m "Add ; update meta-skills" git push origin main ``` This is the typical pattern: you're maintaining a growing collection, not creating a fresh repo per skill. **Post-publish (all paths):** - Add `hermes-skills` topic to the GitHub repo (Settings → Topics in web UI) - Also tag: `hermes-agent`, `agentskills` - Verify the skill appears in `hermes skills search` within 24 hours ## Skill Directory Layout ``` / ├── SKILL.md # Required — main skill document ├── scripts/ # Optional — Python/Bash scripts │ └──