Skill Author

skill-author

The meta-skill that governs how every other robium skill gets born, mined, and hardened. It is the repo's authoring machinery: it enforces the quality bar defined in the design spec, runs the repo-level validator, and describes the three ways skill content enters the catalog — fresh authoring, mining from existing repos, and hardening from post-trial learnings.

When to use this skill

• Creating a brand-new skill under skills/<name>/ from the template.
• Extracting reusable patterns out of an existing repo (an official demo repo, or an app built without robium) into a new or existing skill.
• Consuming learnings/YYYY-MM-DD.md files written during app-building sessions and folding them back into the affected skills.
• Auditing an existing skill against the quality bar, or running the validator before a commit.
• Tuning a skill's frontmatter description for better trigger accuracy, or evaluating whether a skill fires on the phrasing it should.
• Cross-reference: for building an actual robotics application (choosing a stack, scaffolding a repo), use the architect skill and the domain skills it routes to instead — this skill only edits skills, never application code.

Key directives

• Delegation posture: embed. This skill owns the authoring workflow outright; there is no good upstream skill for "how to write a robium skill," so the process lives here rather than being linked out.
• Knowledge goes to the lowest skill that can hold it — a Nav2 costmap gotcha belongs in nav2, not architect; a ROS 2 launch-file quirk belongs in ros2, not a per-tool skill built on top of it. Never park knowledge one level higher than where it will actually be looked up.
• Recurrence rule: anything appearing twice across learnings notes becomes a skill edit immediately — do not wait for a third occurrence.
• Every absorbed learning adds one dated line to the ## Changelog section of the skill it changed. No silent edits during hardening.
• Always run scripts/validate_skills.py before committing any skill change — fresh, mined, or hardened. A skill that fails the validator is not done.
• For eval design and description-wording tuning, wrap Claude's own skill-creator skill rather than reinventing evals or trigger-testing machinery. skill-author supplies the robium-specific quality bar and workflow; skill-creator supplies the generic eval tooling.

Quick start

Mode 1 — Fresh authoring (new skill from scratch):

1. cp -r skills/_TEMPLATE skills/<new-skill-name>, rename the dir to match the intended name:, and rename SKILL.template.md to SKILL.md (the template file is deliberately not named SKILL.md so plugin discovery never exposes the skeleton as an installable skill).
2. Research the upstream tool/library docs and examples for the domain the skill covers.
3. Fill every template section — frontmatter description (capability summary, Use when: triggers, literal keywords, workflow-position marker, Not for: negative scope), ## Key directives (state the delegation posture explicitly), ## Quick start, ## Decision guidance or ## Usage patterns, ## Platform gotchas, ## Customization, ## References (local files plus upstream links).
4. Run uv run skills/skill-author/scripts/validate_skills.py and fix any FAIL: lines.
5. Commit.

Mode 2 — Mining (extract patterns from an existing repo):

1. Read the target repo (an official demo repo, or an app built without robium) end to end — configs, launch files, Dockerfiles, glue code.
2. List candidate patterns: anything that recurs across the repo, or that was clearly a hard-won config (nonobvious values, workarounds, ordering requirements).
3. Map each candidate to the lowest existing skill that can hold it; if no skill fits, that's a signal to create one (Mode 1).
4. Edit the target skill(s) — add a reference file, a ## Quick start snippet, or an examples/ file (see references/mining-guide.md).
5. Run the validator, then commit.

Mode 3 — Hardening (post-trial learnings absorption):

1. Read learnings/*.md in the application repo that isn't yet marked absorbed.
2. Group entries by which robium skill each one implicates.
3. Edit each implicated skill: fix wrong/missing guidance, refresh stale samples, add a section where a skill should have fired but didn't.
4. Add a one-line dated entry to that skill's ## Changelog.
5. Mark each absorbed learning by appending <!-- absorbed: YYYY-MM-DD --> to its line in the learnings file.
6. Run the validator, then commit.

Decision guidance

• New skill vs. deepen an existing one vs. add a reference file — ask in this order:
  1. Does an existing skill already own this domain (same tool, same decision point)? If yes, the content is an edit to that skill, not a new one.
  2. Within that skill, is the content core to the common path (belongs in SKILL.md itself, under ## Quick start/## Decision guidance) or a deep dive only some callers need (belongs in a new or existing file under references/)?
  3. Only create a brand-new skill when the content is a genuinely distinct decision point or tool with its own trigger surface — e.g. nav2 vs gazebo are separate skills because they're separate tools with separate "when do I load this" questions, even though both feed the nav vertical.
  4. If the new content would push a skill's SKILL.md body toward the 500-line cap, that's a signal to push the next addition into references/ rather than growing the body further — don't wait until the validator fails.
• Body snippet vs. examples/ file — a snippet belongs directly in SKILL.md (## Quick start or ## Decision guidance) when it is short (a handful of lines), generic across the skill's common cases, and needed on the most common path. It belongs in examples/ instead when it is a fuller file (a whole launch file, a multi-service Dockerfile/compose file, a full config) that callers copy and adapt rather than read inline — those get a one-line reference from ## References plus a verified/unverified status marker (see references/quality-bar.md).

Platform gotchas

• None specific to this skill — it edits Markdown and runs a uv-managed Python script, which behaves the same on macOS and Linux. Per-skill platform gotchas belong in the skill being authored, not here.

Customization

• The three modes are process, not code — there is nothing to template beyond the skeleton in skills/_TEMPLATE itself. When robium's quality bar changes (a new required section, a new constraint), update REQUIRED_SECTIONS/checks in scripts/validate_skills.py, the _TEMPLATE skeleton, and references/quality-bar.md together — the three must never drift apart.
• If a project forks robium and wants a stricter or looser bar (e.g. a 600-line cap, or an extra required ## Safety section), edit the validator's constants and the checklist in lockstep, then re-run it against every skill in the catalog to see what breaks.

References

• references/quality-bar.md — the full per-skill checklist enforced by the validator and by hand during review, with a one-line "how to check" per item.
• references/learnings-loop.md — the operational loop connecting app sessions (writing learnings/) to hardening sessions (absorbing them).
• references/mining-guide.md — how to recognize a reusable pattern in an existing repo, trim it into a skill asset, and place it correctly.
• scripts/validate_skills.py — the repo-level validator; run it before every commit that touches skills/.
• Upstream: Claude's built-in skill-creator skill (evals, description tuning), the agentskills.io convention this format follows, docs/superpowers/specs/2026-07-10-robium-plugin-design.md section 5 (the design source for this skill).

Changelog