Skill learning

Apply this to an explicit invocation or clear intent to author a reusable skill. Convert conversations, notes, paths, URLs, repeated workflows, or skill-evolution candidates into repo skill | user skill candidates. Rules, one-off tips, and general implementation are out of scope, and never invoke another user-invoked skill.

This is the sole TigerKit author for skill create | improve | merge, including new skills and semantic updates. Candidates or targets from other skills must also pass evidence, deduplication, evaluation, compatibility, and apply gates.

For every create | improve | merge, check mature upstream practice first when available. Use [Skill quality](references/skill-quality.md) to verify provenance, distill behavior and failure modes, and record each applicable disposition with the literal keep | adapt | omit label; never copy an upstream framework wholesale.

Draft and apply are separate.

• draft gate: Distinguish verified evidence from unverified user claims and design a

pending candidate. Even when evidence remains unverified, keep a clear design request in the active candidate packet without treating it as apply evidence.

• apply gate: Every checklist row must pass before writing to a skill path.

Need-based draft checkpoint

When candidate or apply approval is needed, prefer the host's native structured question surface (Claude Code: AskUserQuestion; Codex: requestuserinput; Hermes: clarify). If unavailable, present the same approval packet in plain chat; do not write a canonical skill path before approval.

Keep a straightforward same-turn candidate in the current interaction when the host can faithfully retain and reread it. Use the singleton repository-root .tigerkit/learn.md only for explicit save, multi-turn handoff/recovery, a complex candidate whose evidence/checklist cannot fit safely in the approval packet, or when the host cannot retain exact state. Do not create the artifact for a clear no-op merely to report that nothing should change. This file is neither a canonical skill path nor .tigerkit/skill-drafts/<skill-name>/.

The active candidate packet, and learn.md when used, owns each of these fields exactly once: work Status (Pending | Blocked), Disposition (reported | applied | pending), Decision (proposed | merge | no-op | continue | pending), Candidate, Evidence (ID/source/verified | unverified for every claim), Checklist (each apply check's passed | pending | failed state and evidence), Target path (the exact planned path and not created), Not created (both canonical write boundaries), Next step (one executable action), and Updated (write time or run ID).

Use Disposition: applied when a required ledger write and reread match the current candidate/run, while preserving work Status: Pending before apply approval. Without a ledger, use reported | pending for the in-memory packet. Disposition describes candidate-state recording and is not synonymous with Status or canonical skill application.

When an artifact is required, create a temporary file in the same directory, atomically rename it, and reread immediately. If required fields are absent, the ledger is stale or missing, or the reread differs from the written content, stop as Blocked and do not write canonical paths. Do not overwrite a different active candidate; stale completed content may be invalidated and replaced, never archived into per-run files.

Workflow

1. Evidence: Accept any sufficient route: mature upstream plus a concrete TigerKit gap; one strongly verified,

reusable incident; explicit reusable workflow intent plus sufficient source or repository evidence; or genuinely recurring verified cases. Weak anecdotes, raw logs, unsourced claims, and one-off mistakes without reusable correction evidence do not promote. Once one route is verified, advance to a pending candidate and the remaining gates instead of requesting recurrence. Unverified claims cannot pass apply.

1. Promotion and deduplication: Apply [Skill quality](references/skill-quality.md),

then compare against existing repository/user skills, default model capability, and a short rule. Choose one of merge | no-op | continue | pending. If the catalog cannot be read, remain pending and record that status and rationale in the candidate packet.

1. Candidate proposal: Present the target, action name, invocation kind, and

positive/negative triggers. Draft a trigger-first description that answers when to load and preserves only the routing discriminators; keep procedure in the body. Use the user's domain/workflow language to choose a lowercase, hyphenated, verb-form name of at most 64 characters; check for collisions, then mark it proposed. Leave unsupported values as TBD.

1. Minimal draft: Record the minimal SKILL.md inputs, workflow, failure branches,

approval boundaries, completion criteria, output contract, and prohibitions directly in the candidate packet. Also add train/validation triggers, success/boundary assertions, behavior evidence designed for the candidate's skill type, a no-skill or prior-skill baseline, and the portable-core/host-extension determination.

1. Approval checkpoint: After rereading the active packet and any required learn.md, follow the checkpoint and

output contract below, then stop.

1. Write, verify, report: After every checklist row and apply authority pass,

preserve the pre-write contents, write with an atomic rename, then reread and verify frontmatter, links, evals, and target-host invocation.

Apply gate checklist

Use only the current host's native repo/user skill paths proven through actual path or host discovery. An unknown host is Unverifiable. Do not invent locations, force one host's paths onto another host, perform cross-host fan-out/sync, or use .tigerkit/ as a permanent skill registry/global state.

Failure paths

🔴 CHECKPOINT · 🛑 STOP (Approval and stop point)

Do not write to the canonical path or .tigerkit/skill-drafts/<skill-name>/ before explicit current-turn apply approval. Past approval, implicit invocation, and a generic request to continue are insufficient authority. Before approval, the candidate remains pending, and Target path records the exact planned path and not created.

The approval checkpoint occurs only after rereading the complete active packet and any required .tigerkit/learn.md. When the artifact branch is required, a write or reread failure is Blocked and cannot request approval. A simple same-turn packet may proceed without the artifact; the one-off no-op branch creates neither.

Output contract

Report Decision/Status/Disposition and, when created, the exact learn.md path, then summarize the key result in only 1–3 lines. End with exactly one approval question when apply is eligible. A no-op ends without an invented approval question. Do not copy the packet's full Evidence, Dedupe, Candidate, Target path, Verification, or Remaining concerns into chat. A no-op caused by a threshold failure or duplicate remains concise and need not materialize an artifact.

Prohibitions / antipatterns

• Do not promote weak one-off anecdotes, credentials, raw logs, or screenshots as

reusable evidence or copy them into a draft.

• Do not omit a requested pending draft because evidence is unverified.
• Do not create duplicate skills, verbose wrappers around default capability, or

indistinguishable trigger pairs.

• Do not duplicate the name/kind/path/verification/concerns in the Receipt.
• Do not auto-archive, edit .gitignore, invoke another user skill, push, or

publish.