craftwork

Build automation scripts and pipelines that use coding-agent CLIs (Claude Code, Codex, Gemini CLI, GitHub Copilot CLI) in headless/non-interactive mode as the AI engine, or delegate work to cloud agents (`gh agent-task`) that open pull requests asynchronously. Use this skill whenever the user wants to write a shell script, CI job, cron task, batch processor, webhook handler, or any automation that shells out to `claude`, `codex`, `gemini`, `copilot`, or `gh agent-task` — single-turn prompts, multi-turn agentic loops, parallel fan-out across files/folders, structured JSON outputs consumed by downstream tools, or cloud-delegated tasks that produce PRs. Trigger on phrases like "script that uses Claude", "automate with Claude Code", "headless Claude", "batch process files with an LLM", "pipeline with codex exec", "gemini -p", "copilot --autopilot", "gh agent-task create", "GitHub Action that calls Claude", "cron job to review PRs", "agent loop in bash", "dispatch an agent task to open a PR", "fleet-wide agent-tas

Apply causal inference whenever the user is interpreting metrics, debugging system behavior, reading A/B test results, or trying to understand whether an observed change was caused by an action or by something else. Triggers on phrases like "X caused Y", "since we deployed this, metrics changed", "the A/B test showed a lift", "why did this metric move?", "is this correlation or causation?", "we changed X and Y improved", "how do we know this worked?", "the data shows…", or any situation where conclusions are being drawn from observational data. Also trigger before any decision based on metric interpretation — confusing correlation with causation leads to interventions that don't work and misattribution of credit. Never assume causation without applying this skill.

Apply ethical reasoning whenever the user faces a decision, design, or action with moral implications — especially when someone could be harmed, rights could be violated, or values are in tension. Triggers on phrases like "is this the right thing to do?", "what are the ethical implications?", "who could this harm?", "should we build this?", "is this fair?", "what are our obligations?", "value trade-off", "responsible AI". Use proactively when reviewing any high-stakes decision, product design affecting vulnerable populations, or action where the beneficiaries and those bearing costs are different groups.

Apply execution-planning whenever the user has made a decision and needs to turn it into action — decomposing work, sequencing tasks, estimating timelines, and assigning ownership. Triggers on phrases like "how do we execute this?", "break this into tasks", "what's the project plan?", "create a roadmap", "what are the dependencies?", "who does what by when?", "how long will this take to build?". Use proactively after decision-synthesis or architecture-evaluation produces a committed decision that requires coordinated implementation.

Apply experimental-design whenever the user needs to test a hypothesis, validate an assumption, or determine whether something actually works. Triggers on phrases like "how do we test this?", "design an experiment", "what would prove this?", "set up an A/B test", "how do we validate this hypothesis?", "what's the right control?", "is this result significant?", "what sample size do we need?". Use proactively when decisions rest on untested assumptions — designing the test before collecting data prevents post-hoc rationalization.

Apply fairness auditing whenever the user describes a system, algorithm, policy, or process that allocates outcomes across groups and wants to know whether it is equitable. Triggers on phrases like "is this fair?", "disparate impact", "bias in the system", "does this discriminate?", "algorithmic fairness", "who's disadvantaged by this?", "equitable outcomes". Use proactively when reviewing any allocation mechanism, scoring system, or automated decision pipeline that affects people differently based on group membership.

Apply learning-strategy whenever the user needs to close a knowledge gap, ramp up on a new domain, or build a structured plan for acquiring understanding. Triggers on phrases like "how do I learn this?", "I'm new to this domain", "ramp up on", "knowledge gap", "what should I study?", "learning plan", "how do I get up to speed?", "teach me about", "onboarding plan". Use proactively when epistemic-mapping reveals gaps that block decisions — knowing what you don't know is only useful if you then learn it efficiently.

Apply process-design whenever the user needs to create, improve, or streamline a workflow or operational process. Triggers on phrases like "design a workflow", "improve this process", "streamline this", "too many handoffs", "the process is too slow", "automate or not?", "how should we structure this pipeline?". Use proactively when a user describes repeated operational friction, bottlenecks, or unclear ownership in how work moves through a system.

Apply limit thinking when the user wants to understand what happens when a variable or condition is pushed toward its extreme — zero, infinity, 100%, or any boundary. Triggers on 'what happens if we scale this?', 'where does this break?', 'what's the ceiling?', 'what does this converge to?', or when evaluating a system by exploring its trajectory rather than its current state. Also trigger when a decision is based on a snapshot but hasn't examined what it converges to at scale. Use before any scaling decision, rollout plan, or growth strategy.

Apply evidence-synthesis whenever the user has multiple sources of evidence and needs to reach a conclusion — especially when sources conflict, vary in quality, or come from different methodologies. Triggers on phrases like "what does the evidence say?", "synthesize these findings", "are these studies consistent?", "literature review", "conflicting data", "what can we conclude from all this?", "meta-analysis", "weigh the evidence". Use proactively after causal-inference or learning-strategy produce findings that need integration with other evidence before a decision.

Apply game-theoretic analysis whenever multiple agents, actors, teams, or systems interact strategically — where each party's best move depends on what the others do. Triggers on "what's their incentive?", "why would they cooperate?", "how do we align incentives?", "coordination problem", "trust problem", or any situation involving negotiation, competition, cooperation under self-interest, or multi-agent interaction. Also trigger when designing multi-agent AI systems, agent negotiation protocols, or when a design fails because agents optimize for own payoffs rather than the system goal.

Apply this skill first whenever the user presents a problem, question, or situation that requires structured thinking — before reaching for any specific reasoning framework. Triggers on any substantive request to evaluate, analyze, diagnose, decide, design, improve, understand, or learn from something. This is the entry point for the reasoning skill collection. If you are unsure which reasoning skill to use, always start here.

Apply retrospective and counterfactual reasoning whenever something has already happened and the user needs to understand why — or learn from it to improve future decisions. Triggers on phrases like "what went wrong?", "why did this fail?", "post-mortem", "incident review", "we just shipped and it didn't go well", "let's debrief", "what would we have done differently?", "should we have seen this coming?", "what did we miss?", "what would have happened if we'd done X instead?", or any after-the-fact analysis of a completed event. Also trigger to prevent survivorship bias in success analyses — "what made this succeed?" deserves as much causal scrutiny as failure. Look backwards with as much rigor as you look forward.

Apply second-order thinking whenever the user is making a decision, proposing a change, or evaluating an action — especially one that seems obviously good or obviously safe. Triggers on phrases like "let's just do X", "the obvious answer is", "we should change Y", "what happens if we do Z?", "should we implement this?", "will this work?", or any time a user proposes an intervention in a system involving people, incentives, markets, or complex processes. Also trigger when first-order analysis has already been done and the user needs to go deeper. Second-order thinking should be applied before any significant decision is made — don't wait to be asked.

Apply this skill whenever the user needs to create, plan, structure, or improve a presentation, talk, pitch, keynote, or slide deck. Triggers on phrases like 'make a presentation about', 'I have a talk on', 'help me structure my deck', 'create slides for', 'pitch deck for', 'I'm presenting at', 'conference talk', 'prepare a keynote', 'workshop slides', or any request that involves communicating ideas to an audience via slides and spoken delivery. Also trigger when the user has existing slides and wants to improve the narrative flow, when they need speaker notes, or when they want to rehearse timing. This skill does NOT produce .pptx files directly (use the pptx skill for file creation). This skill produces the presentation SCRIPT — the narrative blueprint that determines what each slide says, shows, and how long the presenter spends on it.

Apply whenever the user needs to write, draft, review, or improve technical documents — RFCs, design docs, ADRs, runbooks, postmortems, one-pagers, announcements, Slack threads, PR descriptions. Triggers on 'write a design doc', 'draft an RFC', 'help me write this up', 'write a runbook', 'review my doc', 'make this clearer', 'write a postmortem', or when technical information must be communicated to a specific audience. Also trigger when the user pastes a draft for feedback or needs to explain technical decisions to non-technical stakeholders.

Apply architecture evaluation whenever the user faces a system design decision — choosing between architectures, evaluating trade-offs, or documenting a technical direction. Triggers on phrases like "evaluate this architecture", "should we use microservices?", "what are the trade-offs?", "is this design scalable?", "architecture decision", "ADR", "system design review", "which database should we use?". Use proactively when the user is about to commit to a technical direction without explicit trade-off analysis.

Apply argument-craft whenever the user needs to communicate a recommendation, persuade stakeholders, or structure a case for a decision. Triggers on phrases like "help me make the case for", "structure this argument", "write an executive summary", "how do I present this?", "convince the team", "frame this for leadership", "what's the narrative?", "how do I pitch this?". Use proactively when the user has completed analysis via decision-synthesis or scenario-planning but hasn't yet structured the communication.

Apply difficult-conversations whenever the user needs to prepare for a conversation involving conflict, power dynamics, emotional stakes, or relationship risk. Triggers on phrases like "how do I bring this up?", "I need to give difficult feedback", "there's a conflict on the team", "how do I have this conversation?", "someone is underperforming", "I disagree with my manager", "how do I say no?", "this is going to be awkward". Use proactively when negotiation-strategy identifies emotional or identity stakes that pure interest-based negotiation cannot handle.

Apply facilitation-design whenever the user needs to plan a meeting, workshop, retrospective, or any group session aimed at a specific outcome. Triggers on phrases like "design a workshop", "how do I run this meeting?", "facilitate a retrospective", "structure a brainstorm", "we need alignment", "how do I get the group to decide?", "plan an offsite session". Use proactively when a user describes a group decision-making challenge, alignment gap, or collaborative work session that lacks structure.

Apply financial modeling whenever the user needs quantitative rigor for a business decision — evaluating an investment, pricing a product, comparing costs and benefits, or assessing profitability. Triggers on phrases like "what's the unit economics?", "build a financial model", "is this profitable?", "what's the ROI?", "pricing strategy", "cost-benefit analysis", "what's the NPV?", "should we invest in this?". Use proactively when a decision has financial implications that the user has not quantified.

Apply narrative-construction whenever the user needs to turn analysis, data, or ideas into a compelling story. Triggers on phrases like "tell the story of", "create a narrative", "make this compelling", "what's the story arc?", "thought leadership piece", "how do I frame this as a story?", "content strategy", "write a blog post about". Use proactively when the user has strong analytical output that needs to reach a non-expert audience.

Apply negotiation strategy whenever the user needs to prepare for, navigate, or debrief a negotiation — whether formal (contracts, salary, deals) or informal (resource allocation, scope disputes, partnership terms). Triggers on phrases like "how do I negotiate this?", "what's my BATNA?", "how do we reach agreement?", "they won't budge on", "what leverage do I have?", "finding common ground", "deal structure", "how do I handle this negotiation?". Use proactively when a user describes a situation with competing interests and an outcome that requires agreement between parties.

Apply stakeholder and power mapping whenever the user is navigating organizational decisions, driving change, launching a product, building alignment, or trying to understand why something keeps getting blocked. Triggers on phrases like "why won't people adopt this?", "who do I need to convince?", "this keeps getting blocked", "how do I get buy-in?", "who are the key players?", "there's political resistance", "how do I manage stakeholders?", "who has influence here?", "someone is sabotaging this", or any situation where human actors, organizational dynamics, or change management are involved. Also trigger when a technically sound plan is failing for non-technical reasons — the real constraint is often human, not systemic. Never skip this skill when organizational change or adoption is involved.

Entry point for context engineering work. Routes to the right skill based on what the user needs — creating instructions, debugging agent failures, building documentation, or measuring outcomes. Use this when the user's goal involves agent context but they haven't named a specific skill.

Use when designing what goes into an agent's context window — system prompts, tool definitions, retrieval results, or any context artifact assembled before the agent runs. Triggers on "what should I put in the system prompt?", "how do I structure my context?", "the agent loses track of...", "my context window is full", "how do I decide what to include?", "designing a new harness", "the agent ignores my instructions". Do NOT use for one-off prompts, runtime conversation management, or when the problem is model capability rather than context design.

Use when an agent is failing, producing wrong output, ignoring instructions, hallucinating, or behaving unexpectedly — and the cause isn't an obvious code bug. Triggers on "my agent keeps failing", "the agent ignores my instructions", "it hallucinates even though I told it not to", "I fixed one thing but something else broke", "the agent used to work but now it doesn't", "why is the agent doing X instead of Y?". Do NOT use for infrastructure errors (API 500s, timeouts), code bugs in the harness (use systematic-debugging), or when the agent has never worked (use context-cartography to design first).

Evaluate whether a context engineering harness actually improves agent outcomes. Use when the user wants to measure, benchmark, compare, or validate any context artifact — rules, instructions, guidelines, docs, retrieval pipelines, tool setups. Triggers on "does this context help?", "benchmark my context", "evaluate my prompt", "A/B test my context", "is this worth the tokens?", "eval my context", or when someone wants empirical evidence their context engineering produces better outcomes than baseline.

Identify implicit context missing from a codebase that would most improve agent performance. Use whenever someone asks to audit, assess, or improve context for a codebase; asks 'what context is my codebase missing?', 'why do agents keep making mistakes here?', 'what should I put in my CLAUDE.md?', 'audit my codebase context', 'context gaps', or any variation. Also trigger when setting up agent context infrastructure for the first time, or when agent-generated code keeps violating implicit conventions.

Guide humans through creating effective instruction rules for coding agents (Copilot, Claude Code, Cursor, Windsurf, Aider, AGENTS.md, CLAUDE.md, .cursorrules, copilot-instructions.md). Trigger when someone asks to create, improve, or write agent instructions, copilot rules, AI coding guidelines, context files, or anything shaping agent behavior. Also trigger on 'agent keeps making mistakes', 'make Copilot follow our conventions', 'write rules for repo', 'set up agent context'. Runs an interactive extraction process — reads codebase first, then guides the human through targeted questions to surface implicit knowledge (past failures, non-obvious conventions, architectural decisions) that code alone can't tell an agent. For analyzing gaps in existing context, use context-gap-analyzer. This skill *creates* the rules.

Use when iterating on agent harnesses, system prompts, context pipelines, or any context artifact that will run repeatedly. Triggers on "how do I test my harness?", "is my agent getting better or worse?", "I changed the prompt and something broke", "regression in agent behavior", "how do I know if this context change helped?", "my harness used to work", "I'm tweaking the prompt but can't tell if it's improving". Do NOT use for one-off prompts, feature code testing (that's TDD), or exploratory prototyping where "good" isn't defined yet.

Evaluate the quality of existing agent instruction rule sets — CLAUDE.md, AGENTS.md, .cursorrules, copilot-instructions.md, or any coding-agent context file. Use this skill whenever someone asks to audit, score, or improve their agent rules; wants to know if their instructions are effective; or describes rules that aren't changing agent behavior. Trigger on phrases like 'are my rules good?', 'why is the agent ignoring my instructions?', 'score my CLAUDE.md', 'audit my agent rules', 'are these instructions effective?', 'review my copilot-instructions.md', 'my rules aren't working', 'evaluate my context file', or any situation where a human has an existing instruction file and wants to know whether it will actually improve agent behavior. Also trigger when someone has just run agent-instruction-forge and wants to verify the output before committing.

Challenge AI-generated (or any) unit tests to find false positives — tests that pass against wrong behavior. Use this skill whenever the user asks to review, audit, validate, or challenge test quality, especially tests generated by AI to increase code coverage. Triggers on phrases like 'review these tests', 'are these tests actually correct?', 'challenge my tests', 'test quality audit', 'false positive tests', 'these tests were auto-generated', 'AI wrote these tests', 'coverage went up but I don't trust it', 'are these tests testing the right thing?', 'validate test correctness', or any situation where tests exist alongside source code and someone wants to know whether the tests are genuinely verifying correct behavior vs. merely mirroring implementation bugs. Also trigger when the user mentions increasing code coverage with AI, copilot-generated tests, or test generation tools — these are high-risk contexts for false positive tests.

Apply kaizen continuous improvement philosophy to any codebase — identifying waste, unevenness, and overburden at the code level and producing small, actionable improvement opportunities. Triggers on '/kaizen', 'kaizen this codebase', 'continuous improvement audit', 'find waste in this code', 'what small improvements can we make?', 'improve this codebase incrementally', 'code health check', 'codebase hygiene', 'tech debt sweep', or any request to find incremental improvement opportunities in code. Also trigger when the user says 'clean up', 'tidy up', 'make this codebase better', or expresses frustration about code quality without wanting a full rewrite. This is NOT a code review skill for PRs or diffs — kaizen operates on the codebase as a whole or a focus area, looking for systemic improvement opportunities. Use this skill even for small codebases — the philosophy scales down gracefully.

Apply kintsugi (金継ぎ) repair visibility philosophy to any codebase — finding invisible repairs and making them legible with 'gold' context. Triggers on '/kintsugi', 'kintsugi this codebase', 'repair visibility audit', 'are our fixes documented?', 'why was this changed?', 'undocumented fixes', 'invisible patches', 'git archaeology', 'missing context on past fixes', 'why does this workaround exist?', or any request to understand or document the history behind code changes. Also trigger when someone asks 'why is this code like this?', 'what incident caused this?', 'who knows why we do it this way?', or when tribal knowledge about past repairs is at risk of being lost. This skill audits the history layer of a codebase — not what the code does today, but whether past breaks and repairs are visible and legible to future developers.

Scan ALL available skills before any non-trivial request. Prevents skill blindness, tunnel vision, and wrong-skill selection. Entry point for all skill-assisted work.

Apply this skill whenever the user asks to review code, a PR, a diff, or a merge request — or when they paste code and ask for feedback on it. Also trigger when someone asks to 'prepare a review', 'check this PR', 'review my changes', 'what do you think of this code', 'is this PR ready to merge', 'help me review', or any situation where code quality assessment is involved. This skill does NOT try to replace the human reviewer. It amplifies human reviewers by assembling context, pre-scanning surface issues, generating design coherence questions, and routing knowledge-transfer opportunities. Use this skill even for small snippets — the 7-dimension framework scales down gracefully. If the user says 'code review' in any form, trigger this skill.

Apply debugging methodology whenever the user faces a software failure they cannot explain — a broken test, unexpected behavior, a regression, or an intermittent bug. Triggers on phrases like "why is this broken?", "how do I debug this?", "the test fails but I don't know why", "intermittent failure", "works on my machine", "this used to work", "regression". Use proactively when the user describes a symptom and jumps straight to a fix without isolating the root cause.

Apply whenever knowledge is at risk of being lost, needs to be captured, or a team needs to design how knowledge flows and persists. Triggers on 'document this decision', 'we should write this down', 'someone is leaving the team', 'why did we do it this way?', 'we keep re-debating this', 'set up our knowledge system', 'our docs are a mess', 'onboarding is painful', or any situation where implicit knowledge needs to become explicit and discoverable. Also trigger after incidents, migrations, vendor choices, or finished spikes — high-value capture moments.

Entry point for professional skills — architecture, communication, process design, ethics, and leadership. Routes to the right skill based on what the user needs. Use this when the user's goal involves a professional discipline but they haven't named a specific skill.