kookaburra-skill-creator

name

kookaburra-skill-creator

description

Creates or updates project skills, slash commands, and toolkit primitives for the Kookaburra Cut repo. Use when asked to "add a Kookaburra Cut skill", "create a project skill", "sync skills for Codex and Claude Code", "add a slash command", "add a toolkit primitive", "document an authoring workflow", or extend Kookaburra Cut's shared agent infrastructure. Project-scoped distillation of ps-agent-skill-creator.

kookaburra-skill-creator

Builds new in-repo skills, commands and primitives for Kookaburra Cut that actually work. Project-scoped; lives in and commits with this repo. .agents/skills is the only skill source of truth, while .claude/skills exposes it to Claude Code through one relative symlink. For personal, cross-project skills use the global ps-agent-skill-creator instead.

When to use

• Adding a new project skill under .agents/skills/<name>/
• Repairing the shared Codex and Claude Code skill layout
• Adding a slash command under .claude/commands/<name>.md
• Adding a toolkit primitive under src/toolkit/ (and documenting it)
• Improving an existing Kookaburra Cut skill/command

Instructions

1. Interview first: ask before writing. Ask focused multiple-choice questions covering: purpose, trigger phrases, the exact workflow, edge cases, failures already seen, and validation steps. Do not write skill content from assumptions. Skipping this produces generic, low-value skills every time.
2. Name it for the repo. Project skills/commands use a descriptive kookaburra--or-domain name in kebab-case (e.g. kookaburra-scene-authoring, new-scene). No ps- prefix, which is reserved for global personal skills.
3. Ensure the shared skill layout.
   • Treat .agents/skills as the only source of truth. Never maintain duplicate skill files under .claude; expose the canonical directory through a symlink instead.
   • If needed, run mkdir -p .agents/skills .claude, then create .claude/skills with ln -s ../.agents/skills .claude/skills.
   • If .claude/skills is a real directory, move each non-conflicting skill into .agents/skills. If a name exists in both locations, compare them and ask which version to keep. Never overwrite either version. Once the directory is empty, remove it with rmdir .claude/skills and create the symlink.
   • If .claude/skills is an incorrect symlink, inspect its target first. Migrate safe in-repo content, ask before touching unique or external content, then run unlink .claude/skills and recreate the relative symlink.
4. Place it correctly.
   • Skill → .agents/skills/<name>/SKILL.md (+ REFERENCE.md if it would exceed ~250 lines).
   • Command → .claude/commands/<name>.md.
   • Primitive → src/toolkit/<area>/<Name>.tsx, exported from src/toolkit/index.ts, documented in kookaburra-scene-authoring/REFERENCE.md.
5. Write to the quality bar (below). No vague rules.
6. Verify immediately. Run test -L .claude/skills, test "$(readlink .claude/skills)" = "../.agents/skills", test .agents/skills -ef .claude/skills, then the relevant project checks. Fix and rerun until clean before responding.

Quality bar

• Description is king. The YAML description is the only thing seen before loading. Pack it with concrete trigger keywords/phrases, in third person. Vague descriptions never get loaded.
• Only add what the agent doesn't know. Cut general knowledge; the context window is shared.
• One skill = one capability. Never merge unrelated workflows because it breaks trigger matching.
• Every rule traces to a real failure. "Use useTimeline() not Date.now() because Date.now() makes frame N non-reproducible and breaks byte-identical export" beats "use time correctly".
• Every prohibition includes an alternative. "Never animate the DOM. Instead, render via a troika toolkit primitive." A bare "don't" is a dead end.
• One concrete example beats paragraphs. Show a snippet.
• Validation loop. Give exact commands and say to fix-and-rerun until passing.
• Skip what linters enforce. Reference biome.json / tsconfig.json instead of restating style.

Pre-finalization checklist

• Description has concrete triggers, third person
• Instructions are numbered, actionable steps
• Every prohibition has an alternative
• No vague rules ("write clean code")
• Validation loop included (pnpm build / pnpm test / pnpm lint as relevant)
• SKILL.md under ~250 lines (split to REFERENCE.md if not)
• One capability only
• Skill authored under .agents/skills, with .claude/skills linked to it
• New primitive exported from src/toolkit/index.ts and added to REFERENCE.md

Example: SKILL.md skeleton

---
name: <name>
description: <what + when, third person, with trigger keywords>
---

# <name>

<one-sentence purpose>

## When to use
- <trigger>

## Instructions
1. **Step:** actionable, with exact command
2. **Verify:** run `pnpm build && pnpm test`; fix and rerun until clean