| name | repo2skill |
| description | Extracts a reusable code pattern from the current repo and authors a portable, validated Agent Skill. Use when you want to capture a logging setup, CI/CD pipeline, observability stack, async messaging pattern, frontend component library, feature-flag middleware, or any other repeatable engineering pattern so it can be replayed across other repos. Produces: a standard-conformant SKILL.md, parameterized code templates in assets/templates/, a PARAMETERS.md documenting every placeholder, then runs validate-skill.sh, scan-leaks.sh, and dry-run-replay.sh as a tiered quality gate. Output is ready to publish via references/publishing.md. |
| x-spec-version | 1 |
repo2skill
Reads the current repo, identifies a reusable code pattern, generalizes every
repo-specific identifier into {{UPPER_SNAKE}} placeholders, and authors a
portable Agent Skill that passes a full tiered quality gate.
When to use
Use when:
- You spot a pattern (logging, observability, CI/CD, async messaging, feature
flags, frontend scaffolding, auth middleware, etc.) worth capturing.
- A teammate asks "how did you set up X?" and you want a replayable answer.
- You are migrating the same pattern across multiple repos.
- You want to publish a skill others can install with
npx skills add.
Decision flow
Is the pattern named by the user?
├── Yes → Stage 1 (Target): bound it, confirm, proceed.
└── No → Stage 0 (Mode select): scan repo, propose candidates.
Does the pattern span independently-usable concerns?
├── No → Single skill.
└── Yes → Coordinated skillset (INDEX.SKILL.md + per-concern SKILL.md).
See references/extraction-playbook.md §Phase 2.
Quality gate result?
├── PASS → Stage 6 (Publish).
└── FAIL → Loop back to Stage 3 (Generalize) and fix.
Stage 0 — Mode select
Auto-discover: scan repo for recurring, self-contained patterns. Propose
up to five candidates (name, one-line rationale, key files). Await user choice.
User-directed: user names the pattern or supplies paths. Skip to Stage 1.
Stage 1 — Target
Produce a Pattern Brief:
| Field | Content |
|---|
| Name | kebab-case skill name |
| Problem | What it solves |
| In scope | Files / dirs that implement the pattern |
| Out of scope | Business logic, unrelated config |
| Entry point(s) | Files a consumer copies first |
| Dependencies | Packages, env vars, system tools |
| Consumer steps | What a new repo must do to reproduce |
Get explicit user confirmation before authoring. If uncertain about scope,
ask one clarifying question.
Stage 2 — Analyze
Map the pattern's structure. Apply the single-skill vs. skillset decision tree
(see references/extraction-playbook.md §Phase 2).
- Single skill → one
SKILL.md + one PARAMETERS.md.
- Coordinated set →
assets/templates/skillset/INDEX.SKILL.md.tmpl as the
orchestrator; each member uses assets/templates/skill/SKILL.md.tmpl.
Stage 3 — Generalize
Replayability invariant: skill + PARAMETERS.md alone must reproduce the
pattern in a clean repo, with zero reference to this source repo.
- Replace every repo-specific identifier with
{{UPPER_SNAKE_CASE}}.
See references/extraction-playbook.md §Phase 3 for the full list
(service names, hostnames, ports, paths, org names, image registries,
version pinnings, env var names).
- Document every
{{PLACEHOLDER}} in PARAMETERS.md per the table format
in references/agent-skills-spec.md.
- Build a denylist file listing all actual source values (not placeholder
names) — used in Stage 5 by
scripts/scan-leaks.sh.
- Fill the templates in
assets/templates/skill/SKILL.md.tmpl and
assets/templates/skill/PARAMETERS.md.tmpl.
- Self-review against
references/authoring-rules.md before proceeding.
Stage 4 — Author
Populate the generated skill directory:
<skill-name>/
├── SKILL.md ← from assets/templates/skill/SKILL.md.tmpl
├── PARAMETERS.md ← from assets/templates/skill/PARAMETERS.md.tmpl
└── assets/templates/
└── <concrete-files> ← parameterized copies of the source files
Rules (see references/authoring-rules.md for the full checklist):
- Imperative second-person voice. No preamble.
- Description starts with a verb, states WHAT and WHEN, ≤1024 chars.
x-spec-version: 1.0 in frontmatter.- No dangling
references/, assets/, or scripts/ paths in the body.
- Progressive disclosure: deep material →
references/; keep SKILL.md lean.
Stage 5 — Validate (tiered quality gate)
Run gates in order. Each is a hard gate unless noted.
Gate 1 — Structural + bijection + spec-version (HARD GATE)
scripts/validate-skill.sh <skill-dir> --spec references/agent-skills-spec.md
Must print VALIDATION_RESULT: PASS. On failure, return to Stage 3.
Gate 2 — Leak scan (HARD GATE — any leaked secret is an unconditional fail)
scripts/scan-leaks.sh <skill-dir> --denylist <denylist-file>
Must print SCAN_RESULT: PASS. Any finding is a hard fail; fix in Stage 3.
See references/extraction-playbook.md §Phase 4 for denylist procedure.
For documented false positives only (e.g. regex literals in tooling), add
# scan-leaks:ignore on the specific line — reviewed in Stage 5; never used
to suppress real credentials.
Gate 3 — LLM self-review
Review the generated skill against references/authoring-rules.md.
Report findings; user may waive with documented justification.
Gate 4 — Dry-run replay
scripts/dry-run-replay.sh <skill-dir> <scratch-dir>
Must print DRY_RUN_RESULT: PASS. Then have a fresh agent reproduce the
pattern from ONLY the skill output. User may accept with documented exceptions.
Definition of done: all four gates complete; user has reviewed output.
Stage 6 — Publish
Follow references/publishing.md. Emit ready-to-run commands for the user.
Never auto-push. The user reviews and runs every command.
Channels: GitHub (npx skills add <owner>/<repo>), skills.sh registry,
plugin marketplace. See references/publishing.md for full procedure and
pre-publish checklist.
Graceful degradation (no shell available)
If a shell is unavailable, each gate can be performed manually:
| Gate | Manual equivalent |
|---|
Gate 1 (validate-skill.sh) | Check: SKILL.md exists; frontmatter --- delimiters; name is kebab-case ≤64 chars; description non-empty ≤1024 chars; every references//assets//scripts/ path in body exists; {{}} tokens in templates match PARAMETERS.md rows exactly. |
Gate 2 (scan-leaks.sh) | Grep each template and doc file for AWS keys, GitHub tokens, PEM headers, and every denylist identifier. |
| Gate 3 (LLM review) | Work through references/authoring-rules.md checklist line by line. |
Gate 4 (dry-run-replay.sh) | Manually substitute PARAMETERS.md Example values into each template; confirm no {{}} remain. |
Packaging (package-skill.sh) | List the skill's files for a manifest and archive the directory by hand, e.g. tar czf <skill-name>.tar.gz <skill-dir>. |
Reference index
| File | Purpose |
|---|
references/agent-skills-spec.md | Canonical spec (v1.0): required fields, layout, bijection invariant |
references/extraction-playbook.md | Phase-by-phase extraction procedure |
references/authoring-rules.md | Quality checklist for generated skills |
references/publishing.md | Distribution channels and pre-publish checklist |
scripts/validate-skill.sh | Structural + bijection + spec-version validator |
scripts/scan-leaks.sh | Secret + denylist leak scanner |
scripts/dry-run-replay.sh | Substitutes PARAMETERS.md examples into templates; checks residuals |
scripts/package-skill.sh | Manifest + optional tarball builder |
assets/templates/skill/SKILL.md.tmpl | SKILL.md template for generated skills |
assets/templates/skill/PARAMETERS.md.tmpl | PARAMETERS.md template |
assets/templates/skillset/INDEX.SKILL.md.tmpl | Index template for coordinated skillsets |
