# Shadow > AI operator learning library and agent-skill kit by shiny.sh. Use this index to pick relevant atoms, then fetch the raw markdown URL listed on each line. Total atoms: 146 Generated: 2026-07-20 ## anti-patterns ### anti-patterns - [Giving agents blanket permission too early](https://shadow.shiny.sh/anti-patterns/giving-agents-blanket-permission-too-early/) — raw: https://shadow.shiny.sh/anti-patterns/giving-agents-blanket-permission-too-early.md; slug: giving-agents-blanket-permission-too-early; type: anti-patterns; department: anti-patterns; group: anti-patterns; persona: OP BD TL; level: intermediate Anti-pattern: rolling out agents with broad production permissions before anyone has calibrated trust. Covers the failure modes and the staged sandbox-to-scoped-write progression to use instead. - [Letting the agent edit its own completion contract](https://shadow.shiny.sh/anti-patterns/letting-it-edit-its-own-completion-contract/) — raw: https://shadow.shiny.sh/anti-patterns/letting-it-edit-its-own-completion-contract.md; slug: letting-it-edit-its-own-completion-contract; type: anti-patterns; department: anti-patterns; group: anti-patterns; persona: OP BD; level: intermediate Anti-pattern: an agent silently edits its own plan file mid-execution to redefine "done", then declares success. Read for the two-file plan/log fix, explicit read-only constraints, and stop-and-check markers. - [Poison strings in prompts](https://shadow.shiny.sh/anti-patterns/poison-strings-in-prompts/) — raw: https://shadow.shiny.sh/anti-patterns/poison-strings-in-prompts.md; slug: poison-strings-in-prompts; type: anti-patterns; department: anti-patterns; group: anti-patterns; persona: OP BD; level: beginner Anti-pattern: typing control signals or panic ("stop", stray pastes, vague corrections) into the chat box, where they pollute context and survive compaction. Covers common triggers, recovery, and prevention. - [Reading every line of agent output](https://shadow.shiny.sh/anti-patterns/reading-every-line-of-output/) — raw: https://shadow.shiny.sh/anti-patterns/reading-every-line-of-output.md; slug: reading-every-line-of-output; type: anti-patterns; department: anti-patterns; group: anti-patterns; persona: OP BD; level: beginner The operator runs the agent. Each tool call produces output: file reads, command results, search hits, JSON returned by an MCP server. The operator reads every line. Approves each action individually. Asks the agent to explain its reasoning before continuing. - [Trying to validate everything upstream](https://shadow.shiny.sh/anti-patterns/trying-to-validate-everything-upstream/) — raw: https://shadow.shiny.sh/anti-patterns/trying-to-validate-everything-upstream.md; slug: trying-to-validate-everything-upstream; type: anti-patterns; department: anti-patterns; group: anti-patterns; persona: TL OP BD; level: intermediate A team discovers that downstream data is dirty. The instinct is to fix it at the source: add validation rules to the form, block save until every required field is populated, force the field team to comply before any record can move forward. - [Two sources of truth](https://shadow.shiny.sh/anti-patterns/two-sources-of-truth/) — raw: https://shadow.shiny.sh/anti-patterns/two-sources-of-truth.md; slug: two-sources-of-truth; type: anti-patterns; department: anti-patterns; group: anti-patterns; persona: OP BD; level: beginner Anti-pattern: the same fact lives in two places (CLAUDE.md vs filesystem, skill vs doc) and they drift into contradiction. Read for the one-canonical-source rule, detection smells, and recovery steps. - [Validation that edits product files](https://shadow.shiny.sh/anti-patterns/validation-that-edits-product-files/) — raw: https://shadow.shiny.sh/anti-patterns/validation-that-edits-product-files.md; slug: validation-that-edits-product-files; type: anti-patterns; department: anti-patterns; group: anti-patterns; persona: BD TL; level: intermediate Treat validation commands that rewrite product files as implementation work, not independent evidence. - [Vendor-shipped skills conflicting with operator skills](https://shadow.shiny.sh/anti-patterns/vendor-skill-conflicts-with-operator-skill/) — raw: https://shadow.shiny.sh/anti-patterns/vendor-skill-conflicts-with-operator-skill.md; slug: vendor-skill-conflicts-with-operator-skill; type: anti-patterns; department: anti-patterns; group: anti-patterns; persona: OP BD; level: intermediate Anti-pattern: a vendor-shipped harness skill overlaps with an operator-authored skill and the agent picks the wrong one. Read for narrowing triggers, auditing shipped skills, and disabling or routing around conflicts. ## cases ### cases - [AcmeMed: failing claims sync](https://shadow.shiny.sh/cases/acmemed-failing-claims-sync/) — raw: https://shadow.shiny.sh/cases/acmemed-failing-claims-sync.md; slug: case-acmemed-failing-claims-sync; type: cases; department: cases; group: cases; persona: OP TL; level: intermediate Case study: diagnosing AcmeMed's failing Salesforce-Boomi-EasyClaim claims sync with AI-clustered exceptions and a v2 spec check, then shipping a downstream block plus exception report instead of upstream validation. - [AcmeMed: live firewall recovery](https://shadow.shiny.sh/cases/acmemed-firewall-recovery/) — raw: https://shadow.shiny.sh/cases/acmemed-firewall-recovery.md; slug: case-acmemed-firewall-recovery; type: cases; department: cases; group: cases; persona: OP BD; level: advanced Case study: recovering a live Cisco FTD firewall in a broken HA state with no lab device. Shows parallel diagnostic and planning sessions, .env files for credentials, backups first, and command-by-command verification. - [AcmeMed: renaming a misleading CRM field](https://shadow.shiny.sh/cases/acmemed-field-rename/) — raw: https://shadow.shiny.sh/cases/acmemed-field-rename.md; slug: case-acmemed-field-rename; type: cases; department: cases; group: cases; persona: OP; level: beginner A small, bounded scenario useful as a first hands-on exercise for a new operator. The whole task is one Salesforce field-label change. - [Lawsuit evidence prep with Obsidian and Claude](https://shadow.shiny.sh/cases/lawsuit-evidence-prep/) — raw: https://shadow.shiny.sh/cases/lawsuit-evidence-prep.md; slug: case-lawsuit-evidence-prep; type: cases; department: cases; group: cases; persona: KW; level: beginner Case study: a knowledge worker preps lawsuit evidence by migrating 25 years of OneNote notes and email into an Obsidian vault Claude can query. Shows why data shape matters more than tooling for personal AI work. - [Software team AI onboarding (engineering, regulated)](https://shadow.shiny.sh/cases/software-team-ai-onboarding/) — raw: https://shadow.shiny.sh/cases/software-team-ai-onboarding.md; slug: case-software-team-ai-onboarding; type: cases; department: cases; group: cases; persona: TL BD; level: intermediate A flagship case for the team-lead and builder personas. A small software engineering team at a medical-device company is being onboarded to agentic AI tools, by an external AI champion, in a regulated environment where production code requires human review. - [The engineering team lead wants one starter setup; the coach pushes back](https://shadow.shiny.sh/cases/engineering-lead-wants-standardization/) — raw: https://shadow.shiny.sh/cases/engineering-lead-wants-standardization.md; slug: case-engineering-lead-wants-standardization; type: cases; department: cases; group: cases; persona: TL BD; level: intermediate A team lead pushes for one standard harness and model; the coach argues for shared conventions with individual tooling. Read this when planning team AI adoption and deciding what to standardize. - [The operator can't let the agent run](https://shadow.shiny.sh/cases/operator-let-it-run/) — raw: https://shadow.shiny.sh/cases/operator-let-it-run.md; slug: case-operator-let-it-run; type: cases; department: cases; group: cases; persona: OP TL; level: beginner A coaching session, hours in. The operator-trainee is working on a real task. The agent is producing output. The operator reads every line. The agent's pace dramatically exceeds the operator's reading pace. The session drags. - [The operator can't picture where the folders go](https://shadow.shiny.sh/cases/operator-folder-structure/) — raw: https://shadow.shiny.sh/cases/operator-folder-structure.md; slug: case-operator-folder-structure; type: cases; department: cases; group: cases; persona: OP; level: beginner A coaching session, several hours in. The operator-trainee has been using Claude Code for the first time on a real Salesforce task. The coach is explaining how to organize projects. - [The operator confuses escape with stop](https://shadow.shiny.sh/cases/operator-escape-vs-stop/) — raw: https://shadow.shiny.sh/cases/operator-escape-vs-stop.md; slug: case-operator-escape-vs-stop; type: cases; department: cases; group: cases; persona: OP; level: beginner Mid-onboarding session. The operator-trainee is using Claude Code for the first time on a real task. The agent is in the middle of running. The operator wants to interrupt it because something looks off. - [The team lead resists the downstream-fix-first move](https://shadow.shiny.sh/cases/team-lead-upstream-vs-downstream/) — raw: https://shadow.shiny.sh/cases/team-lead-upstream-vs-downstream.md; slug: case-team-lead-upstream-vs-downstream; type: cases; department: cases; group: cases; persona: TL OP; level: intermediate A multi-hour debugging session. The integration is failing; the data is dirty; the team lead and the coach are debating how to respond. ## concepts ### agent-patterns - [Custom agent platforms (Hermes, Open Claw, and the build-your-own option)](https://shadow.shiny.sh/concepts/universal/agent-patterns/custom-agent-platforms/) — raw: https://shadow.shiny.sh/concepts/universal/agent-patterns/custom-agent-platforms.md; slug: custom-agent-platforms; type: concepts; department: concepts; group: agent-patterns; persona: BD TL; level: advanced Maps the spectrum from vendor harnesses to operator-built agent platforms (Hermes, Open Claw) and when building your own is justified. Read before deciding an agent need has outgrown Claude Code or Codex. - [Env file for secrets](https://shadow.shiny.sh/concepts/universal/agent-patterns/env-file-for-secrets/) — raw: https://shadow.shiny.sh/concepts/universal/agent-patterns/env-file-for-secrets.md; slug: env-file-for-secrets; type: concepts; department: concepts; group: agent-patterns; persona: OP BD; level: intermediate An environment file (commonly .env) is a plain-text file storing key/value pairs the agent (or any program) can read at runtime without those values ever appearing in conversational input or output. - [Parent control plane](https://shadow.shiny.sh/concepts/universal/agent-patterns/parent-control-plane/) — raw: https://shadow.shiny.sh/concepts/universal/agent-patterns/parent-control-plane.md; slug: parent-control-plane; type: concepts; department: concepts; group: agent-patterns; persona: BD TL; level: advanced The operating model where a parent agent routes, decomposes, dispatches, integrates, and closes delegated work while child agents own bounded packets. - [Plan files](https://shadow.shiny.sh/concepts/universal/agent-patterns/plan-files/) — raw: https://shadow.shiny.sh/concepts/universal/agent-patterns/plan-files.md; slug: plan-files; type: concepts; department: concepts; group: agent-patterns; persona: OP BD; level: intermediate A plan file is a markdown document that captures the intent of a multi-step task in a form that survives session resets. It lives in the project (typically plans/.md) and is the contract the agent honors across /clear, /compact, and new sessions. - [Skill library operating model](https://shadow.shiny.sh/concepts/universal/agent-patterns/skill-library-operating-model/) — raw: https://shadow.shiny.sh/concepts/universal/agent-patterns/skill-library-operating-model.md; slug: skill-library-operating-model; type: concepts; department: concepts; group: agent-patterns; persona: BD TL; level: intermediate A project-local skill library is an operating model: skills are registered, discoverable, scoped to durable workflows, and kept free of contradiction. - [Sub-agents](https://shadow.shiny.sh/concepts/universal/agent-patterns/sub-agents/) — raw: https://shadow.shiny.sh/concepts/universal/agent-patterns/sub-agents.md; slug: sub-agents; type: concepts; department: concepts; group: agent-patterns; persona: BD; level: intermediate A sub-agent is a worker spawned with its own isolated context, returning only a summary to its parent. Covers when to spawn, when not to, and the cost implications. Read when long subtasks are bloating a session. ### ai-fundamentals - [Compaction](https://shadow.shiny.sh/concepts/universal/ai-fundamentals/compaction/) — raw: https://shadow.shiny.sh/concepts/universal/ai-fundamentals/compaction.md; slug: compaction; type: concepts; department: concepts; group: ai-fundamentals; persona: OP BD; level: intermediate Compaction summarizes older conversation history so the context window stays usable, but it is lossy and invalidates the KV cache. Read to learn when to compact, when to reset instead, and what to save first. - [Context window](https://shadow.shiny.sh/concepts/universal/ai-fundamentals/context-window/) — raw: https://shadow.shiny.sh/concepts/universal/ai-fundamentals/context-window.md; slug: context-window; type: concepts; department: concepts; group: ai-fundamentals; persona: OP BD TL; level: beginner The context window is the finite token buffer holding everything the model can see, and models degrade as it fills. Read to learn the symptoms of a full window and the write-reset-run habit that keeps sessions sharp. - [KV cache](https://shadow.shiny.sh/concepts/universal/ai-fundamentals/kv-cache/) — raw: https://shadow.shiny.sh/concepts/universal/ai-fundamentals/kv-cache.md; slug: kv-cache; type: concepts; department: concepts; group: ai-fundamentals; persona: BD; level: intermediate The key-value cache is the model's internal representation of the conversation so far, retained across turns so the model does not have to reprocess prior tokens on every step. - [Lookups vs telling the agent](https://shadow.shiny.sh/concepts/universal/ai-fundamentals/lookups-vs-tell-it/) — raw: https://shadow.shiny.sh/concepts/universal/ai-fundamentals/lookups-vs-tell-it.md; slug: lookups-vs-tell-it; type: concepts; department: concepts; group: ai-fundamentals; persona: OP BD; level: beginner Agents trust information they look up more than information the operator asserts. Explains why letting the agent fetch beats telling it, and the cases where telling (CLAUDE.md, team conventions) is still right. - [Tokens and pricing](https://shadow.shiny.sh/concepts/universal/ai-fundamentals/tokens-and-pricing/) — raw: https://shadow.shiny.sh/concepts/universal/ai-fundamentals/tokens-and-pricing.md; slug: tokens-and-pricing; type: concepts; department: concepts; group: ai-fundamentals; persona: OP BD TL EX; level: beginner Tokens are how models count text and how providers bill you; input, output, and cache rates all differ. Read for the 2026 plan-tier landscape and the operator habits that keep per-session token spend down. ### ai-judgment - [Sandbox-first](https://shadow.shiny.sh/concepts/universal/ai-judgment/sandbox-first/) — raw: https://shadow.shiny.sh/concepts/universal/ai-judgment/sandbox-first.md; slug: sandbox-first; type: concepts; department: concepts; group: ai-judgment; persona: OP BD TL; level: beginner The discipline of always running new, risky, or unproven AI work in an environment where the worst-case outcome is bounded. - [Trust progression](https://shadow.shiny.sh/concepts/universal/ai-judgment/trust-progression/) — raw: https://shadow.shiny.sh/concepts/universal/ai-judgment/trust-progression.md; slug: trust-progression; type: concepts; department: concepts; group: ai-judgment; persona: OP BD TL; level: beginner The single most important operator skill is calibrating how much to trust the agent in the current situation — and changing that calibration as you learn what it does well and badly. - [Upstream vs downstream fix](https://shadow.shiny.sh/concepts/universal/ai-judgment/upstream-vs-downstream-fix/) — raw: https://shadow.shiny.sh/concepts/universal/ai-judgment/upstream-vs-downstream-fix.md; slug: upstream-vs-downstream-fix; type: concepts; department: concepts; group: ai-judgment; persona: OP BD TL; level: intermediate Compares fixing data-quality problems at the source form versus filtering downstream in the pipeline. Read when deciding where to repair a failing integration and how to sequence a stopgap into a permanent fix. ### ai-orgs - [Bottlenecks and glue work](https://shadow.shiny.sh/concepts/universal/ai-orgs/bottlenecks-and-glue-work/) — raw: https://shadow.shiny.sh/concepts/universal/ai-orgs/bottlenecks-and-glue-work.md; slug: bottlenecks-and-glue-work; type: concepts; department: concepts; group: ai-orgs; persona: TL EX OP; level: intermediate A bottleneck is a person, system, or process that gates the throughput of everyone else. Glue work is the manual reconciliation, exception-handling, hand-coordination, and ad-hoc problem-solving that exists because the rest of the system is incomplete. - [Build vs buy (under AI)](https://shadow.shiny.sh/concepts/universal/ai-orgs/build-vs-buy/) — raw: https://shadow.shiny.sh/concepts/universal/ai-orgs/build-vs-buy.md; slug: build-vs-buy; type: concepts; department: concepts; group: ai-orgs; persona: EX TL BD; level: intermediate Explains how agentic AI shifts the build-vs-buy math toward buying core systems and building the operational glue in-house. Read when weighing a vendor AI product against a champion-built alternative. - [Data quality as the real blocker](https://shadow.shiny.sh/concepts/universal/ai-orgs/data-quality-as-real-blocker/) — raw: https://shadow.shiny.sh/concepts/universal/ai-orgs/data-quality-as-real-blocker.md; slug: data-quality-as-real-blocker; type: concepts; department: concepts; group: ai-orgs; persona: TL OP EX; level: beginner Argues that failed automations and AI rollouts usually trace to dirty data that humans were silently absorbing, not the system itself. Read when an agent project stalls and you need to plan the data-cleanup work it exposes. - [Humans can't write agent instructions](https://shadow.shiny.sh/concepts/universal/ai-orgs/humans-cant-write-agent-instructions/) — raw: https://shadow.shiny.sh/concepts/universal/ai-orgs/humans-cant-write-agent-instructions.md; slug: humans-cant-write-agent-instructions; type: concepts; department: concepts; group: ai-orgs; persona: TL EX BD; level: intermediate Argues that non-trivial agent instructions are too long and conditional for humans to write by hand, so agents should draft them and experts edit. Read when authoring skills or evaluating vendor agent products. - [Personal vs work AI accounts](https://shadow.shiny.sh/concepts/universal/ai-orgs/personal-vs-work-accounts/) — raw: https://shadow.shiny.sh/concepts/universal/ai-orgs/personal-vs-work-accounts.md; slug: personal-vs-work-accounts; type: concepts; department: concepts; group: ai-orgs; persona: OP BD TL KW; level: beginner Covers whether operators should use personal or business AI accounts, including pricing realities, the data-training opt-out, and when to keep accounts separate. Read when rolling out AI subscriptions to a team. - [The AI champion role](https://shadow.shiny.sh/concepts/universal/ai-orgs/ai-champion-role/) — raw: https://shadow.shiny.sh/concepts/universal/ai-orgs/ai-champion-role.md; slug: ai-champion-role; type: concepts; department: concepts; group: ai-orgs; persona: TL EX BD; level: intermediate Describes the AI champion, the one person who absorbs AI fluency first and brings it to the rest of the team. Read when naming, supporting, or becoming the role that makes org-wide AI adoption actually stick. - [Token usage as optics](https://shadow.shiny.sh/concepts/universal/ai-orgs/token-usage-as-optics/) — raw: https://shadow.shiny.sh/concepts/universal/ai-orgs/token-usage-as-optics.md; slug: token-usage-as-optics; type: concepts; department: concepts; group: ai-orgs; persona: TL EX BD; level: intermediate Explains why token usage is a misleading productivity metric that makes trainees look busy and coaches look idle. Read when leadership measures AI adoption by token dashboards and you need throughput-shaped metrics instead. ### claude-code - [CLAUDE.md](https://shadow.shiny.sh/concepts/claude/claude-code/claude-md/) — raw: https://shadow.shiny.sh/concepts/claude/claude-code/claude-md.md; slug: claude-md; type: concepts; department: concepts; group: claude-code; persona: OP BD; level: beginner CLAUDE.md is the standing instructions file Claude Code reads at the start of every session in a project. It lives at the project root. - [Dangerously skip permissions](https://shadow.shiny.sh/concepts/claude/claude-code/dangerously-skip-permissions/) — raw: https://shadow.shiny.sh/concepts/claude/claude-code/dangerously-skip-permissions.md; slug: dangerously-skip-permissions; type: concepts; department: concepts; group: claude-code; persona: OP BD; level: intermediate A Claude Code permission mode in which the agent executes commands and edits files without per-action approval. The label is intentional — dangerously — to signal that the operator has assumed responsibility for whatever happens. - [Escape vs stop](https://shadow.shiny.sh/concepts/claude/claude-code/escape-vs-stop/) — raw: https://shadow.shiny.sh/concepts/claude/claude-code/escape-vs-stop.md; slug: escape-vs-stop; type: concepts; department: concepts; group: claude-code; persona: OP; level: beginner Two ways an operator might try to interrupt a running agent. Only one works. - [Permission modes](https://shadow.shiny.sh/concepts/claude/claude-code/permission-modes/) — raw: https://shadow.shiny.sh/concepts/claude/claude-code/permission-modes.md; slug: permission-modes; type: concepts; department: concepts; group: claude-code; persona: OP BD; level: beginner Claude Code's three permission modes — plan, accept edits, and dangerously skip permissions — form a trust ladder. Read to learn when each mode fits the task and how Tab cycles between them. - [Plan mode](https://shadow.shiny.sh/concepts/claude/claude-code/plan-mode/) — raw: https://shadow.shiny.sh/concepts/claude/claude-code/plan-mode.md; slug: plan-mode; type: concepts; department: concepts; group: claude-code; persona: OP BD; level: beginner A Claude Code permission mode in which the agent reasons, reads, and produces a plan — but does not write files, run commands, or take side- effecting actions. Output only. - [Skills](https://shadow.shiny.sh/concepts/claude/claude-code/skills/) — raw: https://shadow.shiny.sh/concepts/claude/claude-code/skills.md; slug: skills; type: concepts; department: concepts; group: claude-code; persona: OP BD; level: beginner A skill is a folder of instructions that teaches the agent how to do a specific kind of task. When the agent encounters a situation that matches the skill, it auto-loads the skill's instructions and follows them. ### enterprise-systems - [API name vs label (Salesforce and beyond)](https://shadow.shiny.sh/concepts/enterprise-systems/api-name-vs-label/) — raw: https://shadow.shiny.sh/concepts/enterprise-systems/api-name-vs-label.md; slug: api-name-vs-label; type: concepts; department: concepts; group: enterprise-systems; persona: OP BD; level: beginner Explains the API-name vs label distinction in Salesforce and similar systems — label renames are safe, API-name renames break integrations. Read before renaming any field or asking an agent to do it. - [API-only user](https://shadow.shiny.sh/concepts/enterprise-systems/api-only-user/) — raw: https://shadow.shiny.sh/concepts/enterprise-systems/api-only-user.md; slug: api-only-user; type: concepts; department: concepts; group: enterprise-systems; persona: OP BD TL; level: intermediate A user account configured so it can authenticate via API but not log into the UI. The account exists for programs to act on behalf of, with permissions scoped to exactly what the program is supposed to do. - [Claims pipeline anatomy](https://shadow.shiny.sh/concepts/enterprise-systems/claims-pipeline-anatomy/) — raw: https://shadow.shiny.sh/concepts/enterprise-systems/claims-pipeline-anatomy.md; slug: claims-pipeline-anatomy; type: concepts; department: concepts; group: enterprise-systems; persona: OP BD TL; level: intermediate Many enterprise teams operate a claims pipeline — the workflow that takes a billable event (a service rendered, a product shipped, a procedure performed) and produces a claim submitted to a payer (insurance company, government program, customer). - [iPaaS and Boomi](https://shadow.shiny.sh/concepts/enterprise-systems/ipaas-overview/) — raw: https://shadow.shiny.sh/concepts/enterprise-systems/ipaas-overview.md; slug: ipaas-overview; type: concepts; department: concepts; group: enterprise-systems; persona: OP BD TL; level: intermediate Introduces iPaaS middleware and Boomi specifics, the failure modes common in real deployments, and where agents genuinely help. Read before auditing or debugging an integration between enterprise systems. ### guides - [Context and memory: where to start](https://shadow.shiny.sh/concepts/universal/guides/context-and-memory-cluster/) — raw: https://shadow.shiny.sh/concepts/universal/guides/context-and-memory-cluster.md; slug: context-and-memory-cluster; type: concepts; department: concepts; group: guides; persona: OP BD TL; level: beginner; version: 0.1 Guided tour of the context and memory atoms: the context window and its failure modes, the caching and pricing mechanics underneath, the plan-file habit that survives resets, and the lookup tools that stretch what the agent can know. Read this first if you don't know where to start with context management. - [Debugging and operations: where to start](https://shadow.shiny.sh/concepts/universal/guides/debugging-and-operations-cluster/) — raw: https://shadow.shiny.sh/concepts/universal/guides/debugging-and-operations-cluster.md; slug: debugging-and-operations-cluster; type: concepts; department: concepts; group: guides; persona: OP BD TL; level: intermediate; version: 0.1 Guided tour of the debugging and operations atoms: surface-first diagnosis, bounded debug content, environment readiness, the upstream-versus-downstream repair decision, and two worked recoveries from real sessions. Read this first if you don't know where to start when production is misbehaving. - [Delegation: where to start](https://shadow.shiny.sh/concepts/universal/guides/delegation-cluster/) — raw: https://shadow.shiny.sh/concepts/universal/guides/delegation-cluster.md; slug: delegation-cluster; type: concepts; department: concepts; group: guides; persona: BD TL; level: intermediate; version: 0.1 Guided tour of the delegation atoms: the concepts behind sub-agents and the parent control plane, the contract skills that shape every dispatch, and the patterns that keep multi-agent runs coherent. Read this first if you don't know where to start with delegation. - [Planning: where to start](https://shadow.shiny.sh/concepts/universal/guides/planning-cluster/) — raw: https://shadow.shiny.sh/concepts/universal/guides/planning-cluster.md; slug: planning-cluster; type: concepts; department: concepts; group: guides; persona: OP BD TL; level: beginner; version: 0.1 Guided tour of the planning atoms: the concepts that explain why plans live in files, the patterns that run them, and the skills that install the behavior. Read this first if you don't know where to start with planning. - [Tools and vendors: how to choose](https://shadow.shiny.sh/concepts/universal/guides/tools-and-vendors-cluster/) — raw: https://shadow.shiny.sh/concepts/universal/guides/tools-and-vendors-cluster.md; slug: tools-and-vendors-cluster; type: concepts; department: concepts; group: guides; persona: TL EX BD; level: beginner; version: 0.1 Guided tour of the tool and vendor landscape atoms: the major agent harnesses, the model families behind them, the in-app assistants and AI-native editors, and the supporting tools for review, multiplexing, and knowledge. Read this first when choosing or comparing tools. - [Trust and permissions: where to start](https://shadow.shiny.sh/concepts/universal/guides/trust-and-permissions-cluster/) — raw: https://shadow.shiny.sh/concepts/universal/guides/trust-and-permissions-cluster.md; slug: trust-and-permissions-cluster; type: concepts; department: concepts; group: guides; persona: OP TL BD; level: beginner; version: 0.1 Guided tour of the trust and permissions atoms: the trust-calibration mindset, the sandbox discipline, Claude Code's permission ladder, the interrupt that actually works, and the three anti-patterns that mark too little trust and too much. Read this first if you don't know where to start with agent safety. - [Validation and evidence: where to start](https://shadow.shiny.sh/concepts/universal/guides/validation-cluster/) — raw: https://shadow.shiny.sh/concepts/universal/guides/validation-cluster.md; slug: validation-cluster; type: concepts; department: concepts; group: guides; persona: BD TL OP; level: intermediate; version: 0.1 Guided tour of the validation and evidence atoms: the gate skills, the evidence patterns, the browser-smoke workflow, and the two anti-patterns that mark the boundaries. Read this first if you don't know where to start with validation. - [Working with humans: where to start](https://shadow.shiny.sh/concepts/universal/guides/working-with-humans-cluster/) — raw: https://shadow.shiny.sh/concepts/universal/guides/working-with-humans-cluster.md; slug: working-with-humans-cluster; type: concepts; department: concepts; group: guides; persona: TL OP BD EX; level: intermediate; version: 0.1 Guided tour of the atoms about the human side of agent work: how the agent communicates decisions, how broken work surfaces without stopping the line, how ship-versus-fix calls get made, and how skills and fluency spread across a team. Read this first if you don't know where to start with the people layer. ### mcp - [Context7](https://shadow.shiny.sh/concepts/claude/mcp/context7/) — raw: https://shadow.shiny.sh/concepts/claude/mcp/context7.md; slug: context7; type: concepts; department: concepts; group: mcp; persona: OP BD; level: beginner Context7 is an MCP server that fetches up-to-date library, framework, and product documentation on demand. When the agent encounters an unfamiliar API or version, it queries Context7 instead of relying on its training data. - [MCP vs CLI](https://shadow.shiny.sh/concepts/claude/mcp/mcp-vs-cli/) — raw: https://shadow.shiny.sh/concepts/claude/mcp/mcp-vs-cli.md; slug: mcp-vs-cli; type: concepts; department: concepts; group: mcp; persona: BD OP; level: intermediate Compares MCP servers and CLI tools as agent integration paths, with a prefer-the-CLI default and the cases where MCP wins. Read when deciding how to give an agent access to an external system. - [Serena (codebase-indexing MCP)](https://shadow.shiny.sh/concepts/claude/mcp/serena/) — raw: https://shadow.shiny.sh/concepts/claude/mcp/serena.md; slug: serena; type: concepts; department: concepts; group: mcp; persona: BD; level: intermediate Explains Serena, an MCP server that indexes a codebase's symbols so the agent can look up definitions and call sites fast. Read when native exploration of a very large codebase is too slow or token-expensive. - [What is MCP?](https://shadow.shiny.sh/concepts/claude/mcp/what-is-mcp/) — raw: https://shadow.shiny.sh/concepts/claude/mcp/what-is-mcp.md; slug: what-is-mcp; type: concepts; department: concepts; group: mcp; persona: OP BD; level: beginner MCP (Model Context Protocol) is a standard way for an AI agent to talk to external tools and services. It's the plug that lets the agent reach beyond its own knowledge into your filesystem, your APIs, your databases, your SaaS apps. ### models - [Claude vs ChatGPT temperament](https://shadow.shiny.sh/concepts/claude/models/claude-vs-chatgpt-temperament/) — raw: https://shadow.shiny.sh/concepts/claude/models/claude-vs-chatgpt-temperament.md; slug: claude-vs-chatgpt-temperament; type: concepts; department: concepts; group: models; persona: OP BD TL; level: beginner Contrasts Claude's exploratory temperament with ChatGPT's literal executor style and maps each to the task shapes it suits. Read when choosing which model to route a task to or pairing them within one workflow. - [Opus vs Sonnet vs Haiku](https://shadow.shiny.sh/concepts/claude/models/opus-vs-sonnet-vs-haiku/) — raw: https://shadow.shiny.sh/concepts/claude/models/opus-vs-sonnet-vs-haiku.md; slug: opus-vs-sonnet-vs-haiku; type: concepts; department: concepts; group: models; persona: OP BD; level: beginner Explains Anthropic's three model tiers — Opus, Sonnet, and Haiku — and how to route work by cost, latency, and capability. Read when picking a model for a task, a skill, or an operator's default session. - [The five-hour window](https://shadow.shiny.sh/concepts/claude/models/five-hour-window/) — raw: https://shadow.shiny.sh/concepts/claude/models/five-hour-window.md; slug: five-hour-window; type: concepts; department: concepts; group: models; persona: OP BD TL; level: beginner Explains Claude Code's rolling five-hour usage window, how it throttles heavy sessions, and the pacing, multi-account, and plan-upgrade workarounds. Read when planning heavy agent work or provisioning operators. ### openai-and-codex - [AGENTS.md](https://shadow.shiny.sh/concepts/openai-and-codex/agents-md/) — raw: https://shadow.shiny.sh/concepts/openai-and-codex/agents-md.md; slug: agents-md; type: concepts; department: concepts; group: openai-and-codex; persona: OP BD; level: beginner AGENTS.md is a project-root markdown file that serves as the standing instructions for OpenAI's Codex CLI (and other compatible agents). It plays the same role as CLAUDE.md does for Claude Code: project-wide context the agent reads at session start. - [Codex (the OpenAI CLI)](https://shadow.shiny.sh/concepts/openai-and-codex/codex/) — raw: https://shadow.shiny.sh/concepts/openai-and-codex/codex.md; slug: codex; type: concepts; department: concepts; group: openai-and-codex; persona: BD OP; level: beginner Codex is OpenAI's CLI tool for agentic coding work. It is the rough peer of Claude Code: a terminal-based interface that runs agentic loops against your codebase, uses skills, supports MCP servers, and ties into a Chat GPT or OpenAI API plan for billing. - [Codex built-in browser](https://shadow.shiny.sh/concepts/openai-and-codex/codex-browser/) — raw: https://shadow.shiny.sh/concepts/openai-and-codex/codex-browser.md; slug: codex-browser; type: concepts; department: concepts; group: openai-and-codex; persona: BD OP; level: intermediate A web browser embedded directly in the Codex CLI interface, added in late 2025 / early 2026. The operator can ask the agent to open a URL, see screenshots of pages, click around, and inspect content — all without an external browser-automation MCP server. - [The /goal command](https://shadow.shiny.sh/concepts/openai-and-codex/goal-command/) — raw: https://shadow.shiny.sh/concepts/openai-and-codex/goal-command.md; slug: goal-command; type: concepts; department: concepts; group: openai-and-codex; persona: BD OP; level: intermediate A Codex slash command that tells the agent to pursue an outcome rather than execute a specified set of steps. The agent will keep working — replanning, retrying, looping — until either the goal is met or it determines the goal is impossible. ### tooling - [AI code review (Code Rabbit, GitHub's reviewer, and others)](https://shadow.shiny.sh/concepts/tooling/code-rabbit-and-ai-code-review/) — raw: https://shadow.shiny.sh/concepts/tooling/code-rabbit-and-ai-code-review.md; slug: code-rabbit-and-ai-code-review; type: concepts; department: concepts; group: tooling; persona: BD TL; level: intermediate A category of tools that read a pull request, reason about the change, and produce structured review comments — issues, questions, suggestions — that a human reviewer can act on. The reviewer is an AI rather than (or in addition to) a human. - [CMX (cmux) — terminal multiplexer for AI sessions](https://shadow.shiny.sh/concepts/tooling/cmux/) — raw: https://shadow.shiny.sh/concepts/tooling/cmux.md; slug: cmux; type: concepts; department: concepts; group: tooling; persona: BD OP; level: intermediate A terminal multiplexer purpose-built for running multiple AI agent sessions side by side. Lets the operator open several Claude Code / Codex / other- harness sessions, each in its own tab, while keeping the underlying terminal usable for other shell work. - [Cursor and the Composer model](https://shadow.shiny.sh/concepts/tooling/cursor-and-composer/) — raw: https://shadow.shiny.sh/concepts/tooling/cursor-and-composer.md; slug: cursor-and-composer; type: concepts; department: concepts; group: tooling; persona: BD; level: beginner Cursor is an AI-native IDE — a VS-Code-derived editor with first-class AI integration. Distinct from Claude Code (terminal-first) and Codex (terminal- first) in that the editor is the primary surface; the chat lives alongside the code. - [Git worktrees](https://shadow.shiny.sh/concepts/tooling/worktrees/) — raw: https://shadow.shiny.sh/concepts/tooling/worktrees.md; slug: worktrees; type: concepts; department: concepts; group: tooling; persona: BD OP; level: intermediate A git worktree is a separate working directory linked to the same git repository. It lets you have the same repo checked out at multiple branches simultaneously, each in its own folder, all sharing the underlying git history. - [Markdown, YAML, JSON, TOML](https://shadow.shiny.sh/concepts/tooling/markdown-yaml-json-toml/) — raw: https://shadow.shiny.sh/concepts/tooling/markdown-yaml-json-toml.md; slug: markdown-yaml-json-toml; type: concepts; department: concepts; group: tooling; persona: OP BD; level: beginner Explains the four file formats agent tooling lives in — Markdown, YAML, JSON, TOML — what each is for, and how much an operator edits versus delegates. Read when a config or frontmatter file looks unfamiliar. - [Obsidian as a knowledge vault](https://shadow.shiny.sh/concepts/tooling/obsidian-as-knowledge-vault/) — raw: https://shadow.shiny.sh/concepts/tooling/obsidian-as-knowledge-vault.md; slug: obsidian-as-knowledge-vault; type: concepts; department: concepts; group: tooling; persona: KW OP; level: beginner Why an Obsidian vault — just a folder of markdown files — is the agent-friendly home for personal knowledge, and when to use it over OneNote or Notion. Read before setting up a knowledge layer an AI can query. - [Open Code (SST) and alternative terminal harnesses](https://shadow.shiny.sh/concepts/tooling/open-code-and-alternatives/) — raw: https://shadow.shiny.sh/concepts/tooling/open-code-and-alternatives.md; slug: open-code-and-alternatives; type: concepts; department: concepts; group: tooling; persona: BD; level: intermediate Surveys community terminal harnesses like Open Code and SuperSST and when their heavy customizability beats the vendor offerings. Read when Claude Code or Codex defaults don't fit a power-user workflow. - [Shell basics for operators](https://shadow.shiny.sh/concepts/tooling/shell-basics-for-operators/) — raw: https://shadow.shiny.sh/concepts/tooling/shell-basics-for-operators.md; slug: shell-basics-for-operators; type: concepts; department: concepts; group: tooling; persona: OP; level: beginner The operator does not need to become a shell expert. They need a few commands well enough to navigate, look at, and modify files without panicking. - [Trusted bot review state](https://shadow.shiny.sh/concepts/tooling/trusted-bot-review-state/) — raw: https://shadow.shiny.sh/concepts/tooling/trusted-bot-review-state.md; slug: trusted-bot-review-state; type: concepts; department: concepts; group: tooling; persona: BD TL; level: advanced Trust bot-authored review output only when author identity, payload shape, review baseline, and current head all match. ### vendor-landscape - [Gemini models](https://shadow.shiny.sh/concepts/vendor-landscape/gemini-models/) — raw: https://shadow.shiny.sh/concepts/vendor-landscape/gemini-models.md; slug: gemini-models; type: concepts; department: concepts; group: vendor-landscape; persona: OP BD; level: beginner Surveys Google's Gemini model family as of mid-2026, how it compares to Claude and GPT, and when to choose or skip it. Read when evaluating Gemini for agent work or routing tasks across model vendors. - [Google Anti-Gravity](https://shadow.shiny.sh/concepts/vendor-landscape/anti-gravity/) — raw: https://shadow.shiny.sh/concepts/vendor-landscape/anti-gravity.md; slug: anti-gravity; type: concepts; department: concepts; group: vendor-landscape; persona: BD OP; level: beginner Google's agentic-AI harness for the Gemini family of models. Released in late 2025 / early 2026 as a third major entrant alongside Claude Code (Anthropic) and Codex (OpenAI). - [Microsoft Copilot](https://shadow.shiny.sh/concepts/vendor-landscape/microsoft-copilot/) — raw: https://shadow.shiny.sh/concepts/vendor-landscape/microsoft-copilot.md; slug: microsoft-copilot; type: concepts; department: concepts; group: vendor-landscape; persona: OP TL EX; level: beginner Explains what Microsoft Copilot is, where in-app assistance fits versus agent CLIs, and how to use it as an adoption ramp. Read when a team asks whether Copilot is enough or it also needs Claude Code or Codex. - [Salesforce AgentForce](https://shadow.shiny.sh/concepts/vendor-landscape/agentforce/) — raw: https://shadow.shiny.sh/concepts/vendor-landscape/agentforce.md; slug: agentforce; type: concepts; department: concepts; group: vendor-landscape; persona: TL EX BD; level: intermediate AgentForce is Salesforce's first-party agentic AI product. It runs agents inside the Salesforce environment, with access to Salesforce data, integrated with Salesforce's existing automation primitives (flows, Apex, validation rules). ## patterns ### operations-and-debugging - [Bounded AI-debug content](https://shadow.shiny.sh/patterns/bounded-ai-debug-content/) — raw: https://shadow.shiny.sh/patterns/bounded-ai-debug-content.md; slug: bounded-ai-debug-content; type: patterns; department: patterns; group: operations-and-debugging; persona: BD TL; level: advanced Use when exposing AI prompts, responses, tool calls, model metadata, traces, screenshots, DOM snapshots, or execution artifacts for debugging. Keep rich content bounded, short-retention, and separated from durable telemetry. - [Operator-surface-first debugging](https://shadow.shiny.sh/patterns/operator-surface-first-debugging/) — raw: https://shadow.shiny.sh/patterns/operator-surface-first-debugging.md; slug: operator-surface-first-debugging; type: patterns; department: patterns; group: operations-and-debugging; persona: OP BD TL; level: intermediate; version: 0.2 Debug through the supported operator UI, API, dashboard, or helper script before raw logs, direct database reads, ad hoc provider calls, or break-glass writes, then drill to durable evidence and classify the result before fixing. - [Realtime transport decisions](https://shadow.shiny.sh/patterns/realtime-transport-decisions/) — raw: https://shadow.shiny.sh/patterns/realtime-transport-decisions.md; slug: realtime-transport-decisions; type: patterns; department: patterns; group: operations-and-debugging; persona: BD TL; level: advanced Use when choosing between websocket, polling, bounded waits, heartbeats, or push-fed shared state for live runtime surfaces. - [Shared-environment readiness](https://shadow.shiny.sh/patterns/shared-environment-readiness/) — raw: https://shadow.shiny.sh/patterns/shared-environment-readiness.md; slug: shared-environment-readiness; type: patterns; department: patterns; group: operations-and-debugging; persona: OP BD TL; level: advanced; version: 0.2 Prove a shared operator environment is ready by exercising accounts, access, seeded data, provider credentials, budgets, and runtime wiring through the normal app and API paths instead of faking customer state. ### orchestration-and-sessions - [Autoresearch loop](https://shadow.shiny.sh/patterns/autoresearch-loop/) — raw: https://shadow.shiny.sh/patterns/autoresearch-loop.md; slug: autoresearch-loop; type: patterns; department: patterns; group: orchestration-and-sessions; persona: BD TL; level: advanced; version: 0.2 Run benchmark-driven improvement as a controlled experiment: freeze the evaluator, change one narrow surface, measure against a baseline, and keep or revert every attempt. - [Ready-frontier dispatch](https://shadow.shiny.sh/patterns/ready-frontier-dispatch/) — raw: https://shadow.shiny.sh/patterns/ready-frontier-dispatch.md; slug: ready-frontier-dispatch; type: patterns; department: patterns; group: orchestration-and-sessions; persona: BD TL; level: advanced Dispatch only the packet frontier whose dependencies, ownership boundaries, validation needs, shared-state risks, and commit boundaries are ready. - [Resume preflight](https://shadow.shiny.sh/patterns/resume-preflight/) — raw: https://shadow.shiny.sh/patterns/resume-preflight.md; slug: resume-preflight; type: patterns; department: patterns; group: orchestration-and-sessions; persona: BD TL; level: intermediate Before mutating after an interruption, reload governing instructions, verify branch and state, reconcile child results, and choose the next ready packet. - [Side chat — fork without forking](https://shadow.shiny.sh/patterns/side-chat-fork-conversation/) — raw: https://shadow.shiny.sh/patterns/side-chat-fork-conversation.md; slug: side-chat-fork-conversation; type: patterns; department: patterns; group: orchestration-and-sessions; persona: OP BD; level: intermediate How to use a side chat (/btw) to answer tangent questions without polluting a long session's context. Read this when side questions keep derailing a carefully shaped main conversation. - [Two sessions, parallel work](https://shadow.shiny.sh/patterns/two-sessions-parallel-work/) — raw: https://shadow.shiny.sh/patterns/two-sessions-parallel-work.md; slug: two-sessions-parallel-work; type: patterns; department: patterns; group: orchestration-and-sessions; persona: OP BD; level: intermediate Run two independent Claude Code or Codex sessions side by side, each with a narrow scope, coordinating only at boundaries. Read this when you have genuinely independent threads of work and want clean contexts. ### planning-and-prompting - [Fact-finder then planner](https://shadow.shiny.sh/patterns/fact-finder-then-planner/) — raw: https://shadow.shiny.sh/patterns/fact-finder-then-planner.md; slug: fact-finder-then-planner; type: patterns; department: patterns; group: planning-and-prompting; persona: BD TL; level: intermediate Separate factual inventory from synthesis so exploration returns evidence and planners turn integrated facts into packet boundaries and decisions. - [Loop the plan](https://shadow.shiny.sh/patterns/loop-the-plan/) — raw: https://shadow.shiny.sh/patterns/loop-the-plan.md; slug: loop-the-plan; type: patterns; department: patterns; group: planning-and-prompting; persona: OP BD; level: intermediate A multi-step plan was executed by the agent. The result is mostly what you wanted, but the agent missed something, took a wrong turn, or left edges rough. Instead of debugging the specific miss, you ask the agent to execute the same plan again. - [Plan-write-reset-execute](https://shadow.shiny.sh/patterns/plan-write-reset-execute/) — raw: https://shadow.shiny.sh/patterns/plan-write-reset-execute.md; slug: plan-write-reset-execute; type: patterns; department: patterns; group: planning-and-prompting; persona: OP BD; level: intermediate Plan a multi-step task, save the plan to a file, reset the session, then execute from a clean context. Read this before any agent task with more than a few steps or one that could outgrow the context window. - [Target-driven goal prompt](https://shadow.shiny.sh/patterns/target-driven-goal-prompt/) — raw: https://shadow.shiny.sh/patterns/target-driven-goal-prompt.md; slug: target-driven-goal-prompt; type: patterns; department: patterns; group: planning-and-prompting; persona: OP BD TL; level: intermediate Produce a compact goal prompt that lets a fresh parent agent drive toward a measurable target state while using subagents dynamically for discovery, implementation, validation, and review. - [Tracker-plan alignment](https://shadow.shiny.sh/patterns/tracker-plan-alignment/) — raw: https://shadow.shiny.sh/patterns/tracker-plan-alignment.md; slug: tracker-plan-alignment; type: patterns; department: patterns; group: planning-and-prompting; persona: BD TL; level: intermediate Keep a tracker as execution state for a plan without changing the plan's deliverables, gates, or phase boundaries. ### validation-and-evidence - [AI review checkpointing](https://shadow.shiny.sh/patterns/ai-review-checkpointing/) — raw: https://shadow.shiny.sh/patterns/ai-review-checkpointing.md; slug: ai-review-checkpointing; type: patterns; department: patterns; group: validation-and-evidence; persona: BD TL; level: advanced Use a draft PR/MR or equivalent review artifact as a branch-health checkpoint while implementation continues, without confusing checkpoint review with the final landing gate. - [Observability contracts](https://shadow.shiny.sh/patterns/observability-contracts/) — raw: https://shadow.shiny.sh/patterns/observability-contracts.md; slug: observability-contracts; type: patterns; department: patterns; group: validation-and-evidence; persona: BD TL; level: advanced; version: 0.3 Treat telemetry as a set of written contracts: every surface belongs to one plane, fields are allowlisted, retention is declared, and sensitive data stays out of the wrong surface. - [Platform validation](https://shadow.shiny.sh/patterns/platform-validation/) — raw: https://shadow.shiny.sh/patterns/platform-validation.md; slug: platform-validation; type: patterns; department: patterns; group: validation-and-evidence; persona: BD TL; level: advanced; version: 0.3 Run structured validation passes that leave durable evidence, end in an explicit terminal result, and turn discoveries into candidate issues instead of silent fixes. - [Runtime evidence required](https://shadow.shiny.sh/patterns/runtime-evidence-required/) — raw: https://shadow.shiny.sh/patterns/runtime-evidence-required.md; slug: runtime-evidence-required; type: patterns; department: patterns; group: validation-and-evidence; persona: BD TL OP; level: intermediate Require runtime proof when tests alone cannot show that a UI, route, background job, integration, agent flow, or deploy path works. - [Validator-owned validation](https://shadow.shiny.sh/patterns/validator-owned-validation/) — raw: https://shadow.shiny.sh/patterns/validator-owned-validation.md; slug: validator-owned-validation; type: patterns; department: patterns; group: validation-and-evidence; persona: BD TL; level: intermediate Keep validation independent by assigning validators evidence-producing checks while workers own product changes and only cheap local sanity checks. ### working-with-humans - [Hide buttons the AI shouldn't click](https://shadow.shiny.sh/patterns/hide-buttons-the-ai-shouldnt-click/) — raw: https://shadow.shiny.sh/patterns/hide-buttons-the-ai-shouldnt-click.md; slug: hide-buttons-the-ai-shouldnt-click; type: patterns; department: patterns; group: working-with-humans; persona: OP BD; level: intermediate Pattern for removing dangerous affordances from the agent's visible interface so it cannot click them, layered with permission scoping and tool constraints. Read before letting an agent drive a UI with destructive actions. - [Output questions with a recommended option](https://shadow.shiny.sh/patterns/output-questions-with-recommended-option/) — raw: https://shadow.shiny.sh/patterns/output-questions-with-recommended-option.md; slug: output-questions-with-recommended-option; type: patterns; department: patterns; group: working-with-humans; persona: OP BD; level: beginner Pattern for cutting decision fatigue by having the agent mark a recommended choice whenever it outputs options or questions, so the operator scans one line instead of reading everything. Read when planning sessions drag. - [Share skills via a portable folder](https://shadow.shiny.sh/patterns/share-skills-via-portable-folder/) — raw: https://shadow.shiny.sh/patterns/share-skills-via-portable-folder.md; slug: share-skills-via-portable-folder; type: patterns; department: patterns; group: working-with-humans; persona: OP BD TL; level: intermediate You have a working skill set that took weeks to build. You want a teammate to use it. Or you want to set up the same workspace on a second machine without re-doing everything from scratch. - [Ship now, V2 later](https://shadow.shiny.sh/patterns/ship-now-v2-later/) — raw: https://shadow.shiny.sh/patterns/ship-now-v2-later.md; slug: ship-now-v2-later; type: patterns; department: patterns; group: working-with-humans; persona: TL OP BD; level: intermediate A team is debating whether to fix a problem properly (slow, painful, correct) or stopgap it (fast, dirty, leaves debt). The fast version would unblock real work this week; the proper version would land in a month and the team is bleeding now. - [The exception report pattern](https://shadow.shiny.sh/patterns/exception-report-pattern/) — raw: https://shadow.shiny.sh/patterns/exception-report-pattern.md; slug: exception-report-pattern; type: patterns; department: patterns; group: working-with-humans; persona: OP BD TL; level: intermediate A workflow has dirty data, partial failures, or unhandled cases that produce silent breakage. The team needs to see what's broken without stopping the workflow. ## personas ### personas - [The builder](https://shadow.shiny.sh/personas/builder/) — raw: https://shadow.shiny.sh/personas/builder.md; slug: builder; type: personas; department: personas; group: personas; persona: BD; level: intermediate; version: 0.2 An engineer or technical operator adopting agentic AI tools. Has used a terminal for a decade, knows git, has shipped production code. New to Claude Code, sub-agents, MCP, skills, the whole agentic stack. - [The executive](https://shadow.shiny.sh/personas/executive/) — raw: https://shadow.shiny.sh/personas/executive.md; slug: executive; type: personas; department: personas; group: personas; persona: EX; level: beginner; version: 0.2 A C-level or board-facing leader who sets AI strategy. Doesn't operate the tools. Sometimes asks "are we doing AI?" in every leadership meeting for 45 minutes at a stretch. Owns the build-vs-buy decision and the budget for AI- related contracts. - [The knowledge worker](https://shadow.shiny.sh/personas/knowledge-worker/) — raw: https://shadow.shiny.sh/personas/knowledge-worker.md; slug: knowledge-worker; type: personas; department: personas; group: personas; persona: KW; level: beginner; version: 0.2 Persona profile for the non-software professional using AI on their own data — what they bring, what they lack, and what they need. Read this before writing atoms aimed at personal-scale, no-terminal workflows. - [The operator](https://shadow.shiny.sh/personas/operator/) — raw: https://shadow.shiny.sh/personas/operator.md; slug: operator; type: personas; department: personas; group: personas; persona: OP; level: beginner; version: 0.2 Persona profile for the non-engineer who runs real business workflows — domain-deep, terminal-new. Read this before writing atoms for this audience to get the voice, scaffolding, and anti-patterns right. - [The team lead](https://shadow.shiny.sh/personas/team-lead/) — raw: https://shadow.shiny.sh/personas/team-lead.md; slug: team-lead; type: personas; department: personas; group: personas; persona: TL; level: intermediate; version: 0.2 A manager of operators or builders. Owns a workflow that involves multiple people. Has the political and budget authority to decide what gets automated and how risk is handled — but doesn't operate the tools day to day. ## software-development ### foundations - [Coding style guardrails](https://shadow.shiny.sh/agent-skills/software-development/foundations/coding-style-guardrails/) — raw: https://shadow.shiny.sh/agent-skills/software-development/foundations/coding-style-guardrails.md; slug: coding-style-guardrails; type: agent-skills; department: software-development; group: foundations; persona: BD TL; level: intermediate; version: 0.3 Use when editing code — anti-patterns and discipline rules specifically tuned for AI-assisted coding. Type-safety ladder, anti-over-engineering rules, forward-only cleanup, and "preserve the contract" heuristics. - [Context7 documentation lookup](https://shadow.shiny.sh/agent-skills/software-development/foundations/context7-documentation-lookup/) — raw: https://shadow.shiny.sh/agent-skills/software-development/foundations/context7-documentation-lookup.md; slug: context7-documentation-lookup; type: agent-skills; department: software-development; group: foundations; persona: BD; level: intermediate; version: 0.2 Use when working with a current version of a library, framework, or API where training-data assumptions might be stale. Reach for Context7 for live documentation; fall back to direct doc URLs. - [Coverage accountability](https://shadow.shiny.sh/agent-skills/software-development/foundations/coverage-accountability/) — raw: https://shadow.shiny.sh/agent-skills/software-development/foundations/coverage-accountability.md; slug: coverage-accountability; type: agent-skills; department: software-development; group: foundations; persona: BD TL; level: intermediate; version: 0.3 Use when code changed and you are about to declare work done — produce a coverage map of modified files → specific tests that exercise them. No shipping uncovered new logic. - [Documentation impact](https://shadow.shiny.sh/agent-skills/software-development/foundations/doc-impact/) — raw: https://shadow.shiny.sh/agent-skills/software-development/foundations/doc-impact.md; slug: doc-impact; type: agent-skills; department: software-development; group: foundations; persona: BD TL; level: intermediate; version: 0.3 Use when code or behavior changed — decide whether docs need to update, scan for stale content, and fix drift in-area before declaring work done. - [Lint as a gate](https://shadow.shiny.sh/agent-skills/software-development/foundations/lint-as-gate/) — raw: https://shadow.shiny.sh/agent-skills/software-development/foundations/lint-as-gate.md; slug: lint-as-gate; type: agent-skills; department: software-development; group: foundations; persona: BD TL; level: intermediate; version: 0.3 Use when code changed and you are about to run tests, build, push, or open a PR — lint runs first and blocks everything downstream until clean. ### infra-ops - [Database migration safety](https://shadow.shiny.sh/agent-skills/software-development/infra-ops/database-migration-safety/) — raw: https://shadow.shiny.sh/agent-skills/software-development/infra-ops/database-migration-safety.md; slug: database-migration-safety; type: agent-skills; department: software-development; group: infra-ops; persona: BD TL; level: advanced; version: 0.2 Use when changing schema, writing or running migrations, resetting fixture state, inspecting records, or touching database-backed shared resources. - [Dependency management](https://shadow.shiny.sh/agent-skills/software-development/infra-ops/dependency-management/) — raw: https://shadow.shiny.sh/agent-skills/software-development/infra-ops/dependency-management.md; slug: dependency-management; type: agent-skills; department: software-development; group: infra-ops; persona: BD TL; level: intermediate; version: 0.2 Use when adding, removing, or changing dependencies, lockfiles, package manager configuration, install workflows, or dependency caches. - [Deploy environment contract](https://shadow.shiny.sh/agent-skills/software-development/infra-ops/deploy-env-contract/) — raw: https://shadow.shiny.sh/agent-skills/software-development/infra-ops/deploy-env-contract.md; slug: deploy-env-contract; type: agent-skills; department: software-development; group: infra-ops; persona: BD TL; level: advanced; version: 0.3 Use when editing env templates, deploy scripts, CI/CD config, or anything in the deploy pipeline. Defines the set of files that move together as one contract, the co-edit rule, the validation command bundle, and the wait-for- terminal-status discipline. - [Dev stack wrapper](https://shadow.shiny.sh/agent-skills/software-development/infra-ops/dev-stack-wrapper/) — raw: https://shadow.shiny.sh/agent-skills/software-development/infra-ops/dev-stack-wrapper.md; slug: dev-stack-wrapper; type: agent-skills; department: software-development; group: infra-ops; persona: BD TL; level: intermediate; version: 0.3 Use when bringing the local dev stack up or down, running a service command (test, migration, shell), tailing logs, or diagnosing a dead dev service. - [Host mutation safety](https://shadow.shiny.sh/agent-skills/software-development/infra-ops/host-mutation-safety/) — raw: https://shadow.shiny.sh/agent-skills/software-development/infra-ops/host-mutation-safety.md; slug: host-mutation-safety; type: agent-skills; department: software-development; group: infra-ops; persona: BD TL; level: advanced; version: 0.3 Use when mutating cloud hosts, snapshots, networking, or VM state. - [Network access contract](https://shadow.shiny.sh/agent-skills/software-development/infra-ops/network-access-contract/) — raw: https://shadow.shiny.sh/agent-skills/software-development/infra-ops/network-access-contract.md; slug: network-access-contract; type: agent-skills; department: software-development; group: infra-ops; persona: BD TL; level: advanced; version: 0.2 Use when changing public ingress, private operator routes, DNS, tunnels, proxies, access policies, or network exposure. - [Secrets and config](https://shadow.shiny.sh/agent-skills/software-development/infra-ops/secrets-and-config/) — raw: https://shadow.shiny.sh/agent-skills/software-development/infra-ops/secrets-and-config.md; slug: secrets-and-config; type: agent-skills; department: software-development; group: infra-ops; persona: OP BD TL; level: intermediate; version: 0.3 Use when touching environment variables, secrets, credentials, .env files, or configuration that varies between environments. Defines env-file conventions, secret-handling rules, redaction baseline, and credential rotation procedures. - [Shared resource safety](https://shadow.shiny.sh/agent-skills/software-development/infra-ops/shared-resource-safety/) — raw: https://shadow.shiny.sh/agent-skills/software-development/infra-ops/shared-resource-safety.md; slug: shared-resource-safety; type: agent-skills; department: software-development; group: infra-ops; persona: OP BD TL; level: intermediate; version: 0.3 Use when an agent is about to read or write a shared resource (database, queue, third-party SaaS, device fleet, message bus). Direct writes are last resort; supported app/API paths are the default. - [Structured logging](https://shadow.shiny.sh/agent-skills/software-development/infra-ops/structured-logging/) — raw: https://shadow.shiny.sh/agent-skills/software-development/infra-ops/structured-logging.md; slug: structured-logging; type: agent-skills; department: software-development; group: infra-ops; persona: BD TL; level: intermediate; version: 0.3 Use when adding or modifying code that triggers side effects, makes external calls, or changes runtime state. Defines what to log, what fields to attach, and what never to log. ### workflow - [Git workflow](https://shadow.shiny.sh/agent-skills/software-development/workflow/git-workflow/) — raw: https://shadow.shiny.sh/agent-skills/software-development/workflow/git-workflow.md; slug: git-workflow; type: agent-skills; department: software-development; group: workflow; persona: BD TL; level: intermediate; version: 0.3 Use when branching, committing, or changing local git history — trunk discipline, branch naming, commit guardrails, and destructive-command approval. - [Issue tracker workflow](https://shadow.shiny.sh/agent-skills/software-development/workflow/issue-tracker-workflow/) — raw: https://shadow.shiny.sh/agent-skills/software-development/workflow/issue-tracker-workflow.md; slug: issue-tracker-workflow; type: agent-skills; department: software-development; group: workflow; persona: BD TL; level: intermediate; version: 0.3 Use when creating, updating, or interpreting issues in your tracker (Linear, Jira, GitHub Issues, etc.). Treats the issue as a live state machine + handoff record between human and agent. - [Plan to issues](https://shadow.shiny.sh/agent-skills/software-development/workflow/plan-to-issues/) — raw: https://shadow.shiny.sh/agent-skills/software-development/workflow/plan-to-issues.md; slug: plan-to-issues; type: agent-skills; department: software-development; group: workflow; persona: BD TL; level: intermediate; version: 0.3 Use when mirroring an approved plan into tracker parent + child issues without changing the plan's meaning. - [Planning](https://shadow.shiny.sh/agent-skills/software-development/workflow/planning/) — raw: https://shadow.shiny.sh/agent-skills/software-development/workflow/planning.md; slug: planning; type: agent-skills; department: software-development; group: workflow; persona: OP BD TL; level: intermediate; version: 0.3 Use when the user wants a plan written, reviewed, or guided to approval before any execution begins. - [PR flow](https://shadow.shiny.sh/agent-skills/software-development/workflow/pr-flow/) — raw: https://shadow.shiny.sh/agent-skills/software-development/workflow/pr-flow.md; slug: pr-flow; type: agent-skills; department: software-development; group: workflow; persona: BD TL; level: intermediate; version: 0.1 Use when pushing a branch, opening or updating a PR/MR, handing work to reviewers, working an AI reviewer's findings, or merging after approval. - [Work lifecycle](https://shadow.shiny.sh/agent-skills/software-development/workflow/work-lifecycle/) — raw: https://shadow.shiny.sh/agent-skills/software-development/workflow/work-lifecycle.md; slug: work-lifecycle; type: agent-skills; department: software-development; group: workflow; persona: BD TL; level: intermediate; version: 0.3 Use when starting, resuming, checkpointing, or wrapping up a tracked unit of work. - [Worktree policy](https://shadow.shiny.sh/agent-skills/software-development/workflow/worktree-policy/) — raw: https://shadow.shiny.sh/agent-skills/software-development/workflow/worktree-policy.md; slug: worktree-policy; type: agent-skills; department: software-development; group: workflow; persona: BD TL; level: intermediate; version: 0.3 Use when working on multiple features in parallel, when you need lane discipline so worktrees don't collide, or before creating/destroying a worktree. ## universal ### agent-meta - [Agent memory pattern](https://shadow.shiny.sh/agent-skills/universal/agent-meta/agent-memory-pattern/) — raw: https://shadow.shiny.sh/agent-skills/universal/agent-meta/agent-memory-pattern.md; slug: agent-memory-pattern; type: agent-skills; department: universal; group: agent-meta; persona: BD TL; level: intermediate; version: 0.2 Use when setting up or maintaining persistent agent memory directories — the per-role files an agent reads at session start and updates as it learns. Covers what to save, what NOT to save, and how to keep memory accurate over time. - [Shadow](https://shadow.shiny.sh/agent-skills/universal/agent-meta/shadow/) — raw: https://shadow.shiny.sh/agent-skills/universal/agent-meta/shadow.md; slug: shadow; type: agent-skills; department: universal; group: agent-meta; persona: OP BD TL EX KW; level: beginner; version: 0.4 Use when answering questions about AI operator patterns, agent skills, Claude Code, Codex, MCP, or any Shadow library topic — or when the user wants to discover, install, update, or adapt a Shadow skill ("install Shadow's git skill", "does Shadow have a skill for X?", "update my Shadow skills"). Fetches live Shadow content, cites source URLs, and installs skills tailored to the current project. - [Skill authoring](https://shadow.shiny.sh/agent-skills/universal/agent-meta/skill-authoring/) — raw: https://shadow.shiny.sh/agent-skills/universal/agent-meta/skill-authoring.md; slug: skill-authoring; type: agent-skills; department: universal; group: agent-meta; persona: BD TL; level: intermediate; version: 0.3 Use when creating, splitting, renaming, or registering a new skill. Forces deliberate skill growth — one per durable workflow, registered in canonical places, reviewed for contradictions. ### collaboration - [Collaboration protocol](https://shadow.shiny.sh/agent-skills/universal/collaboration/collaboration-protocol/) — raw: https://shadow.shiny.sh/agent-skills/universal/collaboration/collaboration-protocol.md; slug: collaboration-protocol; type: agent-skills; department: universal; group: collaboration; persona: OP BD TL; level: beginner; version: 0.2 Use when setting how the agent communicates — response format, structured question format, planning-mode behavior, and "go means go" execution discipline. - [Delegation model](https://shadow.shiny.sh/agent-skills/universal/collaboration/delegation-model/) — raw: https://shadow.shiny.sh/agent-skills/universal/collaboration/delegation-model.md; slug: delegation-model; type: agent-skills; department: universal; group: collaboration; persona: BD TL; level: intermediate; version: 0.3 Use when deciding whether non-trivial work should run in the main session, dispatch to a subagent, or wait for a separate verification pass. Keeps the parent session as the control plane and children on bounded scopes. - [Force-load gate](https://shadow.shiny.sh/agent-skills/universal/collaboration/force-load-gate/) — raw: https://shadow.shiny.sh/agent-skills/universal/collaboration/force-load-gate.md; slug: force-load-gate; type: agent-skills; department: universal; group: collaboration; persona: BD TL; level: intermediate; version: 0.3 Use when starting a session, or after any resume, /clear, or context compaction — (re)load the project's canonical instruction and state files before non-trivial work, and prove it with a gate line. - [Packet contract](https://shadow.shiny.sh/agent-skills/universal/collaboration/packet-contract/) — raw: https://shadow.shiny.sh/agent-skills/universal/collaboration/packet-contract.md; slug: packet-contract; type: agent-skills; department: universal; group: collaboration; persona: BD TL; level: intermediate; version: 0.3 Use when delegating bounded work to a sub-agent or handing work to a fresh session. Forces an 8-heading task packet that is linted before dispatch and checked against its own done-means line on return — no "agent infers scope from prose." - [SME review handoff](https://shadow.shiny.sh/agent-skills/universal/collaboration/sme-review-handoff/) — raw: https://shadow.shiny.sh/agent-skills/universal/collaboration/sme-review-handoff.md; slug: sme-review-handoff; type: agent-skills; department: universal; group: collaboration; persona: OP BD TL; level: intermediate; version: 0.2 Use when turning messy operational data, exception lists, reconciliation outputs, dirty-data findings, or matching uncertainty into SME review spreadsheets or handoff documents. ## workflows ### workflows - [Browser smoke evidence](https://shadow.shiny.sh/workflows/browser-smoke-evidence/) — raw: https://shadow.shiny.sh/workflows/browser-smoke-evidence.md; slug: browser-smoke-evidence; type: workflows; department: workflows; group: workflows; persona: BD TL; level: intermediate Capture browser-level smoke evidence for UI or route changes using the project's supported browser automation or manual verification surface. - [Build a skill from scratch](https://shadow.shiny.sh/workflows/build-a-skill-from-scratch/) — raw: https://shadow.shiny.sh/workflows/build-a-skill-from-scratch.md; slug: build-a-skill-from-scratch; type: workflows; department: workflows; group: workflows; persona: OP BD; level: intermediate Step-by-step workflow for turning a repeated explanation into a tested agent skill — draft with the agent, edit aggressively, test on a fresh session, iterate. Read this when you keep re-explaining the same thing. - [Debug a failing integration with Claude](https://shadow.shiny.sh/workflows/debug-a-failing-integration/) — raw: https://shadow.shiny.sh/workflows/debug-a-failing-integration.md; slug: debug-a-failing-integration; type: workflows; department: workflows; group: workflows; persona: OP BD; level: intermediate An integration between two enterprise systems is failing in ways that are hard to diagnose: poor error messages, intermittent failures, no exception handling. The operator needs to understand what's broken before deciding how to fix it. - [Migrate from OneNote (or similar) to an Obsidian vault](https://shadow.shiny.sh/workflows/migrate-from-onenote-to-obsidian/) — raw: https://shadow.shiny.sh/workflows/migrate-from-onenote-to-obsidian.md; slug: migrate-from-onenote-to-obsidian; type: workflows; department: workflows; group: workflows; persona: KW OP; level: intermediate How to move years of notes from OneNote (or Evernote, Notion, Apple Notes) into a local markdown vault an agent can query. Read this when a proprietary notes app is blocking an AI workflow over your own data. - [Onboard a non-engineer to Claude Code](https://shadow.shiny.sh/workflows/onboard-a-non-engineer-to-claude-code/) — raw: https://shadow.shiny.sh/workflows/onboard-a-non-engineer-to-claude-code.md; slug: onboard-a-non-engineer-to-claude-code; type: workflows; department: workflows; group: workflows; persona: TL BD; level: intermediate The team has an operator — domain expert, fluent in their work, but new to terminal-shaped tools. They need to get to "doing real work with Claude Code" without spending months learning Linux, git, and AI theory first. - [Recover a firewall (or other live device) with Claude](https://shadow.shiny.sh/workflows/recover-a-firewall-with-claude/) — raw: https://shadow.shiny.sh/workflows/recover-a-firewall-with-claude.md; slug: recover-a-firewall-with-claude; type: workflows; department: workflows; group: workflows; persona: OP BD; level: advanced Diagnose and recover a live network device with Claude Code — backup first, two parallel sessions, one verified command at a time. Read this before AI-assisted recovery on production hardware with no sandbox. - [Set up a new Claude Code project](https://shadow.shiny.sh/workflows/set-up-new-claude-project/) — raw: https://shadow.shiny.sh/workflows/set-up-new-claude-project.md; slug: set-up-new-claude-project; type: workflows; department: workflows; group: workflows; persona: OP BD; level: beginner Ad-hoc chats lose context and produce a mess of files in random places. A project folder is the unit of repeatable, durable AI work — it survives session resets, holds the agent's instructions, contains skills, and can be moved between machines.