| name | repo2skill |
| description | Scaffold, author, and review a new gate-passing Agent Skill for this repo (or any repo vendoring its quality gates): generate a standards-complete skeleton, write the real prompt over it, run the semantic review the mechanical gates cannot, and iterate the gates to green. Use when someone says "create a new skill", "add a skill to agent-skills", "scaffold a SKILL.md", "make my skill pass the gates", or "review this SKILL.md for prompt quality". Not for auditing whether a whole repo is ready for coding agents — use agent-ready-rails; not for fact-checking a codebase's claims — use base-in-reality; not for designing or repairing a single agent loop — use crafting-self-prompting-loops. |
| license | MIT |
| compatibility | Requires python3 (stdlib only, offline) plus make and a POSIX shell for the gate loop. Built for this repo's layout — the quality gates under scripts/gates were vendored from this skill — but the scaffolder runs anywhere python3 does. |
| metadata | {"author":"dhanesh","version":"1.0.0","tags":"agent-skills,skill-authoring,scaffolding,prompting-playbook,quality-gates,code-review"} |
repo2skill
The authoring skill this repo's quality gates were vendored from. It turns "I want a new
Agent Skill" into a directory that passes make gate-skill — by scaffolding a skeleton
that is already green, guiding the real authoring over it, and finishing with the
semantic review that mechanical gates cannot perform. Author under gate cover: start
green, stay green, and let every red check tell you exactly what to fix.
When to use
Reach for this when the job is making or reviewing a skill: "create a new skill for
X", "scaffold a SKILL.md", "why does my skill fail the gate?", "review this skill's
prompt quality". The boundaries: auditing whether a whole repo is safe for coding
agents is agent-ready-rails; verifying a codebase's claims against authoritative
sources is base-in-reality; designing or debugging one agent loop is
crafting-self-prompting-loops. This skill owns the narrower loop of one skill
directory versus this repo's standard.
What the gates enforce — and what they can't
make gate-skill SKILL=<dir> runs the repo's whole verify loop: structure and
frontmatter validation (SKILL.md + README.md, kebab name ≤ 64, description ≤ 1024,
no dangling references//assets/ paths, template↔PARAMETERS.md bijection), secret
scanning, the Prompting Playbook lints (PP-1…PP-6, see docs/prompting-playbook.md),
the standard-metadata check, each unit-test suite shipped under assets/, and the outcome eval per
docs/eval-standard.md. All of that verifies presence. Substance — whether the
sections are orthogonal, the deliverable is a real contract, each absolute is justified
— is the reviewer's job, and the checklist for it is
references/semantic-review.md.
Workflow
- Scope the skill. Pin down, in a few lines: the kebab-case name (= directory
name, ≤ 64 chars), the trigger surface (the phrasings a user would actually say,
which become the description), the named deliverable, and the boundaries against
sibling skills — which adjacent jobs this skill refuses and who owns them. If the
promise or the deliverable can't be stated in one sentence each, the skill isn't
scoped yet.
- Scaffold the skeleton. Run
python3 assets/scaffold_skill.py <name> --dir <repo-root> (flags:
--author, --version, --tags). It refuses invalid names and existing
directories, and generates SKILL.md (standard frontmatter + a body shaped to pass
the structural gates, with TODO(repo2skill) markers), README.md, a
references/ stub, a runnable smoke-test suite, and an eval stub conforming to
docs/eval-standard.md. Confirm the fresh skeleton is green with
make gate-skill SKILL=<name> before touching it.
- Author the real content. Replace every
TODO(repo2skill) marker following
references/authoring-guide.md: description recipe,
body conventions, growing the smoke test into a real suite, and replacing the eval
stub's contract-surface checks with an end-to-end harness → grader eval that keeps
a negative fixture. Re-run the gate after each file so a regression points at the
edit that caused it.
- Run the semantic review. With the gate green, work through
references/semantic-review.md against the finished
SKILL.md — the substance behind each mechanical proxy, plus the description-trigger
and eval-honesty rows. Fix what the review finds, or record why a finding is kept.
- Verify and repair until green. From the repo root:
make gate-skill SKILL=<name>, then make gate for the whole repo. On any FAIL line, fix the named
check and re-run; finish only when both are green and
grep -rn "TODO(repo2skill)" <name>/ returns nothing.
Deliverable
A complete skill directory — SKILL.md, README.md, references/, assets/ with
its test_*.py suite, eval/run_eval.py — that exits green from
make gate-skill SKILL=<dir>, plus a short semantic-review note (findings and how
each was resolved or why kept) for the PR description. The repo's PR template has a
checklist item pointing at the review.
Verifying this skill itself
repo2skill eats its own cooking: assets/test_scaffold_skill.py unit-tests the
scaffolder (name refusal, skeleton completeness, determinism, overwrite refusal), and
eval/run_eval.py scaffolds a demo skill into a tempdir and runs the repo's real gate
scripts against it — including the negative fixtures (a Bad_Name scaffold is
refused; a scaffold with README.md deleted fails validation). Both run as part of
make gate-skill SKILL=repo2skill.
