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.
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.
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.
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>.
