scaffold-skill

name	scaffold-skill
description	Write, update, validate, and package agent skills inside an existing or new repository. Use when the user asks to scaffold a skill in a repo, write a SKILL.md, add references/scripts/assets by hand, create project-local .agents/skills entries, optionally add skills.sh/Claude/Codex packaging, or validate skill files before use or publishing.

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.

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:

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.

python3 <skill-root>/scripts/validate_skill_repo.py <repo-root> --strict-frontmatter

For a single skill directory, passing the skill directory path also works:

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:

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:

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