Skip to content

t1k:skill-creator

FieldValue
Modulet1k-maintainer
Version4.10.58
Effortmedium
ToolsAgent, 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

/t1k:skill-creator
[skill-name or description]

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

Size limits — this table is the SSOT. Every other mention in references/ points here; do not restate numbers there.

ResourceLimitPurpose
DescriptionBy 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 250Auto-activation trigger (be “pushy”)
SKILL.mdWARN >250 lines · ERROR >400 — enforced by validate-skill-line-count.cjsCore instructions
Each reference<300 lines (advisory — no gate enforces it)Detail loaded as-needed
ScriptsNo limitExecuted without loading
.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

FieldRequiredRules
nameYesColon-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.
descriptionYesClass cap from Quick Reference, trigger-optimized
autoloadYesauto, user-only, or internal — the description-cap class. validate-skill-description-budget.cjs errors on a missing or invalid value
disable-model-invocationYes, consistent with autoloadtrue iff autoload: user-only; false (or absent) for auto/internal. The gate errors when the two disagree
effortYeslow, medium, or high
contextOptionalcontext: 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-hintRecommendedUsage hint shown in skill listing
versionPresent after release, never authoredCI/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.
originNever hand-authorCI 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, protectedNever hand-authorCI-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.

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.

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.

  1. Capture Intent — what, when trigger, what output (AskUserQuestion)
  2. Research — Context7, WebSearch for best practices
  3. Plan — identify reusable scripts, references, assets
  4. Initialize — t1k skill new <name> --module <owner> (see Auto-register below)
  5. Write — implement resources, write SKILL.md
  6. Test & Evaluate — run eval suite, grade, compare with/without skill
  7. Optimize Description — AI-powered trigger accuracy
  8. Validate — run checklist in references/validation-checklist.md
  9. 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:

Terminal window
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 tier

It 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.

Full eval guide: references/eval-infrastructure-guide.md Scripts reference: references/scripts-reference.md

Python scripts use: ~/.claude/skills/.venv/bin/python3

  • 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 flagSeverityQuick fix
Skill executes shell from MCP-sourced content (script bodies, console output)BlockerHard-block inline-shell tokens (!, $(...), backticks) before treating MCP output as instruction
Live shell substitution in skill body (bang-prefixed backtick command form)HighMove to a tool call AFTER the cached prefix — body must stay static
Skill declares context: fork AND spawns sub-agentsHighRemove context: fork — fork strips Agent; the spawn silently bails (arch rule D.0)
Sub-agent spawn without a stated depth budgetHighState 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 agentsHighRoute 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 bodiesHighFollow t1k-team/references/spawn-brief-contract.md — name SendMessage explicitly, pass paths not payloads
Verification sub-agent without anti-avoidance promptingMedium-HighPrompt MUST: enumerate excuses, reinject “verify ONLY, do NOT fix” after every tool result
Memory/persistence with unbounded growth or scheduled expiryHighCap lines AND bytes; staleness warnings (“47 days ago”), never auto-delete
Duplicate version (frontmatter + metadata.version)HighDrop metadata.version — CI-injected version is sole SSOT
Last Updated commit metadata embedded in bodyHighRemove — git log answers it; embedding cache-busts every release
Tool/script with no output size cap (maxResultSizeChars)HighPer-tool cap (e.g., 32KB); document truncation marker
Cloud skill missing per-instance auth, capture-at-send-time, asymmetric channelsHighApply category H rules — token closures, BoundedUUIDSet for dedup, bounded retry table per close code
Skill recommends rm -rf or git checkout -- without backupBlocker-HighWrap in t1k install --reset style command that backs up first; never raw destructive ops
Templated boilerplate inserted BEFORE the H1 headingMediumBody 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)MediumPush 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”).

  • 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: fork on a skill whose body spawns sub-agents (fork strips Agent; the spawn bails)

  • A lesson-style ## Gotchas section or *gotcha*.md reference 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 / raw git 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 Updated commit metadata or runtime date in body (cache bust on every change; see arch rule E)

  • Duplicate version SSOT (version and metadata.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)

  • 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 rules is fine, and a references/*gotcha*.md file 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 (host t1k-rsi in core, the skill itself in a kit without it), owned by t1k-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 ## Gotchas section or *gotcha*.md reference. To record one, write a bullet under a temporary ## Gotchas and run bun .claude/scripts/gotcha-migrate.cjs --repo . --skill <name>.
  • ../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 above
  • references/skill-design-patterns.md — five patterns for structuring a skill body (problem-first vs tool-first); pairs with references/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 above
  • references/writing-effective-instructions.md — imperative/infinitive writing style and instruction-clarity guidance
  • references/yaml-frontmatter-reference.md — full frontmatter field reference (required + optional keys), companion to the Required Frontmatter table above
  • references/testing-and-iteration.md — testing rigor by skill visibility, iteration loop
  • references/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 other
  • references/distribution-guide.md — packaging + distribution model (individual, org, API, marketplace); links to the plugin-marketplace-*.md set

Skill creation and improvement within .claude/skills/ only.