SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillsrepo2skill

repo2skill

Agents & models

View repository

Updated 10-15 21:09

About this skill

repo2skill

The key words MUST, MUST NOT, SHOULD, SHOULD NOT and MAY in this skill are to be interpreted as described in BCP 14 (RFC 2119, RFC 8174) when, and only when, they appear in all capitals.

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.

Locating this skill's helpers (do this first). The steps below run bundled scripts. You execute from the target repo, not from this skill's directory, so a path written relative to this skill will not resolve. Resolve the base directory once and use it everywhere — including in any subagent prompt, which MUST receive the literal absolute path:

SKILL_DIR="<this skill's base directory>"   # your harness provides it when the skill loads
# If you don't have it, discover it:
SKILL_DIR=$(find ~/.claude ~/.config ~/.agents -type d -name 'repo2skill' 2>/dev/null | head -1)
test -d "$SKILL_DIR/assets" || test -d "$SKILL_DIR/scripts"   # verify before proceeding

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

Python interpreter. Most commands in this skill and its references are written with python3. Find the interpreter once, before the first of them. If $SKILL_PYTHON is set, use it. Otherwise, on macOS, if command -v python3 prints /usr/bin/python3 and xcode-select -p fails, that python3 is the install stub: skip it without running it. Use the first of python3, python and py -3 that is not skipped and for which <interpreter> -c 'import sys; sys.exit(sys.version_info < (3, 10))' exits 0. Write the interpreter you found in place of python3 in every command, and in any Bash(...) permission rule you suggest. Commands that start with uv run or {python} keep their own form. In a session resumed under a Bash(...) allowlist, skip this lookup and use the interpreter that the allowlist names. If none passes, follow this skill's own fallback for running without Python where it gives one; otherwise stop and tell the user that this skill needs Python 3.10 or newer.

  1. Scope the skill. Pin down, in a few lines: the kebab-case name (= directory name, ≤ 64 chars), the trigger surface (the kinds of request that should fire it, in the user's words, 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.
  2. Scaffold the skeleton. Run python3 "$SKILL_DIR/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.
  3. 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.
  4. 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.
  5. 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.

Output style. Write reports and explanations for the user in about 80% ASD-STE100 Simplified Technical English. Use short sentences, common words, active voice and one action per step. This style is for prose to the user, not for the code, prompts or files that this skill makes.

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.