Skill build wizard

skill-build-wizard — End-to-End Skill Building Workflow

• Version: 1.0.0
• License: MIT
• Author: Evan Song · github.com/Songhonglei
• Repository: https://github.com/Songhonglei/build-better-skills
• Part of: build-better-skills suite — see Stages for the lifecycle map.

A guided workflow that walks users through building production-quality agent skills. Unlike skill-creator (a technical reference written for AI), this wizard is written for the user — it sequences the work into 4 stages and pauses for confirmation at each handoff so nothing important gets skipped.

Usage

When a user says "build a skill" / "做个 skill" / "skill-build-wizard", execute the four stages in order. Wait for user confirmation before advancing to the next stage.

---

Stage 1: Pre-flight checks (skippable)

Goal: Make sure the workspace is ready, avoid rework later.

Skip rules: The user can skip this stage or any individual check at any time, no explanation required.

• Skip all: user says "skip pre-flight" / "skip" / "no checks" → jump to Stage 2
• Skip specific: user says "skip git check" → skip just that item, run the rest
• On warnings/failures: report the result, then proactively ask "continue or fix first?" — never force a fix.

Run the pre-flight script (auto-locates the skill directory, supports --skip):

# Auto-locate the script (works under common locations)
SKILL_DIR=$(find "$HOME/.openclaw/workspace/skills" "$HOME/.claude/skills" /app/skills \
  -maxdepth 1 -name "skill-build-wizard" -type d 2>/dev/null | head -1)
bash "${SKILL_DIR}/scripts/pre-check.sh"

# Skip examples:
# bash "${SKILL_DIR}/scripts/pre-check.sh" --skip git
# bash "${SKILL_DIR}/scripts/pre-check.sh" --skip all

The script checks one thing and prints two general recommendations (see references/checklist-before-start.md):

1. Workspace Git — version-track your work so you can undo any mis-edit
2. (Recommendation) Long-running task tolerance — ensure your agent/IDE won't time out mid-build
3. (Recommendation) Cross-session continuity — have a way to recover or reload the conversation context if it gets dropped

Outcomes:

• ✅ All pass → proceed to Stage 2
• ⚠️ Warning → tell the user, ask "continue or fix first?", honor their choice
• ❌ Failure → suggest a fix, ask "continue or fix first?", honor their choice

---

Stage 2: Spec clarification → confirmation

Goal: Align on requirements and design before writing any code.

Three musts:

1. Must use skill-creator for scaffolding — say to the user: "I'll call skill-creator to build this skill", don't roll your own.
2. Must give a complete design and wait for user confirmation before coding — the design includes: skill purpose, directory structure, list of scripts/references/assets, trigger phrase design.
3. Must avoid local dependencies — no fixed paths (e.g. /home/me/...), no machine-specific env vars, no local DB endpoints.

Question pacing (ask in small batches, not a 10-question list):

• What problem does this skill solve? How will users trigger it?
• Can you give one or two concrete usage scenarios?
• Does the skill need external APIs or local file access?

After the design is confirmed, before coding, optionally save the design:

• Save to any markdown / docs system you use (your team wiki, Confluence, Notion, a local DESIGN.md file in the project, etc.) — this is optional and non-blocking.
• Document title: "[Skill name] — Design"
• Content: skill purpose, directory structure, scripts/references/assets list, trigger phrase design.
• If save fails or the user prefers not to save, proceed to coding directly (no need to block the flow).
• Tell the user: "Design confirmed. Starting code now; will run quality checks when done."

---

Stage 3: Coding acceptance

Goal: Don't carry bugs into the release stage.

See references/checklist-coding.md for the full checklist. Run four checks in order:

1. Design alignment — verify every functional point against the agreed design
2. Edge cases — empty input / API failure / file-not-found / dependency missing, etc.
3. Code + doc review (2 passes) — Pass 1: script stability (set -e traps, missing external commands, numeric guards, hardcoded paths, pipe safety) + SKILL.md doc quality (paths, fallback logic, references usage, trigger coverage); Pass 2: from the "first-time stranger user" perspective, walk the flow end-to-end and find dead ends.
4. Smoke tests (2 passes) — direct script run + end-to-end functional test, with real output as evidence.

Gate: All four must pass before advancing. Fix issues then re-run the affected items.

Before advancing to Stage 4, clean up build artifacts (avoid shipping temp files in the release package):

• Move any smoke-test scripts / logs / fixtures to a temp dir or delete them. Do not leave them in the skill directory.
• The skill directory should only contain release files: SKILL.md, scripts/, references/, assets/. No *.log, *.bak, test_* fixtures.
• Verify: ls -la <skill-dir> and confirm each file belongs.

---

Stage 4: Release prep

Goal: Ship a clean, safe, cross-environment package.

See references/checklist-release.md for the full checklist. Five requirements, in this order:

1. skill-regression — regression testing (fill in Test.md, then run twice)
2. glic-check — 5-dimension quality review (Grammar / Logic / Integrity / Containment + Usability). The Integrity dimension catches dangerous writes, missing artifacts, and several security smells.
3. skill-release-audit — final mechanical gate before publish (SKILL.md spec, file structure, no stray README/CHANGELOG, etc.)
4. Cross-environment validation — install the package on a different machine or a teammate's environment, run from scratch. Cannot be automated.
5. skill-release-plus — sign, pack, and fan-out publish to one or more skill hubs.

⚠️ Mandatory confirmation gate (prevents skipping acceptance):

Before executing step 5, you must confirm the following with the user and wait for an explicit reply:

"About to publish via skill-release-plus. Confirm:

• Version: auto-bump / manually specified ..___
• Changelog: __________

Reply 'confirm publish' to proceed."

Absolutely forbidden:

• ❌ Self-testing → commit → upload → publish in one shot. Before publishing, the user must see a clear summary of changes + an acceptance report + a clickable preview URL and explicitly accept.
• ❌ Publishing without confirmed version and changelog.

After publish: share the hub URL and ask the user to verify the skill name, description, and version on the hub page.

---

Dependencies

System commands

• git — required for Stage 1 git check (recommended, not enforced)
• python3 — optional, only used inside scripts/pre-check.sh for one minor detection; the script degrades gracefully if missing

Skill dependencies

All four are part of the build-better-skills suite, plus skill-creator from upstream Anthropic skills:

• skill-creator — scaffolds the skill (called in Stage 2)
• skill-regression — Stage 4 Step 1
• glic-check — Stage 4 Step 2
• skill-release-audit — Stage 4 Step 3
• skill-release-plus — Stage 4 Step 5

Reference files

• references/checklist-before-start.md — Stage 1 details (3 pre-flight tips)
• references/checklist-coding.md — Stage 3 details (4 acceptance checks)
• references/checklist-release.md — Stage 4 details (5 release requirements)
• scripts/pre-check.sh — Stage 1 automated pre-flight script