t1k:skill-creator
| Field | Value |
|---|---|
| Module | t1k-maintainer |
| Version | 4.10.58 |
| Effort | medium |
| Tools | Agent, AskUserQuestion, Bash, Edit, Glob, Grep, Read, Task, WebFetch, WebSearch, Write |
Keywords: audit-skill, benchmark, capability, create-skill, decision-tree, eval, extend, frontmatter, gotcha, new-skill, review-skill, skill-PR, Skillmark, update-skill, validate-skill
How to invoke
Section titled “How to invoke”/t1k:skill-creator[skill-name or description]Skill Creator
Section titled “Skill Creator”Create effective, eval-driven TheOneKit skills using progressive disclosure and human-in-the-loop iteration.
Principles: Context engineering > prompt engineering | Progressive disclosure | Eval-driven iteration | YAGNI/KISS/DRY
Quick Reference
Section titled “Quick Reference”Size limits — this table is the SSOT. Every other mention in references/ points here; do not restate numbers there.
| Resource | Limit | Purpose |
|---|---|---|
| Description | By autoload: class, all blocking: internal ≤100 · auto ≤160 · user-only ≤350 (validate-skill-description-budget.cjs, validate-description-length-cap.cjs). A kit carrying a skillDescChars no-growth override in release-action scripts/data/skill-listing-ceilings.json may hold auto up to that override, never past 250 | Auto-activation trigger (be “pushy”) |
| SKILL.md | WARN >250 lines · ERROR >400 — enforced by validate-skill-line-count.cjs | Core instructions |
| Each reference | <300 lines (advisory — no gate enforces it) | Detail loaded as-needed |
| Scripts | No limit | Executed without loading |
Skill Structure
Section titled “Skill Structure”.claude/skills/t1k-{name}/├── SKILL.md (required — see size limits above)├── scripts/ (optional: executable code)├── references/ (optional: docs loaded as-needed)├── agents/ (optional: eval agent templates)└── assets/ (optional: output resources)Full anatomy: references/skill-anatomy-and-requirements.md
Required Frontmatter
Section titled “Required Frontmatter”| Field | Required | Rules |
|---|---|---|
name | Yes | Colon-form. Core: t1k:{slug}. Kit-wide: t1k:{kit}:{slug}. Module-scoped: t1k:{kit}:{module}:{slug}. Module == kit short name collapses to kit-wide. The directory is the same path in hyphen form (t1k-{kit}-{module}-{slug}/). See references/architecture-rules.md § 0 (SSOT). CI gates validate-skill-prefix.cjs and validate-skill-name-format.cjs are strict. |
description | Yes | Class cap from Quick Reference, trigger-optimized |
autoload | Yes | auto, user-only, or internal — the description-cap class. validate-skill-description-budget.cjs errors on a missing or invalid value |
disable-model-invocation | Yes, consistent with autoload | true iff autoload: user-only; false (or absent) for auto/internal. The gate errors when the two disagree |
effort | Yes | low, medium, or high |
context | Optional | context: fork only for a skill that spawns NO sub-agents (reads, analysis, plan/research docs). Fork STRIPS Agent/Task/TeamCreate; a spawning skill MUST run in the main session and omit context: (references/architecture-rules.md § D.0). validate-skill-context-fork-spawn-usage.cjs fails fork + spawn. |
argument-hint | Recommended | Usage hint shown in skill listing |
version | Present after release, never authored | CI/CD-injected from module.json or metadata.json (SKILL.md only). Stripped + re-injected on every release; do not write it in a new skill. |
origin | Never hand-author | CI injects it before validate-origin-injection-coverage.cjs runs on PR branches (the pre-inject step precedes the coverage gate in quality-gates.yml; run-gates.cjs carries the result forward). Leave it out of new files. |
repository, module, protected | Never hand-author | CI-injected together with origin (and version). |
Why not hand-stamp: on PR branches the CI pre-inject step writes origin markers into an ephemeral workspace before the coverage validator runs, so a new file needs none. CLAUDE.md’s “do not hand-author origin metadata” holds for new and existing files alike.
context: fork rule of thumb: fork runs the body in an isolated sub-context and STRIPS Agent/Task/TeamCreate from it, and tools: cannot add them back. Declare context: fork only when the body spawns no sub-agents (large file reads, analysis, research docs that write to disk); a skill that spawns sub-agents runs in the main session with no context: key. Gate: validate-skill-context-fork-spawn-usage.cjs. Of the skills that spawn (t1k-doctor, t1k-cook, t1k-plan, t1k-debug, t1k-review, t1k-security, t1k-ship), none declares context:.
Post-Write Verification (MANDATORY for new files)
Section titled “Post-Write Verification (MANDATORY for new files)”After scaffolding ANY new file under .claude/, do not add origin markers by hand: CI pre-injects origin/repository/module/protected before validate-origin-injection-coverage.cjs runs. Check only that no TODO- placeholder is left behind.
Common failure: scaffolding and forgetting to fill the TODO- placeholders in non-origin fields. t1k-modules.json-driven module resolution and PR review reject TODO-modulename. Always replace placeholders before pushing.
Decision-Tree Body Pattern
Section titled “Decision-Tree Body Pattern”For skills with 3+ distinct usage paths or input modes, prepend a 5-row decision-tree table to the body. The table maps user intent → which section to read. Reference: .claude/skills/t1k-architecture/SKILL.md lines 26-39 (canonical example). Pattern shipped on t1k-cook, t1k-fix, t1k-debug in the architecture review rollout.
## Decision Tree
| Intent | Path ||---|---|| "Implement feature X end-to-end" | Run full workflow → [Workflow](#workflow) || "Quick fix, skip research" | `--fast` flag → [Fast mode](#fast-mode) || ... | ... |Why: small, predictable AI navigation. Cuts the time from skill activation to correct action.
Creation Workflow
Section titled “Creation Workflow”Follow references/skill-creation-workflow.md:
0. Manual-correction scan (MANDATORY before drafting) — scan recent session checkpoints, plan files, and spawn briefs for the pattern “I keep manually injecting X into teammate briefs” or “I keep correcting the same mistake.” If you find ≥2 instances of the same correction in the last cook session, the new skill SHOULD absorb that knowledge as content. Anti-pattern: writing a skill that documents the happy path while the team keeps fighting the same gotcha in private messages. See docs/manual-correction-implies-skill-gap.md (rule embedded in rules/development-principles.md § “Update Skills After Every Error”).
0.2. Placement gate (MANDATORY when the knowledge is a constraint, not just a how-to) — if the content you’re about to write down is a MUST/MUST-NOT rather than reference material, run the four-way placement test in ../t1k-rule-creator/references/authoring-placement-doctrine.md before defaulting to “skill.” A skill is the right home ONLY when the guidance is consulted after an agent has already decided to do X — not when it must be followed unprompted (that’s a rule or a hook) or only by one agent type (that agent’s .md body). See “Placement & Summoning Gate” below.
0.5. Sibling-overlap scan (MANDATORY before scaffolding) — grep the target module’s existing skills for topical fit with what you are about to create. If an existing skill already owns the domain, extend its references/ instead of adding skill N+1. A new reference file costs zero always-on tokens; a new skill costs a permanent description slot in every session of every consumer who installs the module, forever. Step 0 scans for repeated corrections; this step scans for repeated topics. Only scaffold when the answer to “which existing skill would a user expect this in?” is genuinely “none.” Judging two skills that already exist is the same call in reverse — keyword overlap is not the discriminator, the question each answers is: references/skill-creation-workflow.md § “Step 0.5”.
0.6. Rule-vs-skill mirror check — content you are about to write may actually be a default, prohibition, or frame-responder that must bind before any skill activates, which a skill body can never do. Run the three-shape test in skills/t1k-rule-creator/SKILL.md § “Is it actually a rule?”; if one applies, route it to t1k-rules-manager instead of drafting it here. Corpus history + worked examples: docs/rule-vs-skill-placement.md.
- Capture Intent — what, when trigger, what output (AskUserQuestion)
- Research — Context7, WebSearch for best practices
- Plan — identify reusable scripts, references, assets
- Initialize —
t1k skill new <name> --module <owner>(see Auto-register below) - Write — implement resources, write SKILL.md
- Test & Evaluate — run eval suite, grade, compare with/without skill
- Optimize Description — AI-powered trigger accuracy
- Validate — run checklist in
references/validation-checklist.md - Register — update
t1k-activation-{layer}.json
Auto-register (fast path) — never hand-stamp + hand-place
Section titled “Auto-register (fast path) — never hand-stamp + hand-place”Second occurrence ⇒ automate, never repeat by hand (docs/replicate-and-automate.md): don’t repeat the manual scaffold-dir → stamp-frontmatter → edit-module.json → seed-activation → regen dance. Use the scaffolder:
t1k skill new <name> --module <owner> # writes .claude/skills/<t1k-dash-dir>/SKILL.md (flat)t1k skill new <name> --module <owner> --kit-wide # kit-wide tierIt creates the t1k--prefixed dir + SKILL.md with stamped frontmatter (colon-form name:, dash-form dir per references/architecture-rules.md § 0), appends to the owning module.json skills[], seeds activation keywords in t1k-activation-<owner>.json, and regenerates t1k-modules.json (via generate-modules-registry.cjs). You then write the body. Requires CLI ≥ 5.4.0 (t1k --version).
Modular kits (gamedev, playablelabs, gamebackend, …). t1k skill new writes flat .claude/skills/<dir>/. Those kits’ AGENTS.md conventions prefer .claude/modules/<module>/skills/<dir>/, so moving it (git mv, then re-run generate-modules-registry.cjs) is a convention for those kits, not a shipping requirement: build-module-zip.cjs falls back to flat .claude/skills/ for any skill registered in a module.json.
Manual fallback (CLI < 5.4.0): scaffold the dir + SKILL.md yourself, write frontmatter without origin keys, append to module.json skills[], seed t1k-activation-<owner>.json, then run bun <release-action>/scripts/generate-modules-registry.cjs <kit-root> and stage t1k-modules.json in the SAME commit (agents/t1k-kit-developer.md § “Module Registry Sync”).
Placement & Summoning Gate (MANDATORY when the skill carries a constraint)
Section titled “Placement & Summoning Gate (MANDATORY when the skill carries a constraint)”Mirrors t1k-rule-creator’s placement gate — same table, shared file, one SSOT:
../t1k-rule-creator/references/authoring-placement-doctrine.md.
A skill is the right home only for the fourth row: reference material consulted after an agent
has already decided to do X. If what you’re drafting is instead a MUST/MUST-NOT an agent must
follow unprompted, or only one agent type ever needs it, skill is the wrong answer — route to
/t1k:rule-creator (universal, unprompted, not mechanically checkable), a hook (universal,
unprompted, mechanically checkable), or the consuming agent’s own body (single-consumer),
respectively.
When skill IS the right answer, verify and record the summoning path before shipping. A skill
only fires when something names it: an agent body’s tool/reference list, a routing table
(skill-domain-routing-*.md), or an explicit Skill invocation elsewhere in the kit. No named
summoning path ⇒ the skill is unfindable ⇒ ship nothing — a constraint parked in an unsummoned
skill is strictly worse than the same constraint left in a costly always-loaded rule, because the
rule at least reliably fires. State the summoning path in the PR description alongside the usual
skill-creation checklist, the same way t1k-rule-creator records the rejected-alternatives note.
Record the execution direction too. A new skill must also name which agent executes it, or state explicitly that it runs inline in the main session — never leave the question unanswered by default. See “Executed by Section” below for the structured form and when it applies.
Eval & Testing
Section titled “Eval & Testing”Full eval guide: references/eval-infrastructure-guide.md
Scripts reference: references/scripts-reference.md
Python scripts use: ~/.claude/skills/.venv/bin/python3
Benchmark Scoring
Section titled “Benchmark Scoring”- Accuracy (80%): explicit terminology, numbered steps, concrete examples
- Security (20%): scope declaration + refusal/leakage prevention required
Full scoring criteria: references/skillmark-benchmark-criteria.md
Optimization patterns: references/benchmark-optimization-guide.md
Gotchas Live in the Ledger; Load-Bearing Rules Live in the Step
Section titled “Gotchas Live in the Ledger; Load-Bearing Rules Live in the Step”Lessons live in the ledger skills/<host>/ledger/gotchas/<skill>.md; load-bearing rules stay inline under ## Hard rules. To record a lesson, write a bullet under a temporary ## Gotchas and run bun .claude/scripts/gotcha-migrate.cjs --repo . --skill <name>. Full rules and migrator flags: references/gotcha-ledger-rules.md.
Executed by Section (CONDITIONAL — mechanical-step skills only)
Section titled “Executed by Section (CONDITIONAL — mechanical-step skills only)”## Executed by names which agent runs a skill’s mechanical steps. Conditional, not
mandatory — it applies only when a skill HAS mechanical steps (run a script, tabulate, quote
a named source, poll CI, apply an already-decided rubric). A judgment-driven skill correctly has
none; “every skill needs one” mints bogus blocks. The five core cheap agents ship in the REQUIRED
t1k-extended module, so a block costs no new agent. Shape, exemplar and rationale:
references/executed-by-convention.md · criterion: references/validation-checklist.md §
“Executed by” · enforcement: CI gate, warn-first (it predates Core Req #13’s 2026-09-29 full-rollout rule), in theonekit-release-action.
Architecture Rules (MANDATORY before shipping)
Section titled “Architecture Rules (MANDATORY before shipping)”Skills are not just markdown — they are agent extension points. Apply the architecture-review checklist whenever a skill spawns sub-agents, calls remote services, talks to MCP, manages memory, or recommends destructive operations. Full checklist with red flags, severity, and fixes: references/architecture-rules.md (8 categories: A control-loop, B tool/extension, C memory/SSOT, D sub-agent fork hygiene, E cache stability, F hooks/MCP, G performance, H remote/cloud, I destructive-op safety, J AI-driven design).
Top architecture red flags to scan for in EVERY skill review:
| Red flag | Severity | Quick fix |
|---|---|---|
| Skill executes shell from MCP-sourced content (script bodies, console output) | Blocker | Hard-block inline-shell tokens (!, $(...), backticks) before treating MCP output as instruction |
| Live shell substitution in skill body (bang-prefixed backtick command form) | High | Move to a tool call AFTER the cached prefix — body must stay static |
Skill declares context: fork AND spawns sub-agents | High | Remove context: fork — fork strips Agent; the spawn silently bails (arch rule D.0) |
| Sub-agent spawn without a stated depth budget | High | State the depth budget in prose (rules/agent-security-boilerplate.md); add querySource check. Fan-out width is advisory, not a required cap |
| Read-only fan-out spawned onto write-capable agents | High | Route to an agent whose tools: declares no Edit/Write (Explore, or the narrowest read-only t1k-*). A spawner cannot narrow a child’s tools at the call site — the child’s frontmatter is the only enforcement |
| Spawn brief with no stated delivery channel or pasted file bodies | High | Follow t1k-team/references/spawn-brief-contract.md — name SendMessage explicitly, pass paths not payloads |
| Verification sub-agent without anti-avoidance prompting | Medium-High | Prompt MUST: enumerate excuses, reinject “verify ONLY, do NOT fix” after every tool result |
| Memory/persistence with unbounded growth or scheduled expiry | High | Cap lines AND bytes; staleness warnings (“47 days ago”), never auto-delete |
Duplicate version (frontmatter + metadata.version) | High | Drop metadata.version — CI-injected version is sole SSOT |
Last Updated commit metadata embedded in body | High | Remove — git log answers it; embedding cache-busts every release |
Tool/script with no output size cap (maxResultSizeChars) | High | Per-tool cap (e.g., 32KB); document truncation marker |
| Cloud skill missing per-instance auth, capture-at-send-time, asymmetric channels | High | Apply category H rules — token closures, BoundedUUIDSet for dedup, bounded retry table per close code |
Skill recommends rm -rf or git checkout -- without backup | Blocker-High | Wrap in t1k install --reset style command that backs up first; never raw destructive ops |
| Templated boilerplate inserted BEFORE the H1 heading | Medium | Body order: H1 → 1-line summary → stable rules → details. Security boilerplate is not re-stated per skill at all — rules/agent-security-boilerplate.md is auto-loaded and covers every skill and agent |
| Heavy effort:high skill loads all references inline (>250 lines) | Medium | Push detail to references/; SKILL.md becomes the router |
When reviewing a skill: load references/architecture-rules.md, walk the 10 categories (A-J), and quote the row by name when raising findings (e.g., “Violates D-row 1: missing depth budget”).
Anti-Patterns
Section titled “Anti-Patterns”-
Restating a core skill. A kit skill holds only the engine delta and links the core skill (
t1k:debug,t1k:review); never repeat its procedure. -
Authoring a constraint as a skill with no named summoning path — see “Placement & Summoning Gate” above; a constraint parked in an unsummoned skill ships nothing
-
Defaulting to “skill” for guidance an agent must follow unprompted — run the four-way placement test before scaffolding; that shape is a rule, a hook, or an agent body, not a skill
-
Teach what Claude already knows (waste of context)
-
SKILL.md over 250 lines (CI gate WARN; move detail to references/)
-
context: forkon a skill whose body spawns sub-agents (fork stripsAgent; the spawn bails) -
A lesson-style
## Gotchassection or*gotcha*.mdreference in a skill (lessons go to the ledger, load-bearing rules to the step; see “Gotchas Live in the Ledger”) -
Description written for humans instead of model activation
-
Hand-authoring
origin/repository/module/protected— CI injects them before the coverage gate; never write them yourself. -
Scripts in bash instead of Python/Node.js (cross-platform)
-
Live shell substitution in body (bang-prefixed backtick command form; cache busts on every fragment edit; see arch rule E)
-
Sub-agent spawning without a depth budget (see arch rule D)
-
Tool/script without output size cap (one large output overwhelms model context; see arch rule B)
-
Cloud skill without per-instance auth + capture-at-send-time + bounded retry (see arch rule H)
-
Recommending
rm -rf/ rawgit checkout --without backup (CLAUDE.md #10; see arch rule I) -
Hardcoding MCP tool listing in body (TOCTOU + dynamic content cache bust; snapshot at session start)
-
Embedding
Last Updatedcommit metadata or runtime date in body (cache bust on every change; see arch rule E) -
Duplicate version SSOT (
versionandmetadata.version; see arch rule C) -
Templated boilerplate before H1 (cocos-playable-* anti-pattern; see arch rule E)
-
Verification sub-agent without anti-avoidance prompting (drifts from “verify” to “fix”; see arch rule D)
Hard rules
Section titled “Hard rules”- NEVER write the bang-prefix-then-backtick-then-three-dots-then-backtick character sequence in a skill body — not even inside double-backtick “escaped” markdown. Claude Code’s slash-command preprocessor captures the inner content of bang-prefixed backtick command-form patterns greedily and … detail (
references/hard-rules-full.md)
Two kinds of “gotcha”, two homes:
- Load-bearing rules — a mistake that causes data loss, a crash or a silently-wrong result, or that the skill
says to read before acting — are stated INLINE, in the procedure step they guard (
references/architecture-rules.md§ L.4). Heading them## Hard rulesis fine, and areferences/*gotcha*.mdfile is allowed when it holds ONLY such kept-inline rules. Mark an entry<!-- keep-inline -->to stop the migrator moving it. - Lessons — everything else learned from a failure — live in the ledger
skills/<host>/ledger/gotchas/<skill>.md(hostt1k-rsiin core, the skill itself in a kit without it), owned byt1k-rsi-reviewer: it stamps an entry it sees caught or violated and prunes one unseen for 30 days (t1k-rsi§ gotchas). A skill MUST NOT carry a lesson-style## Gotchassection or*gotcha*.mdreference. To record one, write a bullet under a temporary## Gotchasand runbun .claude/scripts/gotcha-migrate.cjs --repo . --skill <name>.
Additional References
Section titled “Additional References”../t1k-rule-creator/references/authoring-placement-doctrine.md— the shared four-way placement test (rule / hook / agent-body / skill) behind the “Placement & Summoning Gate” section abovereferences/skill-design-patterns.md— five patterns for structuring a skill body (problem-first vs tool-first); pairs withreferences/runbook-template.md(Category 8: runbook-style skills)references/structure-organization-criteria.md— required directory layout and file-placement rules beyond the Skill Structure summary abovereferences/writing-effective-instructions.md— imperative/infinitive writing style and instruction-clarity guidancereferences/yaml-frontmatter-reference.md— full frontmatter field reference (required + optional keys), companion to the Required Frontmatter table abovereferences/testing-and-iteration.md— testing rigor by skill visibility, iteration loopreferences/troubleshooting-guide.md— fixes for “skill won’t upload,” “skill doesn’t trigger,” “skill triggers too often”references/mcp-skills-integration.md— how MCP (tool access) and Skills (procedural knowledge) complement each otherreferences/distribution-guide.md— packaging + distribution model (individual, org, API, marketplace); links to theplugin-marketplace-*.mdset
Skill creation and improvement within .claude/skills/ only.