scaffold-skill

# Scaffold Skill Use this skill to write production-quality Agent Skills in the repository the user is working in. It is knowledge-only: read the instructions and references, inspect the repo, then create or edit the skill files in context. Hard rule: **This skill does not run a generator.** ## Existing skill content is read-only If the user already wrote the skill (an existing `SKILL.md`, references, scripts, or assets) and asked only for scaffolding, packaging, or validation, treat that content as final. Scaffold around it. - Do not rewrite, reword, "improve", or trim the user's `description`, frontmatter, or body — not even small edits. - Auditing is welcome: review the content, and report concerns or suggestions in the final response. - Only change existing skill content after the user explicitly approves a specific proposed change in this conversation. "Scaffold this" is not approval to edit. - If validation fails because of user-written content, report the failure and the suggested fix; do not apply it unasked. ## Source verification is for maintaining this skill `<skill-root>/scripts/verify_reference_facts.py` is for maintaining scaffold-skill itself against local `agentskills` and Vercel `skills` checkouts. It is not part of the normal workflow for scaffolding skills in user repos. When updating scaffold-skill's own references or making claims about packaging behavior, directory paths, frontmatter constraints, plugin manifest fields, or install commands, verify against current source when available: ```bash python3 <skill-root>/scripts/verify_reference_facts.py ``` The verifier auto-discovers sibling checkouts when possible. If auto-discovery fails, pass local paths explicitly with `--agentskills <path>`, `--vercel-skills <path>`, and repeatable `--production-repo <path>`. If sources are unavailable, say what could not be verified, then use the bundled references as a fallback. Do not invent undocumented client-specific behavior. ## Workflow 1. **Clarify context.** Ask only for missing essentials: whether the skill belongs in an existing repo or a new repo, whether it is local-only or intended for publishing, the skill name, concrete trigger prompts, desired output, and whether references/scripts/assets are needed. 2. **Inspect the repo first.** Look for existing skills, `README.md`, plugin directories, package metadata, and `.agents/skills/`. Use the current repo's conventions when they are clear. Never overwrite existing files unless the user explicitly asks. 3. **Read the right references before writing.** - Read `references/portable-skill-format.md` for `SKILL.md` and resource rules. - Read `references/in-repo-scaffolding.md` for placement and safe file creation in user repos. - Read `references/repo-architecture.md` for repository layouts. - Read `references/distribution-targets.md` only when the user wants publishing or plugin packaging. - Read `references/quality-gates.md` before finalizing descriptions, scripts, references, or evals. - Read `references/production-examples.md` when choosing between layouts or metadata patterns. - Read `references/verification-process.md` only when maintaining scaffold-skill references. 4. **Write files by hand in the repo.** Create only the files needed for the requested scope. For a project-local skill, this is usually `.agents/skills/<name>/SKILL.md`. For a repo that ships skills, this is usually `skills/<name>/SKILL.md` plus optional `references/`, `scripts/`, `assets/`, and `agents/openai.yaml`. 5. **Validate correctly.** Use `<skill-root>/scripts/...` paths because agents may be running from the target repo, not from this skill directory. ```bash python3 <skill-root>/scripts/validate_skill_repo.py <repo-root> --strict-frontmatter ``` For a single skill directory, passing the skill directory path also works: ```bash python3 <skill-root>/scripts/validate_skill_repo.py <repo-root>/.agents/skills/<name> --strict-frontmatter python3 <skill-root>/scripts/validate_skill_repo.py <repo-root>/skills/<name> --strict-frontmatter ``` Only pass packaging targets that were actually created: ```bash python3 <skill-root>/scripts/validate_skill_repo.py <repo-root> --targets vercel --strict-frontmatter python3 <skill-root>/scripts/validate_skill_repo.py <repo-root> --targets claude --strict-frontmatter python3 <skill-root>/scripts/validate_skill_repo.py <repo-root> --targets codex --strict-frontmatter ``` Never run `--targets vercel,claude,codex` for in-repo-only work unless all those manifests exist; the validator correctly exits 1 when requested target manifests are missing. If Vercel packaging was added and the CLI is available, smoke-test discovery and install: ```bash npx skills add <repo-root> --list npx skills add <repo-root> -y ``` `npx skills add` is the documented install command. The CLI also accepts `install` as an alias for `add`. `experimental_install` only restores from `skills-lock.json`. 6. **Report what happened.** List files created, existing files skipped, validation run or skipped, and any remaining manual steps. For publishable repos, include the copy-paste install block from `README.md` (see `references/distribution-targets.md`). ## Defaults that prevent common mistakes - Keep portable `SKILL.md` frontmatter strict: `name`, `description`, and only spec fields such as `license`, `compatibility`, `metadata`, or `allowed-tools` when needed. - Do **not** put client-specific invocation flags such as `disable-model-invocation` into a portable/public skill unless the user intentionally accepts client-specific validation failures. For Codex, prefer `skills/<skill>/agents/openai.yaml` with `policy.allow_implicit_invocation: false` for explicit-only skills. - Put all trigger logic in the frontmatter `description`; a body section titled “When to use” is too late for automatic activation. - Keep `SKILL.md` lean and procedural. If the file approaches 500 lines or mixes unrelated variants, split details into `references/` and say exactly when to read each reference. - Include `--help`, noninteractive flags, structured stdout, useful stderr, and idempotent/dry-run behavior in bundled scripts. - Create packaging metadata from the actual skill, not from placeholders. Plugin manifests must not contain `[TODO: ...]` values. - Publishable skill repos must ship a root `README.md` with an `## Install` section whose first command is `npx skills add owner/repo` (no `--skill` flag when the repo has one skill). Verify against `vercel/skills` when local source is available. ## Completion checklist Before final response, confirm: - [ ] Every created skill directory has `SKILL.md` with matching lowercase kebab-case `name`. - [ ] Every description says what the skill does and when to use it. - [ ] Referenced `scripts/`, `references/`, `assets/`, and `agents/openai.yaml` paths exist. - [ ] No existing files were overwritten unless the user explicitly asked. - [ ] User-written skill content is byte-identical unless the user approved a specific edit; audit findings were reported instead of applied. - [ ] `skills.sh.json` references real skill names if created. - [ ] `.claude-plugin/plugin.json` skill paths resolve if created. - [ ] `.codex-plugin/plugin.json` and `.agents/plugins/marketplace.json` are internally consistent if created. - [ ] Validation commands have run, or any skipped validation is explicitly explained. - [ ] Publishable repos have `README.md` with `## Install` and a working `npx skills add owner/repo` one-liner (smoke-tested with `--list` or `-y` when the CLI is available).