Feature: Support directory-based agents in `claude --agent` — critical for multi-agent systems

Problem

claude --agent <name> only resolves single .md files from ~/.claude/agents/. Real-world agents that use multiple sub-agents, shared resources, and structured outputs require a directory, not a single file. There is currently no way to invoke a directory-based agent portably across projects.

What I need (and cannot do today)

# I'm working in ANY project
cd ~/my-actual-project

# I want to invoke my multi-agent system — and it WORKS from here
claude --agent momo-prototype-kit-agent

# Agent definition loads from ~/.claude/agents/momo-prototype-kit-agent/
# But my working directory stays ~/my-actual-project
# Agent reads its own resources (skills/, shared/) from its definition directory
# Agent writes output (products/, artifacts) to my current project

This is impossible today. The only workaround is cd ~/.claude/agents/momo-prototype-kit-agent && claude — which:

• Locks me into the agent directory — I lose my actual project context
• Output goes to the wrong place — artifacts land inside ~/.claude/agents/ instead of my project
• Breaks Claude Desktop App entirely — there is no cd equivalent in the Desktop UI
• Unusable for non-technical users — my team members cannot use Terminal commands

My agent structure (real example, in production)

~/.claude/agents/momo-prototype-kit-agent/
├── CLAUDE.md                         # Router — delegates to 4 sub-agents
├── .claude/agents/
│   ├── product-craft.md              # Sub-agent 1: requirements → product brief
│   ├── design-studio.md              # Sub-agent 2: brief → design specs
│   ├── code-forge.md                 # Sub-agent 3: specs → working prototype
│   └── code-polish.md                # Sub-agent 4: feedback → iterations
├── shared/                           # 13 files: inherited rules, templates, constraints
├── skills/                           # 4 SKILL.md files with references/
├── scripts/                          # Validation scripts
├── products/                         # Output artifacts per team
└── feedback/                         # Self-improvement loop

41 files total. This cannot be a single .md file. The sub-agents reference skills/, shared/, products/ via relative paths. The router enforces a constitution hierarchy (CLAUDE.md → shared/ → SKILL.md). Flattening this into separate .md files breaks CLAUDE.md inheritance, path resolution, and sub-agent isolation.

Why this is urgent

1. Multi-agent is the natural evolution — but the platform doesn't support it

Single-file agents are great for simple tasks. But production agents need:

• Sub-agent coordination (router pattern)
• Shared rules that sub-agents inherit (constitution hierarchy)
• Structured output (products/, artifacts/)
• Progressive disclosure (SKILL.md → references/ → shared/)

All of these require a directory. The current .md-only constraint forces users to either:

• Flatten everything (breaking architecture), or
• Lock themselves into the agent directory (losing project context)

2. Claude Desktop App users are completely blocked

Desktop App has no cd command. The only option is "Open Folder" — but that replaces the user's project with the agent directory. Non-technical users (my target: MoMo employees, product managers, designers) cannot use multi-agent systems at all on Desktop.

3. Skills collide with agent routing

When I open the agent directory as a project in Desktop, globally installed skills (~/.claude/skills/) fire before the agent's CLAUDE.md routing logic. Example: my kien-prototype-building-preview skill intercepts "build prototype" requests that should go to the agent's product-craft sub-agent. The agent's routing is completely bypassed.

4. Live-agent maintenance is painful

Source of truth is 05-deliverables/skills/momo-prototype-kit-agent/ (git-tracked). Runtime is ~/.claude/agents/momo-prototype-kit-agent/. Sync is manual rsync. If claude --agent supported directories natively, the maintenance story would be dramatically simpler.

Proposed behavior

Resolution logic (backward-compatible)

claude --agent my-agent
  1. Look for ~/.claude/agents/my-agent.md          ← existing behavior
  2. Look for ~/.claude/agents/my-agent/CLAUDE.md    ← NEW: directory-based
  3. Same priority: .claude/agents/ (project) > ~/.claude/agents/ (user)

Dual context (critical)

When a directory-based agent is invoked:

• Agent's definition context = ~/.claude/agents/my-agent/ — for resolving skills/, shared/, .claude/agents/ (sub-agents)
• User's working context = current directory — for reading project files, writing output
• Sub-agents inherit both contexts

Desktop App

Directory-based agents appear in @-mention autocomplete alongside .md agents. User selects one → agent loads with dual context.

Agent isolation

When --agent is active, the agent's routing logic (CLAUDE.md) takes precedence over globally installed skills. Skills should not intercept requests that the agent is designed to handle.

Impact

This would unblock:

• Multi-agent systems as first-class citizens (not just sub-agents spawned by code)
• Non-technical users on Desktop App
• Team distribution — share agent directories via git, everyone runs claude --agent from their own projects
• Clean separation — agent definitions portable, project output stays in project

Workarounds I've tried (all insufficient)

| Workaround | Why it fails |
|---|---|
| cd into agent dir + claude | Loses project context, output in wrong place, no Desktop support |
| Flatten to separate .md files | CLAUDE.md inheritance broken, paths must be hardcoded absolute, namespace pollution |
| Copy agent dir to ~/Documents/ + Open Folder in Desktop | Replaces project context, skills collide, manual sync |
| Shell alias alias momo-kit="cd ... && claude" | CLI only, no Desktop, non-technical users can't use |

None of these give me: invoke agent from any project, agent resolves its own resources, output stays in my project.

---

Submitted by a CPO building AI-powered prototyping workflows for a 50M+ user fintech app (MoMo, Vietnam). This agent is used by product managers and designers who have zero technical background.