Skills & Prompt Craft

Part of the PersonalClaw research-learnings library. Source-agnostic; distilled 2026-07-13 from a 95-source competitive-research corpus.

Principles (the durable truths)

Predictability is the root virtue of a skill. A skill exists to wrangle determinism out of a stochastic system: the same process each run, not identical output. Everything else in skill authoring — checkable completion criteria, trigger hygiene, progressive disclosure — serves this.

The description is the routing surface; the body loads only after triggering. Skill metadata sits in context every turn; the body arrives post-trigger. Therefore ALL trigger criteria must live in the description, written as WHEN-clauses (“Use when the user wants…, mentions…”), not as a summary of what the skill does. Multiple independent systems converge on this as the single highest-leverage authoring rule; one production pipeline even treats “wrong triggering” as its own repair class, distinct from wrong content.

Short behavioral documents are the highest-adoption agent artifacts in the ecosystem. An ~80-line behavioral-guidelines skill reached ~191k GitHub stars; a 75-line abstract “idea file” reached 5k+ stars in ~3 months. Distribution-ready prompt craft — not code — is what spreads. Behavioral-guardrail skills (constraints, not procedures) are a distinct, high-leverage genre alongside procedural know-how.

If a step is mandatory, codify it in deterministic rails — never merely ask the model to remember it. Per-step reliability compounds multiplicatively; prompt-only skills are probabilistic and skip steps, stop early, and format inconsistently. When a lesson is expressible as config, hook, schema, or validator, prefer the mechanical form over a prompt sentence. Prompt contracts should be backed by structural enforcement (tool denial, schema validation), not substitute for it. See agent-harness-engineering.

Output quality is a function of the harness-assembled context, not the user-typed prompt. A ~6-60 token user prompt becomes a ~5-50k token inference context via skills, rules, memory, and tool schemas. Skill craft is therefore context-budget engineering: everything always-in-context must pay rent.

Constitutions hold hard rules only; skills hold workflows. One canonical constitution file (AGENTS.md-genre), symlinked or pointer-referenced everywhere, kept in terse telegraph style (“Grammar optional. Few tokens.”); repeatable procedures live in skills; per-repo rules append below the pointer, never fork the canon.

Give success criteria, not step-by-step instructions. LLMs are exceptionally good at looping until they meet specific goals. “Strong success criteria let you loop independently; weak criteria (‘make it work’) require constant clarification.” Transform imperative tasks into verifiable goals (“Fix the bug” → “Write a test that reproduces it, then make it pass”). See verification-and-judging.

Mechanisms

1. SKILL.md anatomy + three-tier progressive disclosure

A skill is a folder with one required SKILL.md plus optional scripts/ (deterministic code for fragile operations), references/ (docs loaded on demand), assets/ (used in outputs, never read into context). Frontmatter is minimal — name (1-64 chars, [a-z0-9-], must match dir name) + description (≤1024 chars, “what it does AND when to use it”); the open-spec adds optional license, compatibility, metadata map, experimental allowed-tools. Disclosure tiers with size budgets: metadata always in context (~100 words/tokens) → body on trigger (<500 lines / <5k tokens) → resources as needed. References >10k words must ship grep patterns in SKILL.md so the model can search instead of reading whole. README/CHANGELOG inside skills are forbidden (dead weight in a context-loaded artifact). The progressive-disclosure test is branches: inline what all usage paths need; move to a linked file what only some paths reach; name files for their contents; keep a concept’s definition + rules + caveats under one heading (co-location). A reference validator (skills-ref validate style) enforces the format.

2. Trigger-shaped description writing

Rules that survived across independent skill corpora: (a) front-load the skill’s leading word — a compact pretrained concept (lesson, tracer bullets, tight, red) that anchors behavior in few tokens; (b) one trigger per branch — synonyms restating one branch are duplication, collapse them; (c) strip identity content already in the body; (d) write descriptions as short generic trigger phrases — “optimize for routing, not documentation”; (e) include scope negatives (“not for editing existing decks — use X”) so routing among overlapping skills is unambiguous; (f) don’t state the obvious — only what pushes the model off its defaults. Separate machine-facing routing text from human-facing description where the format allows (when_to_use field appended to the description in listings, counting toward a 1,536-char per-skill cap inside a ~15k-char all-skills budget). Auto-generated descriptions should be flagged (description_auto: true) so review UX can highlight unvetted routing text.

3. The invocation axis and activation-mode taxonomy

A single authoring dimension decides a skill’s cost model: model-invoked skills keep a rich trigger description that sits in context every turn (context load); user-invoked skills set disable-model-invocation: true, get a one-line human-facing description with trigger lists removed, and cost zero context — but cost human memory. Litmus: “could the model usefully reach for this autonomously?” Reuse justifies extraction but is NOT the invocation-type test. Composition rule: a user-invoked skill may invoke model-invoked skills but can never reach another user-invoked one (no model-facing description = unreachable); when user-invoked skills exceed working memory (~7), add a router skill that indexes them. The full activation taxonomy observed in production harnesses is four modes from two metadata fields: always-apply (unconditional), glob/context auto-attach (inject when matching files/context are touched), description-only (agent-requested/semantic), and manual-only. A three-mechanism surface matrix generalizes this: commands (user-invoked, inline), skills (model-invocable procedures, inline or forked), agents (autonomous multi-step with isolation/memory/restrictions) — resolution prefers the lightest mechanism that fits, and disable-model-invocation deliberately reroutes auto-invocation to a heavier one for destructive procedures.

4. Skill-text failure-mode taxonomy (a ready-made lint rulebook)

Six named failure modes for skill prose, each with its fix: premature completion (vague criteria invite it — every ordered step must end in a checkable completion criterion; demanding criteria drive thorough legwork); duplication (one meaning in multiple places — collapse); sediment (stale layers — prune sentence-by-sentence, delete whole failing sentences); sprawl (cure via disclosure/splitting); no-op (lines the model already obeys — the fix is weak leading words); negation (prohibitions backfire — state the positive target behavior, keep prohibitions only as guardrails paired with alternatives). Splitting is justified on two axes only: by invocation (a distinct leading word warrants independent triggering, at the cost of a description) or by sequence (hide later steps that tempt the agent to rush the current one).

5. Degrees-of-freedom doctrine

Record per skill how tightly it constrains: high freedom = prose (judgment calls), medium = pseudocode/parameterized scripts, low = rigid scripts (“a narrow bridge with cliffs needs specific guardrails”). Ship real executables inside scripts/ so the model composes instead of reconstructing boilerplate; scripts can carry their own test files. This axis is also the repair lever: a step that keeps failing gets its freedom lowered toward a script. Skills that need setup state keep a config.json inside the skill and ask the user (structured question tool) when values are missing; persistent skill data must live in a stable plugin-data directory decoupled from the skill directory, because upgrades wipe the skill dir.

6. Validation at write time, not read time

Keep the routing layer trustworthy with a tiny schema validator wired into every write path: frontmatter must start at line 1 and close properly; name/description non-empty strings; names unique across the corpus; errors accumulated per file, exit nonzero on any. Run it as a git pre-commit hook AND inside the commit helper. Extend with cross-file integrity checks: every referenced sub-resource exists; agent/orchestrator prose that backtick-references a skill (regex `([a-z0-9]+(?:-[a-z0-9]+)+)`) must actually bundle it; copies synced from a source-of-truth dir are drift-checked via directory diff (diff_files or left_only or right_only) with “re-run sync” as the fix. Copy-with-drift-detection beats reference-only sharing for skills bundled into multiple agents.

7. Routing contract tests (no LLM at test time)

Prompt-routing behavior is regression-testable without live model runs: a fixtures file of {prompt, expected_intent, expected_route, expected_mode} entries asserted structurally against the skill source — route dirs exist, modes are valid enums, the router’s intent table maps intent→route exactly. Adding coverage = appending a fixture, no code change. Where live-model routing accuracy IS measured, the working target is ≥85% correct skill selection on sample prompts. The same fixture discipline applies to SOP/template surfacing.

8. Token-budget economics + cleanup tooling for the skill surface

A curator/cleaner tool should: (a) read the agent’s exact model-visible skill list (debug-dump the prompt) rather than trusting the filesystem; (b) model the harness’s real render logic — e.g. skill-list budget = 2% of context window, token cost ceil(utf8_bytes/4), fallback order full descriptions → equal truncation → omitted lines; (c) detect duplicates by near-identical bodies with a keep-priority order; (d) detect UNUSED skills from actual session-log usage evidence over a rolling --months window; (e) suggest description-compaction candidates. Output policy: suggest first, edit only on request — never auto-delete. Per-skill base listing cost is ~24 tokens; a well-budgeted manifest approach loads ~2k tokens total for 13 skills where wholesale loading cost 20-40k per call. Complementary growth signal: log invocations via pre-tool hooks and flag skills undertriggering versus expectation, not just dead ones. Curation must be provenance-scoped: auto-curation only touches agent-created entities (verified by a recorded created_by marker); installed/user-authored content is archive-only at most; worst outcome is archival, never deletion, with pre-run snapshot + rollback + dry-run.

9. Conditional surfacing gates and thresholds

Deterministic precondition filters run before semantic scoring, keeping inapplicable skills out of the budget entirely: requires_toolsets/requires_tools (visible only when the capability is present), fallback_for_toolsets/fallback_for_tools (visible ONLY when the capability is MISSING — e.g. a fallback search skill appears only without the premium-API key), platforms: [macos, linux] OS gating, and paths: globs limiting auto-activation to matching file contexts. Docs get the same treatment via read_when frontmatter: summary (required) + a list of trigger conditions; a listing tool prints path - summary / Read when: … per file, errors on missing summaries, and instructs agents to read matching docs BEFORE writing code — surfacing-by-trigger-condition, exactly parallel to skill descriptions. Outcome-weighted ranking closes the loop: per-skill effectiveness = positive_feedback / injections (default 0.5 unknown) blended into retrieval as similarity × (0.3 + 0.7 × effectiveness), with near-duplicate pruning dropping candidates at pairwise embedding similarity > 0.9. Critical attribution rule: prompt-time injection alone is NOT evidence of use — only actual reads/loads count when crediting or blaming a skill.

10. Self-tests, efficacy signals, paired examples, and traceability

Four packaging techniques that make a skill verifiable rather than aspirational: (a) one-line self-test per principle the agent applies to its own output (“Would a senior engineer say this is overcomplicated?”, “Every changed line should trace directly to the user’s request”); (b) declared efficacy indicators (“you’ll know it’s working when: fewer unnecessary diff lines, clarifying questions BEFORE implementation”) giving measurement loops concrete per-skill signals instead of generic usage counts; (c) paired ❌/✅ anti-pattern examples — before/after pairs per principle, with the framing that overengineered versions aren’t wrong patterns, they’re wrong timing; (d) a problem→principle traceability table mapping each rule to the specific observed failure it addresses, so the skill justifies its own existence per-section. Also declare the skill’s cost profile and escape hatch: “these guidelines bias toward caution over speed; for trivial tasks, use judgment.”

11. Gotchas sections and origin-provenance checklists as the lesson sink

The highest-signal content in a mature skill is its Gotchas section, built up from observed failure points over time — run failures should append there, in the skill they amend, not to a floating lessons pile (variant: a <common_mistakes> / “TOP 5 ERRORS” section plus <correct_patterns>). The executable form: verification checklists where every rule records its Origin incident (“Permissions URL redirected to wrong page”), category, check depth, source-of-truth, and date-added — lessons materialized as checks that grow monotonically. Skill creation itself follows a six-step loop ending “use it on real tasks, note friction, update, retest.” An automated evolution pipeline over real sessions converged on exactly four repair actions: improve_skill (targeted edits), optimize_description (rewrite ONLY the trigger — body untouched; wrong-triggering is its own failure class), create_skill, and no-op — with the anti-pattern rule “correct info existed but wasn’t used → NOT a content problem; never delete correct facts in favor of ‘go discover it’”. See self-improvement-loops.

12. Behavioral-principle distillation (the guardrail-skill genre)

The proven template for distilling coding-agent failure modes into a behavioral skill: each principle = motto + concrete prohibitions + a self-test. The canonical four, each mapped to a diagnosed failure: Think Before Coding (“Don’t assume. Don’t hide confusion. Surface tradeoffs” — state assumptions; present multiple interpretations, don’t pick silently; push back if simpler exists; if confused, stop and name what’s unclear); Simplicity First (“Minimum code that solves the problem. Nothing speculative” — no unrequested features/configurability/abstractions for single-use code; “if you write 200 lines and it could be 50, rewrite”); Surgical Changes (“Touch only what you must. Clean up only your own mess” — don’t improve adjacent code; orphan rule: remove imports/vars YOUR change made unused, leave pre-existing dead code; mention, don’t delete, unrelated cruft); Goal-Driven Execution (“Define success criteria. Loop until verified” — plan lines rendered as [Step] → verify: [check]). Related distillations add a risk threshold (“ask first only if ambiguity carries real risk”) and a skip-cosmetic rule. Imported rule-packs need local override precedence: locally-learned lessons rank above imported guidelines when they conflict (e.g. a popular pack’s git add . vs a learned explicit-path-staging rule for shared working trees).

13. AGENTS.md constitution architecture

One canonical constitution file holds hard rules only; every harness’s expected location (~/.claude/CLAUDE.md, ~/.codex/AGENTS.md, …) is a symlink to it; downstream repos get a one-line pointer file (“READ BEFORE ANYTHING (skip if missing)”) with repo-specific rules appended below, never copied. Operational doctrine worth carrying verbatim: “make a note” = a terse edit to the constitution itself; fixes delete the old code path by default — compatibility shims require a NAMED contract (public API, tagged upgrade, security boundary), “tests alone don’t count”; unknown working-tree changes likely belong to another agent — continue in scope, ask on conflict. The self-amending variant: any repo-wide behavior change the user requests gets written INTO the rules file and persists for future sessions — with the governance wrinkle that user-directed rules (“from now on always X”) are pre-approved by construction, while agent-proposed amendments need a review gate. Content placement rule: “if it should follow you everywhere, it belongs in the identity/constitution file; if it belongs to a project, it belongs in the project rules file.” A companion tools.md documents the environment (per-machine CLI inventory, auth notes, known failure modes) — distinct from skills, which document workflows.

14. Interrupt taxonomy + open-decision batching

Exactly three legitimate reasons to stop and ask mid-run: (a) irreversible or high-risk choices, (b) credentials/access/product decisions that cannot be inferred, (c) conflicting requirements in the repo or prior instructions. Everything else: make a reasonable assumption, proceed, and note it — “permission-seeking for routine engineering is prohibited.” Non-blocking questions are never asked mid-run; they accumulate and land at run end under an explicit “Open decisions” heading — a structured artifact answerable retroactively, distinct from run-blocking needs-input. Two refinements from adjacent corpora: categorical carve-outs beat risk scoring alone (users want a named always-ask list — framework/cloud/database choices are “joint decisions” regardless of computed risk); and interrogation itself has craft — one question at a time (multiple at once “is bewildering”), each question ships WITH the agent’s recommended answer, and a facts-vs-decisions split: discoverable facts get looked up, only genuine decisions get asked. The router variant: “One question, then commit” — ask exactly one disambiguating observation, never guess between two plausible intents, never ask more than one. When blocked, report the exact blocker, what was attempted, evidence gathered, and the smallest human decision needed. See planning-and-decomposition.

15. Mega-prompt craft: the prompt-block library

Reusable structural blocks proven in a ~3,000-line architecture-doctrine prompt and echoed elsewhere: (a) READER CONTRACT — an explicit consumption protocol up top with a priority read order for the most binding sections first; (b) self-recitation — “write a compact local operating summary and re-read it during long runs so this prompt does not get lost in the middle” (countermeasure to lost-in-the-middle context rot); (c) explicit failure definition (“a long essay about architecture without real artifact creation is failure”) giving the model a self-check predicate; (d) forced tradeoff pairs (“working system > beautiful description; observable > clever; measurable result > unverified claim”); (e) every default carries a “Reason:” so the model generalizes the choice correctly when circumstances differ; (f) enumerated anti-patterns — negative space stated, not implied; (g) imperative bootstrap (“INITIAL ACTIONS YOU MUST TAKE NOW”, 12 first steps) so the prompt starts behavior instead of describing an end state; (h) anti-drift re-checks (“if you drift into chat-only behavior, stop and return to files/tasks/verification”); (i) “steal the idea that…” framing for references — each citation states the single extractable pattern plus an explicit inclusion/exclusion rule. Stage prompts in engines should inherit (a), (b), (c), and the blocked-report format. See workflow-engine-design.

16. Execution contracts with structural tool denial

An orchestration skill/command carries an “Execution Contract (non-negotiable)” section — forbidden from doing the worker’s job itself, forbidden from skipping ask-user steps, with fail-closed guardrails (“if the delegate does not return a numeric value and unit, DO NOT proceed to Step 3”) — and, crucially, the prompt contract is backed by harness enforcement: the worker’s tool allowlist structurally excludes what it must not do (e.g. no network tools), with the skill text noting “if you find yourself needing one, that is a signal you are bypassing the skill.” Role-bleed becomes structurally impossible, not just discouraged. The same idea run-scoped: skills can install session-scoped hooks on invocation — a /careful mode blocking rm -rf/DROP TABLE/force-push via pre-tool hooks, a /freeze mode blocking edits outside a directory — temporary guard policies auto-expiring with the run. See security-and-guardrails and multi-agent-orchestration.

17. The router skill / single front-door pattern

One NL entry point = classify → depth → announce → gate → route: (1) classify intent into a closed set (one proven set: CREATE/EVOLVE/POLISH/REMOVE/FIX/AUDIT from verb signals, with taxonomy-gap escapes); (2) infer a depth mode (fast/balanced/production) from a single canonical risk-signal registry cited by-reference from every skill “so the signals can’t drift apart”; (3) announce a structured plan block (Detected / Risk / Mode / numbered pipeline) — persisted to a run-state file because “on compaction the announced pipeline is the first thing lost”; (4) delegate to exactly ONE skill per run; multi-intent prompts become announced sequential calls; (5) report and stop — publishing (commit/PR) is always a separate human-initiated step. Mode-safety override: an explicit user mode=fast NEVER silently wins against a high-risk signal — the conflict surfaces as an informed-consent question, then the choice is honored. Deterministic evidence precedes LLM judgment: one glob/grep probe for the named artifact decides EVOLVE-vs-CREATE before any model call. Host-portability fallback: if the skill-invocation tool is unavailable, read the routed SKILL.md and execute inline, announcing the degradation — “the SKILL.md is the engine.”

18. Domain-SOP skills with embedded verification

The template for deep domain skills (proven on financial modeling, generalizable to any produce-and-audit workflow): a numbered 10-step workflow carrying (a) NON-NEGOTIABLE invariants (“if you catch yourself computing something and hardcoding the result — STOP”); (b) mandatory user checkpoints after each phase, not only at the end; (c) a deterministic validate-until-clean loop (run the bundled validator script until typed success, zero errors) instead of self-assessment; (d) provenance comments on every input (“Source: [system], [date], [reference], [url]”) with unsourced figures tagged [UNSOURCED] rather than estimated; (e) numeric sanity bands as tripwires; (f) a final checklist; troubleshooting split to an on-demand file. Companion pattern: QC as a separate read-only skill with a fixed severity enum, “absence is a finding” affirmative reporting (“‘no inconsistencies found’ is a finding, not an absence of one”), and report-before-fix. Skills that decide dispositions never approve: a rules-grid skill “decides nothing, it scores and routes” — every rule yields one row {rule_id, outcome, evidence}, “no outcome without a rule reference,” and only conjunctive pass-conditions route to auto-clear; everything else goes to a human. See verification-and-judging.

19. Domain skill packs and distribution

Packaging conventions that survived contact with users: a two-file marketplace manifest (registry wrapper + plugin manifest with a skills array of relative paths) makes any git repo an installable skill source; one canonical body, N export adapters (constitution snippet, IDE rule file, plugin dir) beats hand-synced copies — manual multi-format sync is a real, observed drift liability; a domain pack bundles skills + workflow templates + slash commands + connector config + agent presets with version-gated updates and a ref-integrity linter; packs ship a setup skill — a one-time configurator that binds abstract roles (issue tracker, label mapping, docs location) to the concrete environment; a lifecycle with buckets (in-progress → promoted → deprecated with successor pointer, still listed and redirecting — distinct from archived/gone). Federation at scale: multi-source hubs (any repo with skills/<slug>/SKILL.md as a “tap”; a /.well-known/skills/index.json site convention; direct URL) with mandatory install-time security scanning, a trust ladder (builtin → official → trusted → community), a provenance lockfile (URL + content hash + scanner verdict), quarantine, and hash-manifest bundled-sync: origin hashes recorded so user-edited bundled skills are never clobbered on update, with explicit reset/restore verbs. Skill bundles — a YAML naming a group of skills + one instruction, invoked as a unit and injected as a fresh user message so it doesn’t invalidate the prompt prefix cache — cover the “always these five together” case. See ecosystem-and-interop.

20. The idea-file / pattern-seed genre

A distinct artifact class between skill and template: a deliberately abstract pattern document (“everything above is optional and modular — pick what’s useful”) handed to an agent, which then co-instantiates a bespoke implementation with the user — the agent parameterizes the pattern per domain, and learned per-user workflow preferences get documented back into the resulting schema/rules file “for future sessions.” Not procedural know-how (skill), not fixed slots (template): a seed. Its market validation (5k+ stars for 75 lines) shows users want to hand agents patterns, not parameter forms; consuming such files is a planning mode of its own. See planning-and-decomposition and knowledge-pipelines.

21. Slash-command workflows as terse guard-railed contracts

Each user-invoked command is a short file with a fixed frame: purpose; Step-0 guardrails (preconditions — clean working tree, on-main — plus explicit stop-and-ask conditions); numbered steps with exact commands; and postconditions (end on main, verify the PR state reads MERGED “never CLOSED”, verify CI green, exit clean). Guardrail steps and postcondition checks are first-class item types, not prose. A companion handoff/pickup pair treats session continuity as prompt craft: handoff bundles scope/status (done/outstanding/blockers), VCS state + unpushed commits, running processes with ready-to-paste reconnect commands, tests run + outcomes, ordered next steps, and risks/gotchas (flaky tests, credentials, fragile areas); pickup is the inverse — read pointer docs, list docs by trigger, check VCS/CI state, note last tests, plan the next 2-3 actions, execute. A “summarize from here” variant generates the handoff note “from the agent’s future self to its previous iteration.”

22. Glossary and docs-page conventions (vocabulary as prompt infrastructure)

A per-project ubiquitous-language glossary (CONTEXT.md-genre) is the named fix for agent verbosity and wrong jargon: per term — definition + terms to avoid + relationships + a resolved-ambiguities ledger recording retired words. Precise shared vocabulary is itself token compression: strong pretrained words (seam, tracer bullet, depth, locality) anchor behavior in few tokens, and skill briefs carry the vocabulary for naming consistency across parallel workers. Decision records are kept only for load-bearing rejections “a future explorer would need” — skip ephemeral/self-evident reasons; a .out-of-scope/ rejection knowledge base is checked at propose-time so rejected ideas are never re-proposed. Human-facing docs pages for skills use a fixed frame: Quickstart / What it does (including one defining constraint as plain prose) / When to reach for it (invocation mode + trigger boundary) / optional “It’s working if” observable signals / “Where it fits” naming the skill’s role + neighbors with because-clauses + a router link.

23. Second-model consultation as a bundling skill

A one-shot “ask a different frontier model” primitive, packaged as a skill: bundle a prompt + the smallest file set containing the truth into one request; --dry-run/--files-report preview token costs before spending; sessions are stored and reattachable (consults can take 10-60 min — reattach rather than re-run on timeout); paid API runs require explicit user consent; secrets are never attached. The prompt contract for any zero-context delegate is a required-fields schema: goal, exact paths, constraints, non-goals, expected proof (the exact test command), output shape — “spec quality decides success.” Escalation rule: after two failed iteration rounds with a delegate, take over directly; review of delegate output is “never delegated, never skipped,” and delegate claims are advisory until verified against disk. See multi-agent-orchestration.

24. Identity files and the prompt-stack order

A single owner-editable persona file is prompt slot #1 and replaces the hardcoded default identity — “not just an additive layer” — loaded only from the instance home, never the CWD (“the personality belongs to the instance itself”), with a built-in fallback if empty/unreadable, and injection-scanned like any other context file. One production prompt-stack order, useful as a reference layout: (1) identity file, (2) tool-aware guidance, (3) memory/user context, (4) skills guidance, (5) project context files (AGENTS.md/IDE rules), (6) timestamp, (7) platform formatting, (8) session-level personality overlays. Session overlays (named preset personalities) layer on top without touching the baseline. Rule of thumb repeated across systems: instance-global identity vs project-scoped rules are different files with different load paths. Injected memory snapshots are frozen per session — never mutated mid-session — explicitly to preserve the prompt prefix cache; see memory-architectures.

25. Dynamic context injection at invocation

Two mechanisms for making skill/command bodies live rather than static: (a) an inline shell-substitution idiom — a marked command embedded in the body runs at invocation and its output is injected into the prompt (gated by the same tool policy as everything else); (b) named positional arguments in frontmatter (argument-hint, arguments → $name substitution) so one skill parameterizes cleanly. Per-skill declared config (key/description/default/prompt) resolves from user config at load and injects as context; declared required_environment_variables (name/prompt/help) are collected securely — local CLI only, “messaging surfaces never collect secrets in chat” — and auto-passed into sandboxes.

Patterns & compositions

• Classify → gate → route → one skill per run (mechanism 17) composed over a corpus authored per mechanisms 1-2 and validated per mechanisms 6-7 is the full production shape of “NL front door over a skill library.”
• Distill → package → measure → evolve: behavioral principles distilled per mechanism 12, packaged with self-tests and paired examples (10), instrumented with usage/effectiveness telemetry (8-9), repaired through the four-action evolution loop (11). Multiple independent systems converge on description-only repair as a distinct action.
• Constitution + skills + docs three-layer split: hard rules in one canonical file (13), workflows in skills (1-5), environment facts in a tools inventory and read_when-tagged docs (9). Each layer has its own surfacing economics.
• Prompt contract backed by structural rails: execution contracts (16) + validation-at-write (6) + routing contract tests (7) — every “must” appears twice, once as prose and once as a mechanical check.
• Skills-as-procedural-memory: agent-created skills (creation triggers: complex tasks of 5+ tool calls, error recovery, user corrections, discovered workflows; a /learn verb converting sources into skills) flow through a write-approval gate (pending/diff/approve/reject staging, auto-writes tagged [auto]) into the curated corpus — the skill library IS the agent’s procedural memory. See memory-architectures and self-improvement-loops.
• One source, two wrappers: an agent’s canonical system prompt used directly by an interactive wrapper and referenced-with-appended-delta by a headless deployment (“You are running headless; produce files in ./out/”) — deployment differences as appends, never forks (composes with mechanism 19’s drift discipline).

Anti-patterns & failure modes

• Description-as-summary instead of description-as-trigger. The body never loads because nothing matched; the corpus treats undertriggering as a first-class, measurable defect.
• Negation-heavy rules. Prohibitions backfire; state the positive target behavior, keep prohibitions only as guardrails paired with alternatives.
• Trigger synonyms restating one branch — pure duplication that pads the always-in-context budget without widening coverage.
• Vague completion criteria invite premature completion; every ordered step needs a checkable criterion.
• Railroading: prescribing steps instead of goals + constraints strips the model of recovery ability; reserve rigid steps for low-freedom cliffs (mechanism 5).
• Stating the obvious — lines the model already obeys are no-ops that pay context rent; the fix is a stronger leading word or deletion.
• Prompt-only enforcement of mandatory steps. Prompt-level skills skip steps probabilistically; a gist-genre rule file with no hooks/schema “trusts the prompt” — and the corpus’s own doctrine contradicts it: mandatory steps belong in deterministic rails.
• Manual multi-copy sync of one skill body across formats/locations drifts; observed even in flagship reference repos (a shipped connector config with 2 JSON syntax errors that the repo’s own linter didn’t cover).
• Crediting/blaming skills by prompt-time injection rather than actual reads — corrupts every downstream effectiveness statistic.
• Deleting correct-but-unused skill content as a “repair” when the real failure was the agent not consulting it — an attribution error (skill vs agent vs environment must be classified before editing anything).
• README/CHANGELOG inside skill folders — non-loadable ceremony in a context-budgeted artifact.
• Skill state in the skill directory — upgrades wipe it; persistent data needs a stable data dir.
• Blanket git add . in imported rule-packs — sweeps co-tenant agents’ edits; popular imported guidelines can directly contradict locally-learned lessons and must rank below them.

Quantitative findings

• ~80-line behavioral skill: ~191k GitHub stars; 75-line idea file: 5k+ stars/forks in ~3 months — short prompt artifacts are the highest-adoption genre.
• Description caps in the open skill spec: ≤1024 chars; name 1-64 chars [a-z0-9-]. One harness adds a 1,536-char per-skill listing cap within a ~15k-char total skill-descriptions budget.
• Disclosure budgets: metadata ~100 words always-loaded; body <500 lines / <5k tokens; references >10k words require grep patterns.
• Skill-list render budget observed at 2% of context window; token cost modeled as ceil(utf8_bytes/4); truncation fallback: full descriptions → equal truncation → omitted lines (default window 272k when unknown).
• Per-skill base listing cost ~24 tokens; a manifest-first approach loaded ~2k tokens for 13 skills vs 20-40k tokens per call for wholesale loading (~10-20× saving).
• Skill catalog injection: ~3k tokens for a full name/description/category listing; one proxy design falls back from full to compact (no descriptions) above a 30k-char budget; instruction: read at most ONE SKILL.md after selecting.
• Skill-routing accuracy target used in practice: ≥85% correct selection on a sample-prompt fixture suite.
• Effectiveness-weighted retrieval: score = similarity × (0.3 + 0.7 × effectiveness) where effectiveness = positive/injected (default 0.5); near-duplicate pruning at pairwise embedding similarity > 0.9.
• Constitution/rules file guidance: keep under ~200 lines; context rot observed ~300-400k tokens on 1M-context models; effective-work “dumb zone” begins ~40% context fill (aggressive users stay <30%).
• Up to 5 skill-invocation tokens stack in one message in one production harness; curator idle-trigger defaults observed: run when 168h elapsed AND agent idle ≥2h; deterministic decay: unused 30d → stale, 90d → archived.
• Model-based permission classification (a harness-layer alternative to prompt rules) cut permission prompts 84% internally — evidence for “deterministic/config enforcement over prompt instruction.”
• One organization runs hundreds of internal skills organized into a 9-category taxonomy (library/API reference, product verification, data fetching & analysis, business-process automation, scaffolding, code quality & review, CI/CD, runbooks, infrastructure ops) — “the best skills fit cleanly into one; the confusing ones straddle several” (straddlers are split candidates).
• A 37-skill production pack enforces exactly 4 finding severities (extra levels forbidden), sub-300-word explore-agent reports, and a mandatory binary auto-fixable flag per finding (“when in doubt, false”).
• Second-model consult sessions run 10-60 min; delegate escalation threshold: 2 failed iteration rounds, then take over.
• Skill-evolution pipelines cap evidence context at ~30 sessions per prompt, clip tool-call fields to ~400 chars and 8 tools/step; skill-stats flush every 10 mutations.
• Behavioral memory budgets that pair with skill surfacing: ~2,200 chars (~800 tokens, 8-15 entries) for agent notes injected always-on, with overflow-as-error rather than silent compaction.

Open questions

• Measuring undertriggering: “invocations vs expected trigger frequency” needs an expectation model; no source shows how to set expectations except manual judgment.
• Auto-generated trigger descriptions: flagging them for review (description_auto) is established; whether LLM-written descriptions can match hand-tuned routing quality at scale is unmeasured.
• Glob/context auto-attach at scale: the fourth activation mode is proven in IDE rules; whether path-conditioned skill injection stays precise in large monorepos (vs becoming another always-on tax) is untested in the corpus.
• Router-skill threshold: “~7 user-invoked skills before adding a router” is a working heuristic from human memory limits, not measured.
• Cross-harness portability: skills carrying per-harness config side-by-side works today; no source resolves how harness-specific frontmatter fields (effort, context-fork, hooks) should degrade on harnesses that ignore them.
• Behavioral-skill durability: do guardrail skills lose effect as base models internalize the same behaviors (turning them into no-ops per mechanism 4), and should the cleaner therefore re-test guardrails against the current model rather than only checking usage?