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:

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