Superpowers Writing Skills: The Skill That Teaches Agents to Author Skills

A Skill Library Grows by Writing Skills

Everything an agent does well across long-lived sessions — the debugging methodology it actually follows, the verification habits it refuses to skip, the plan format it sticks to — exists because someone wrote that procedure down as a skill and proved an agent would follow it. The Superpowers library is a dozen-plus such procedures, and none of them fell out of the sky. They were authored, tested, and revised. The library even has a skill for the authoring: the superpowers writing skills skill.

writing-skills is the meta-skill behind the meta-skills. If using-superpowers decides when knowledge gets loaded, writing-skills decides what is worth writing, how it should be structured, and how you prove it works. Its core principle is deliberately blunt:

If you didn't test the skill with a real scenario,
you don't know if it teaches the right thing.

That is test-driven development aimed at documentation. This article is a tour of what that means: the file format, the testing loop, the token budgets, and two real jobs — writing superpowers-infra from scratch, and repairing the fourteen skills we imported from the original Superpowers collection.

What the writing-skills Skill Actually Does

The skill fires in three situations, and they are genuinely different jobs:

• Creating new skills. A technique has proven itself and deserves to become a permanent, reusable reference guide.
• Editing existing skills. A loophole was found, a step proved wrong, a new edge case appeared — the skill file gets the same care as a code change.
• Adapting external content. Skills written for another agent harness (or documentation that almost qualifies) get rewritten into a form this agent will actually follow.

Before any of those, the skill enforces a definition that kills most bad proposals on the spot: skills are reusable techniques, patterns, tools, and reference guides; skills are not narratives about solving one specific problem. The distinction matters because the failure mode is so common. An agent solves a gnarly problem, gets excited, and writes a skill titled “Fixing the SYNAS Docker network” — a war story with dates, dead ends, and victory laps. Nobody else’s task will ever match that story, so the skill never fires again. What was reusable inside the story — the diagnostic pattern, the command set — is what should have been extracted.

So the skill ships a two-sided gate. Create a skill when the technique wasn’t intuitively obvious, you’d reference it again across sessions or projects, and the pattern applies broadly. Don’t create one for one-off solutions, standard practices already documented elsewhere, or project-specific conventions — those belong in the project’s .hermes.md, not in a library meant to outlive the project.

The Anatomy of a Skill: SKILL.md, Frontmatter, and metadata.hermes

A skill is one directory and one required file, plus supporting material only when the budget forces it out:

skills/<category>/<skill-name>/
  SKILL.md              # Main reference (required)
  supporting-file.*     # Only if needed

SKILL.md opens with YAML frontmatter — the part the skill index actually reads — followed by a predictable section order:

---
name: skill-name
description: Use when [specific triggering conditions]
version: 1.0.0
author: Hermes Agent
license: MIT
category: software-development
metadata:
  hermes:
    tags: [relevant, search, terms]
    related_skills: [other-skill-names]
---

# Skill Name

## Overview            Core principle in 1-2 sentences.
## When to Use         Symptoms; also when NOT to use.
## Core Pattern        Steps, before/after, the technique.
## Hermes Agent Integration
## Quick Reference     Table or bullets for scanning.
## Common Mistakes     What goes wrong + fixes.

Four frontmatter rules carry most of the weight:

• name — letters, numbers, and hyphens only. It is an identifier, not a title.
• description — must start with “Use when…” and state only triggering conditions.
• metadata.hermes.tags — the terms a future agent would search for when this skill applies.
• metadata.hermes.related_skills — the skills that pair with this one, so the index can lead from one to the next.

The metadata.hermes block is the Hermes-specific adaptation layer. The core fields keep a skill portable across agent products; tags and related_skills are what Hermes’s two-level discovery system (always-visible one-line index, full body on demand) uses to match a task to the right file.

The description rule has a reason, and the skill states it as an explicit anti-pattern:

# BAD: summarizes the workflow — the agent may follow
#      the description instead of reading the skill
description: Use for debugging — gather evidence,
             form hypothesis, test minimally

# GOOD: trigger only — the agent reads the skill for process
description: Use when encountering any bug, test failure,
             or unexpected behavior

This is a lazy-loading problem in disguise. A description that summarizes the procedure tempts the agent to act on the summary and skip the file — executing a ten-word paraphrase of a skill it never loaded. A trigger-only description makes reading the skill the only way to learn the process, which is exactly where the tested detail lives.

Real Example: superpowers-infra and the Fourteen Imported Skills

Both sides of the skill — creation and adaptation — got exercised recently on the same infrastructure work. superpowers-infra began as a real Docker audit of SYNAS, one of our always-on OpenMediaVault boxes: containers behind a drop-only SSH lock, game servers, Plex, a bonded NIC nobody wants to touch. The audit produced findings the agent kept re-deriving from scratch — orphaned volumes left by container renames, writable-layer bloat with no volume mount, host-driver containers that legitimately bypass network isolation. Classic “would reference this again across sessions” material, so it became a skill:

---
name: superpowers-infra
description: Use Superpowers skills for Docker, server
  and network tasks.
metadata:
  version: 1.0.0
  author: cisco (Tetris)
  tags: [superpowers, docker, infrastructure, devops]
  related_skills: [superpowers-executing-plans,
    superpowers-dispatching-parallel-agents]
---

The body is pure reference, not war story: a mapping table from each Superpowers skill to its infra use (dispatching-parallel-agents becomes “check all containers/servers/services simultaneously”; verification-before-completion becomes “run a fresh docker ps before claiming results”), the exact Docker format-strings worth keeping verbatim, and the resource thresholds learned the hard way on that box.

The adaptation job was bigger. The original Superpowers collection — fourteen skills — was written for Claude Code. Installed as-is into Hermes, they half-worked: the skills loaded, but discovery and dispatch didn’t. Running writing-skills over each of the fourteen produced the same repair checklist every time:

That is the third job of the skill in action: external content is raw material. The methodology inside the fourteen files was excellent and stayed intact; everything around it — naming, frontmatter, triggers, tool names — got rewritten until the skills behaved natively.

Testing a Skill: Baseline, Write, Test, Refine

Here is where skill authoring stops being writing and becomes engineering. The creation checklist is a RED–GREEN loop with an extra step at each end:

1. Baseline. Run the scenario without the skill. Document the choices the agent made, the rationalizations it used, and where it went wrong.
2. Write. Draft the skill against those specific recorded failures — not against the hypothetical problem you imagined.
3. Test. Run the same scenario with the skill loaded. Verify the agent now follows the process.
4. Refine. Close every loophole the test run found.
5. Deploy. Place the file at skills/<category>/<name>/SKILL.md.

The baseline step does double duty. It proves the skill is needed at all — if the agent already behaved correctly without it, there is nothing to write — and it hands you the exact language to argue against. The rationalizations collected in step one become the rebuttals in step four. That is why discipline-enforcing skills like TDD and verification carry rationalization tables and red-flag lists: every row is a real excuse collected from a real baseline run under pressure, then explicitly closed. The skill is blunt about the categories that need this treatment: for any skill that enforces a rule rather than teaching a technique, test with pressure scenarios and shut each escape hatch by name, because an unclosed loophole is a loophole the model will eventually find.

Seen from next door, this is the test-driven-development skill re-applied one level up: the baseline run is RED (the agent fails without the skill), the tested rewrite is GREEN, and refinement is refactor. The skill even says so in its closing line: skills are tested documentation — same rigor as code: test first, iterate, keep concise.

Token Efficiency: Every Word Costs Every Session

Skills are not read once and shelved. A skill loads into every conversation where it’s relevant, competing with the user’s actual task for context window. So writing-skills imposes hard word budgets instead of leaving brevity to taste:

• Getting-started skills: under 150 words. These load constantly; every sentence is priced in nearly every session.
• Frequently-loaded skills: under 200 words.
• Everything else: under 500 words.
• Heavy reference moves to separate files that load on demand — the same two-level trick the index itself uses.
• One excellent example beats many mediocre ones.

The budgets are where taste and arithmetic meet. Our superpowers-infra skill is the cautionary tale: the audit was rich, so the draft grew well past 500 words with command dumps and threshold tables inline. By the skill’s own rule, that material is exactly what belongs in a references/ file — SKILL.md keeps the workflow and the mapping table, and the 200 lines of Docker incantations load only when a container is actually on fire. Word counts are not pedantry; they are the price of admission to every future context window.

The Skills That Pair With It

The frontmatter of writing-skills names its two companions, and the pairing is symmetrical. The test-driven-development skill is both the template for the baseline-test-refine loop and one of the skills most in need of it: TDD is precisely a discipline-enforcing skill, the kind the writing guide says must be pressure-tested with rationalization tables, because the excuse “I’ll just write the test after” is the most reliable failure in software. The brainstorming skill sits at the other end of the pipeline: it is where designs get interrogated and decisions get reasons attached — which is exactly the raw material a skill needs, since a skill that records why a step exists is one agents stop rationalizing around.

The loop closes naturally. Brainstorming and executing real work surfaces the techniques worth keeping; writing-skills turns them into tested reference guides; the bootstrap loads them into the next session; and the next session ends with new findings worth writing down. The library isn’t a static bundle — it’s a workflow with a memory.

Related Deep Dives in the Series

In the Superpowers deep-dive series, writing-skills is the maintenance layer: the using-superpowers bootstrap routes work to skills, process skills like brainstorming and test-driven development carry it out, and writing-skills is what lets the library improve itself — one tested, token-budgeted SKILL.md at a time.