addyosmani / addyosmani/agent-skills
Docs: distinguish repo orchestration convention from current Claude Code behavior
- Lingua principale
- JavaScript
- Stelle
- 93.8k
- Fork
- 10k
- Merge medio
- 3g 15h
- PR unite (30g)
- 23
Descrizione
## Context
The Claude Code orchestration notes in this repo appear to predate the June 2026 Claude Code updates, so this looks like documentation drift rather than incorrect original guidance.
The repo currently describes `subagents cannot spawn other subagents` as a hard Claude Code platform constraint, while also using that constraint to reinforce the repo rule that personas should not invoke other personas.
That repo rule still seems valuable and should remain. The part that may need updating is the platform-mapping wording.
## Current drift candidates
- `AGENTS.md`, `docs/agents.md`, and `references/orchestration-patterns.md` describe nested subagents as impossible on Claude Code.
- The Agent Teams worked example still includes a separate `Clean up the team` instruction, which reads like older `TeamDelete`-style behavior.
## Current Claude Code behavior
- As of [Claude Code v2.1.172](https://code.claude.com/docs/en/changelog#2-1-172), subagents can spawn their own subagents, up to 5 levels deep.
- The official docs still allow projects to prevent that by omitting the `Agent` tool from an explicit tools allowlist or by using `disallowedTools`.
- As of Claude Code v2.1.178, Agent Teams no longer use `TeamCreate` / `TeamDelete`; with `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1`, each session has one implicit team and teammates are spawned directly with the Agent tool `name` parameter.
- Agent Teams still cannot nest: teammates cannot spawn their own teammates.
## Suggested direction
Keep the repo orchestration convention:
- personas do not invoke other personas;
- composition remains the job of slash commands or the user;
- Agent Teams remain the only endorsed pattern when teammates need to communicate directly.
But reword the Claude Code compatibility notes so the repo rule is framed as a deliberate project convention, not as a current hard platform limitation.
For the Agent Teams example, remove or soften the separate `Clean up the team` instruction; current docs describe no separate `TeamDelete`-style cleanup step, while still documenting graceful teammate shutdown and possible orphaned tmux cleanup.
## Non-goal
This issue is not asking the repo to adopt nested persona trees. It is only about keeping the Claude Code interop documentation accurate while preserving the repo orchestration model.
## Sources
- Claude Code subagents docs: https://code.claude.com/docs/en/sub-agents
- Claude Code Agent Teams docs: https://code.claude.com/docs/en/agent-teams
- Claude Code changelog: https://code.claude.com/docs/en/changelog
Guida per i contributori
Apri la guida per i contributori
Valutazione
Questa issue non è ancora stata valutata.