kookaburra-skill-creator
Skill10 starsChanged 2 days agoApache-2.0View on GitHub
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.
In this repository11 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- kookaburra-background-authoringSkill
- kookaburra-brand-packsSkill
- kookaburra-commitSkill
- kookaburra-export-presetsSkill
- kookaburra-lighting-authoringSkill
- kookaburra-pr-descriptionsSkill
- kookaburra-releaseSkill
- kookaburra-scene-authoringSkill
- kookaburra-video-editingSkill
The file
We split this skill into the rules it gives an agent
7 rules. About 0 are common, 2 are distinctive, and 5 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈2
Distinctive · estimate
This author's own choices. Worth a look.
5
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- could be automatic: a setting could enforce it
- Distinctive: line 20
Interview first: ask before writing: Ask focused multiple-choice questions covering: purpose, trigger phrases, the exact workflow, edge …
- Very specific: line 23
Treat .agents/skills as the only source of truth.
- Very specific: line 24
If needed, run mkdir -p .agents/skills .claude, then create .claude/skills with ln -s ../.agents/skills .claude/skills.
- Very specific: line 25
If .claude/skills is a real directory, move each non-conflicting skill into .agents/skills.
- Very specific: line 26
If .claude/skills is an incorrect symlink, inspect its target first.
- Very specific: line 32
Verify immediately: Run test -L .claude/skills, test "$(readlink .claude/skills)" = "../.agents/skills", test .agents/skills -ef …
- Distinctive: line 38
One skill = one capability: Never merge unrelated workflows because it breaks trigger matching.
≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
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
- 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.
- 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). Nops-prefix, which is reserved for global personal skills. - Ensure the shared skill layout.
- Treat
.agents/skillsas 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/skillswithln -s ../.agents/skills .claude/skills. - If
.claude/skillsis 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 withrmdir .claude/skillsand create the symlink. - If
.claude/skillsis an incorrect symlink, inspect its target first. Migrate safe in-repo content, ask before touching unique or external content, then rununlink .claude/skillsand recreate the relative symlink.
- Treat
- Place it correctly.
- Skill →
.agents/skills/<name>/SKILL.md(+REFERENCE.mdif it would exceed ~250 lines). - Command →
.claude/commands/<name>.md. - Primitive →
src/toolkit/<area>/<Name>.tsx, exported fromsrc/toolkit/index.ts, documented inkookaburra-scene-authoring/reference/scenes.md(or its topic file), thenpnpm agent:catalog.
- Skill →
- Write to the quality bar (below). No vague rules.
- 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
descriptionis 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()notDate.now()becauseDate.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.jsoninstead 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 lintas relevant) - SKILL.md under ~250 lines (split to REFERENCE.md if not)
- One capability only
- Skill authored under
.agents/skills, with.claude/skillslinked to it - New primitive exported from
src/toolkit/index.ts, added to the scene-authoringreference/and the catalogue regenerated
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 cleanDoes it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

