# Subagent Expert

> Expert guidance for designing, building, orchestrating, and optimizing Claude Code subagents. Make sure to use this skill whenever the user mentions subagents, multi-agent systems, agent delegation, task routing, or the Agent SDK, even if they only ask for a basic agent definition.

- **Type:** Skill
- **Install:** `agentstack add skill-josephsanjaya-skills-subagent-expert`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [JosephSanjaya](https://agentstack.voostack.com/s/josephsanjaya)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [JosephSanjaya](https://github.com/JosephSanjaya)
- **Source:** https://github.com/JosephSanjaya/skills/tree/main/subagent-expert

## Install

```sh
agentstack add skill-josephsanjaya-skills-subagent-expert
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Subagent Expert — 2026 High-Performance Agentic Design

Isolate context. Prevent dilution. Keep parent thread clean. Use subagents as ephemeral, role-scoped context boundaries. Drop filler and articles. Express guidelines using compressed smart caveman style.

## 1. Quick Decision Matrix

| Task Nature | Design Choice | Target Topology | Key Reason |
| :--- | :--- | :--- | :--- |
| **Breadth-first read/explore** | Subagents | Fan-out/fan-in | Parallelize reads. Zero parent context bloat. |
| **Sequential dependencies** | Single Agent | Prompt chaining | Actions carry implicit decisions. Avoid split decisions. |
| **Relational data / comparison** | Subagents | Map-reduce-and-manage | Clean inputs, structured aggregation. |
| **Stateful edits / coding** | Single Writer | Code-Review-Loop | Parallel writes cause merge/AST conflicts. |
| **Unpredictable steps** | Subagents | Orchestrator-workers | Lead plans; specialized workers execute. |
| **Strict validation needed** | Subagents | Evaluator-optimizer | Prevent simulated success via adversarial check. |

## 2. Directory Structure

Specialized guidelines partitioned to prevent token bloat:

* **References**:
  * [architecture.md](references/architecture.md) — Topologies, single-writer rule, concurrency scaling rules.
  * [configuration.md](references/configuration.md) — Frontmatter specs, programmatic SDK (Python/TS), CLI flags, model routing.
  * [failures-mitigations.md](references/failures-mitigations.md) — 14 MAST failures, simulated success fixes, loop detection, worktrees.
  * [token-caching.md](references/token-caching.md) — 4-layer subprocess isolation, persistent streams, caching checkpoints, tool stability.
* **Auditor**:
  * [checklist.md](auditor/checklist.md) — Self-auditing checklists for subagent definitions.
* **Samples**:
  * [custom_subagent.md](samples/custom_subagent.md) — Reference read-only auditor subagent markdown.
  * [sdk_orchestration.py](samples/sdk_orchestration.py) — Python SDK subagent loop implementation.
* **Scripts**:
  * [audit_subagent.py](scripts/audit_subagent.py) — Automated python auditing tool.

Always read the specific file containing the details required for the task. Maintain strict token efficiency. Never bloat the parent context.

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [JosephSanjaya](https://github.com/JosephSanjaya)
- **Source:** [JosephSanjaya/skills](https://github.com/JosephSanjaya/skills)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** yes
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-josephsanjaya-skills-subagent-expert
- Seller: https://agentstack.voostack.com/s/josephsanjaya
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.