Skip to main content
skill CX Codex

delegation · phuryn — Claude Code skill for handing off work

delegation — a Claude Code skill for briefing subagents and assessing their reports. It applies before handing off a build, review, or research task.

MIT ★ 741 updated 2026-11-14

Install into Claude Code · Plugin marketplace All methods and platforms ↓
/plugin marketplace add phuryn/product-engineering
/plugin install agent-teams@product-engineering
Open on GitHub

What delegation does

delegation helps frame work for a subagent around the goal, binding constraints, and proof required at handoff. It covers when to delegate based on the size of the change, how to run work in parallel, and what a useful brief should contain. For longer briefs, it points to references/brief-template.md and asks the delegate to report completed checks, blockers, and choices made where the brief was silent.

The session agent keeps product decisions, review triage, and the judgement that a stage is done. It also runs final checks and inspects the delegate’s evidence. The skill covers build, research, and review handoffs without prescribing implementation details unless they are hard constraints.

What it helps with

  • write a brief with a clear goal and constraints
  • define the checks required before handoff
  • split research and build work across parallel delegates
  • assess a delegate’s report without outsourcing final verification

Example prompts for the agent

  • Prepare a brief for a subagent to build this feature, with the goal, constraints, and checks.
  • Delegate the research to two agents in parallel and outline how to combine their findings.
  • Review this subagent report and separate completed checks from the ones I need to run.

How to install delegation

1Plugin marketplace

/plugin marketplace add phuryn/product-engineering
/plugin install agent-teams@product-engineering

This installs the whole agent-teams plugin with all its skills

2Skills CLI (Vercel)

npx skills add phuryn/product-engineering --skill delegation -a claude-code

3Manually: put the files in place

~/.claude/skills/delegation/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/delegation/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about delegation

How do I install delegation in Claude Code?

Add the marketplace with /plugin marketplace add phuryn/product-engineering, then install the plugin with /plugin install agent-teams@product-engineering.

What does delegation do?

It helps prepare briefs for subagents, hand off build, research, or review work, and assess what comes back. Final verification and stage completion remain with the session agent.

Which decisions stay with the session agent?

The session agent decides what the product should do, accepts or rejects review findings, and verifies the final result. Operational changes and production credentials also remain with that agent.

Source text

SKILL.md · MIT
---
name: delegation
description: "Before spawning a subagent or dispatching a build, review or research, and before trusting its report: the brief, the delegate, parallel runs, the handoff."
---

# Delegation — a delegate is a partner

**A delegate knows only what you hand it, so brief the goal.** Say what you are trying to achieve and for whom. Name the constraints that bind, the traps a smart newcomer would walk into, and how the result will be proved.

**A brief with the goal in it comes back with judgement.** "Change X to Y" gets Y, even when Y is wrong. A delegate that knows the goal can answer "this step is redundant, here is why", and that answer often changes what ships. That is the return on a brief's length: not compliance, judgement.

**Manage a delegate the way a good owner manages you.** Give it the goal and context, then trust its judgement on the means instead of prescribing steps. Push back where you disagree; its view doesn't bind you.

**Apply the delegate's own skill for its mechanics.** Apply `codex-agents`, `grok-agents` or `claude-agents` for a headless CLI peer, builder or reviewer. Apply `independent-review` for the unsteered review loop, normally through Grok, or without it a fresh Codex or headless Claude Code session. This skill covers their shared discipline. For a requested Gemini partner, apply `gemini-agents`: the user agrees first, per run or by an informed standing preference; Gemini is never a default. Never drive `agy` from memory.

## What never delegates

- **Decide what the product should do yourself.** Keep the thesis, scope, taste and interpretation of the owner's wishes with you.
- **Accept or reject review findings yourself.** Treat the finding and its severity as claims (`independent-review` § Triage).
- **Keep operational changes and production credentials with the session agent.** Keep deploys, promotions, pushes, applied migrations, persistent servers, workers, provider settings, secrets and drills with you, including development. Ask the delegate to make each step one command and name those commands; you run them. Development suite runs, including their test server and fixtures, are builder work within the brief's boundary.
- **Perform final verification yourself.** Run the tests, typecheck, gate and smoke, inspecting their results to check the delegate's passing claim.
- **Judge whether a stage is done yourself.** A delegate's handoff supplies evidence for that judgement.

## When it is worth handing off: size, not time

**If the brief would be nearly as long as the diff, write the diff.** A delegate must rediscover the file, conventions and surrounding code before changing anything.

| Situation | Who |
|---|---|
| You know the file and the line, and the change is mechanical | **you, directly** — no brief, no round trip |
| It needs exploration, or you are unsure of the mechanism | a delegate |
| It needs real test coverage | a delegate, or one focused test you write yourself |
| A naive fix would walk into a trap | a delegate, **with the trap in the brief** — this is where a long brief earns out |

- **A build round that has made no writes on a small change is stopped.** Kill its leftover process and write the change in-session, keeping your responsibilities and the requirement for independent review.
- **Use the parallelism or don't pay for it.** Work while the background delegate runs. Waiting pays delegation's latency without gaining its throughput.
- **Keep work whose reasoning you need yourself.** Also keep synthesis that needs everything held in one head.

## The brief

Three things, and the first is the one most often skipped:

1. **Explain what you are trying to achieve and why.** Name the decision this handoff feeds. In the owner's terms, "we are choosing between A and B" lets a delegate suggest a third option or challenge the question. A delegate told "research A and B" cannot.
2. **State the constraints that bind, including the do-nots.** Explain traps that would make a plausible local fix wrong in the larger system. For example: "Keep this out of the argument builder; the same string feeds another spawn path."
3. **Define proof for this handoff, including checks you must run.** The builder runs its tests and fixes failures before handoff; name its development test access and serialize suites on shared data. The session agent applies new migrations to development before the builder runs dependent tests. Keep the handoff's done-when narrower than the stage's; final verification and stage judgement stay with you. If a tool or platform blocks a check, name the concrete limit and who runs it: "Write it; I run it." Report those checks as "written, not run", rather than inventing counts or marking the stage done.

**Ask it to exercise every existing page and function the stage touches, not only its own.** Ask for this explicitly in the brief, including code the delegate did not write.

- **Compress the evidence, not the context.** Three log lines beat twenty lines explaining how you reached your conclusion. Keep the goal, binding constraints and traps at full length. A terse brief can produce a locally correct change that fails in the larger system.
- **The brief is the delegate's entire reality.** Ask it to confirm or refute every consequential claim against primary sources. Treat absence claims such as "none of them shipped X" as extraordinary. Engagement numbers, link lists and filenames do not establish product reality. When a fact changes mid-build, append a dated "Added while you build" section to the brief file. Keep that file complete rather than relying on a side message.
- **A feature that guesses from real-world input starts from evidence.** Run unchanged code on a real corpus first, citing its numbers for each binding decision. After the build, pin a live golden set that runs on demand, outside the gate. Treat a research-based decision as a hypothesis the live run may reverse, and record any reversal with its measurement.
- **Don't prescribe the means.** Leave paths, filenames, libraries and structure to the delegate unless they are hard constraints. For those choices, "the existing system uses X" gives context without requiring X. Surface a choice you disagree with as a disagreement, rather than calling it a defect.
- **Long briefs go in a file.** Pass them by path or stdin, rather than as a long inline argument. Long inline arguments trip permission classifiers and shell quoting.
- **Name ranges, not commits, in a brief you will reuse.** A pinned SHA can send the next round back to an already reviewed commit. Use `git log --oneline <last-reviewed>..HEAD` to fail loudly when the range is stale.
- **Use the brief template and request its handoff.** Start from `references/brief-template.md`, asking for what it built, choices where the brief was silent, spec corrections, blockers and validation actually run. It also names commands for you and what must be redeployed after the push.

## Choosing the delegate

| Delegate | Strong at | Watch for |
|---|---|---|
| **A Claude subagent** (the Agent tool) | Work that needs this repository's context: it loads the project instructions automatically | Fresh context: none of your conversation or tool results. It loads project instructions and your settings and inherits your framing, so it never reviews your work. A review starts from the repository and brief alone (`independent-review`). A subagent may have no Agent tool of its own (observed `2026-06-10`). |
| **The Codex CLI** (`codex-agents`) | Building a stage to a brief; arguing a decision through as a peer over several turns | A new session is read-only unless told otherwise. A build that changed nothing can sound successful; check the disk. |
| **The Grok CLI** (`grok-agents`) | A peer, builder or reviewer from a different model family; the independent review's default reviewer (`independent-review`) | A round that could not read exits 0 after a sentence; length is the tell. |
| **Headless Claude Code** (`claude-agents`) | A session with none of your conversation: a builder or peer for a non-Claude agent, or a reviewer | Plain `-p` loads project and user instructions and auto-memory; only a restricted review starts from the repository alone. Resume keeps the model but drops effort, permission mode and tools unless re-sent (observed `2026-10-24`). |
| **The Antigravity CLI** (`gemini-agents`) | A requested second opinion from another model family, never a default; apply `gemini-agents` and get agreement first | Unsupported by Google on consumer plans (FAQ read `2026-11-13`); headless commands and writes ran unasked, and a refused permission ended the turn with exit 0 (observed `2026-11-14`, CLI 1.5.8, macOS). |

**The session that wrote the code never clears it.** Use a fresh reviewer who did not build the code. Prefer another model family, or use a fresh session of the builder's family when no other family can run. Never resume or fork the building thread, or use its subagent as reviewer. Apply `independent-review` for the loop and its stopping rule.

## Model and effort (Claude subagents)

- **Set the model explicitly on every spawn.** Omitting it inherits the parent's model, and "inherit" is never a routing decision: it is the absence of one.
- **Route by the job, not by how important it feels.** Use the smallest tier for bulk mechanics without judgement, such as renames, CSV parsing and log scans. Use the mid tier for scoped research, code exploration and building to a written spec. Reserve top tiers for multi-step reasoning and judgement bottlenecks: architecture, adversarial review and taste. Model names change every few months; the routing principle stays the same.
- **Use the top tier adversarially.** For example, ask "refute this audit" to test your own conclusions against the reviewer's reasoning.
- **Consult up.** A cheaper parent running a plan spawns one top-tier child for the judgement-heavy step. Pack its brief with the full context, the why and the specific decision, then treat its answer as the ruling on that step.
- **Pull down, decide up.** For data work, the child pulls and reduces to a table; the parent decides what it means.
- **Check the effort each spawn actually used.** Each subagent transcript records it: `grep -o '"effort":"[a-z]*"' <transcript> | sort | uniq -c`. Agent-tool spawns inherited parent effort at every tier (measured `2026-08-22`). Claude Code 2.1.310 adds an Agent-tool `effort` field (read `2026-10-24`). Workflow agent options and agent-definition frontmatter can also set it.
- **A child that finds the task needs more reasoning than its tier gives returns to the parent.** The parent reruns that step a tier up, rather than letting the child burn tokens.

## Several agents at once

- **Parallelise on evidence, not impatience.** Measure file overlap before deciding which changes can run together. Use `git show --stat --name-only --format= <ref>` per planned change.
- **Never two writers in one tree.** Give concurrent writers separate worktrees. Two writers in one tree can silently overwrite each other's work. Without separate worktrees, run them one at a time.
- **Worktrees carry their own dependencies.** Never remove a worktree whose `node_modules` links to another checkout; removal deletes through the link. Apply `independent-review` for the recipe.
- **Parallel stages merge through an integration branch.** Give each stage its own branch and worktree, and get a clean review before merging. Name that round in the merge and rerun the gate after every merge. Two passing branches can fail together when one changes a fixture's required fields. Resolve shared-ledger conflicts by keeping both sides' entries: backlog, decision log, test doc, architecture doc and plan. Concurrent briefs reserve shared sequence numbers, including each migration number and timestamp floor. They state which migrations are applied and which are only written.
- **Every merge checks the new migrations' timestamps against the ledger.** Run `migration list` on the database that will receive them, since a reserved floor cannot prevent collisions with migrations applied meanwhile.
- **Parallel sessions share more than a tree.** Give concurrent sessions separate accounts or run them sequentially. They share test accounts, the development database and workers against it, so scope background workers to named accounts.
- **The binding constraint is usually review, not build.** Keep review rounds sequential within a branch. Each round needs a stable account of changes since the last. Findings arrive only when a round runs, and fix commits produce the worst defects. Parallel building cannot shorten that chain.

## While it runs

- **Don't edit a tree a delegate is building in.** Wait or use another worktree.
- **Never `git checkout -- <file>` (or `git restore`) on a tree carrying uncommitted work.** Either destroys everything uncommitted in the file, a delegate's whole build included. Undo a probe by re-editing the exact change back, or use `git stash push -- <file>` around it. Commit a build before deliberately breaking it to verify a test.
- **Long runs go detached, with a completion marker.** Watch the marker for completion. Shell-tool timeouts kill their process trees. Keep state in files that survive your context window; apply `flight-deck`.
- **When a build runs late, measure where the time went before changing the model.** Split elapsed time into model time, gate runs, review rounds and waiting on a person. Read logs and timestamps rather than trusting an impression.

## When it comes back

- **A delegated diff is unreviewed code.** Read it before believing it. Its independent review comes before anything ships or deploys; in staged work it is the stage's series (`independent-review` § When).
- **Check the disk before believing a round happened.** Inspect `git status` and file times, since a run without write access can return a convincing report with no changes.
- **Re-run its tests yourself, and rewrite any evidence it wrote from your own run.** A piece inside a stage reruns the tests it touches; the full gate runs at stage end and before deploying pushes (`test-harness` § The gate). A builder's passing report remains a claim, even when it can reach development. Read every line it adds to a coverage map or status file; replace stage-completion evidence from your own run rather than inventing counts.
- **Before passing a delegate's "commands for the owner" up, do every one you can.** Use an API, CLI or key you hold and reread the result. Escalate only what needs a person: a dashboard-only click, money or taste.
- **A builder's objection that is a product decision goes to the owner.** Give it its own handoff section, keeping it separate from corrections you can accept yourself.
- **When you take a handoff over, put a dated status line at its top.** Say whether it is merged, which rounds reviewed it, where it is deployed, and what still waits. Keep your changes in their own section, leaving the delegate's text as written. Check claimed deploys against your environment log.
- **Audits record `HEAD` and `git status --short` at the start and again before delivering.** Put this instruction in the audit brief. Reverify findings about deleted, moved or renamed files against current `HEAD`.
- **Repeated correct fixes that don't work mean the model of the problem is wrong.** Stop fixing and distinguish two mechanisms with a screenshot or a question the owner can answer in a minute. Do this on the second failed fix, rather than the fifth. Green tests that exercise a sequence the user never receives turn "I don't understand this" into "this is fixed".
- **Converge before surfacing.** Bring one result or a clearly stated disagreement, leaving the owner to arbitrate intent and taste.
- **"Ready to test" means testable with nothing to do first.** Build, install or deploy it on the surface the owner uses, and say what needs reloading. Complete the handoff, or state its remaining edges plainly.

Each rule's origin, the case that taught it, is in `receipts.md` beside this file; read it when a rule's edge is unclear.

## How you can tell it worked

You can verify the delegate's report without asking it anything, and you repeat no result of its that you have not run yourself.

## Files

| File | Holds | Read when |
|---|---|---|
| `references/brief-template.md` | a brief's skeleton, with what each part is for, and the handoff the delegate writes back | writing any brief longer than a paragraph; reading a handoff |

© Paweł Huryn · MIT · phuryn/product-engineering

Similar skills

All skills for Agent setup: memory, context, orchestration →

delegation by other authors comes first.

delegation josstei The delegation skill structures prompts for delegated work, with prior-phase context, file boundaries, and validation steps. Use it when tasks pass between subagents. CX Codex +1 ★ 489repo stars subagent-delegation chrisbanes The subagent-delegation skill for Claude Code manages subagent task distribution and reassignment. It runs when the user invokes the playbook or explicitly requests delegation. CX Codex +1 123installs include-test-files-that-assert-on-behavior-being-changed-in-decl ZaxbyHub include-test-files-that-assert-on-behavior-being-changed-in-decl is a Claude Code skill that puts tests for changed behaviour in scope, so an agent fixes code alongside its checks. CX Codex +1 ★ 539repo stars competition-kerberos-delegation zhaoxuya520 competition-kerberos-delegation — a skill for Claude Code that automates Kerberos delegation analysis in CTF scenarios. It runs after context setup via $ctf-sandbox-orchestrator to verify exploitation paths. CX Codex +1 109installs delegation-core athola delegation-core delegates tasks to eight external CLIs (Gemini, Qwen, MiniMax, GLM, Muse, Codex, OpenCode, Glimmer). Keeps design and architecture local, sends execution out. CX Codex +1 1installs delegation-audit Son Nguyen delegation-audit is a Claude Code skill that reviews which models handled each subagent type and how those assignments performed. It flags weak results, repeated failures, and possible model mismatches. CX Codex +1 ★ 1,198repo stars codex-delegate amElnagdy The codex-delegate Claude Code skill sends bounded coding work to the OpenAI Codex CLI in the background. The orchestrator then checks the diff, reruns project gates, and lands the change. CX Codex +1 8,400installs

From the same set51

The whole set →
ui-design ui-design — a skill for Claude Code sets design rules for product interfaces and checks the results. It runs for product screens, prototypes, and mockups. CX Codex +1 ★ 741repo stars guardrail-hooks guardrail-hooks — a skill for Claude Code converts natural-language instructions into code paths, permission settings, and hooks. Runs when an agent breaks rules repeatedly. CX Codex +1 ★ 741repo stars security-audit-static security-audit-static is a Claude Code skill that statically audits code against documented trust boundaries. It runs on request for a security audit; a release can suggest it but does not start it. CX Codex +1 ★ 741repo stars start-here The start-here Claude Code skill identifies where product work stands and points to its next step. Run it for an idea, a change, a bug, a release, or an empty repository. CX Codex +1 ★ 741repo stars windows-agent-shell This Claude Code skill diagnoses Windows shell issues with paths, quoting, encoding, and line endings. It applies when command output is garbled or a command behaves differently across environments. CX Codex +1 ★ 741repo stars test-harness The test-harness Claude Code skill organizes tests so a green run checks real behavior. It activates for writing or running tests, verifying a fix, and investigating flaky or failed runs. CX Codex +1 ★ 741repo stars ship-check The ship-check Claude Code skill checks a project before release. It documents the app, runs code reviews, and assembles findings for human sign-off. CX Codex +1 ★ 741repo stars product-analytics The product-analytics Claude Code skill configures behavioral analytics without analytics cookies. It activates for work involving Clarity or PostHog, session recordings, or heatmaps. CX Codex +1 ★ 741repo stars

Project sponsors

Companies that keep this analytics open