/scaffold

name: scaffold
description: Design and scaffold your own AI org structure with custom agents, skills, teams, hooks, and MCP servers. Interactive wizard that interviews you, proposes an org, generates a visual chart, and creates all files.
argument-hint: "optional: prior context to skip"
disable-model-invocation: true

Scaffold Your AI Org: $ARGUMENTS

You are helping the user design and build their own AI team. This is an interactive process. Adapt your language to the user's technical level (assessed in Step 1).

Step 1: Discovery Interview

If `$ARGUMENTS` provides context, use it to skip already-answered questions. Otherwise, ask these questions conversationally (not all at once - ask 1-2 at a time and respond to their answers):

**About them:** 1. **What do you do?** (e.g., "I'm a freelance web developer" or "I run a content agency") 2. **How technical are you?** (e.g., "I code daily" / "I can use a terminal but don't code" / "I'm not technical at all")

• Use their answer to calibrate ALL subsequent communication. For non-technical users: avoid jargon, explain every concept, use real-world analogies. For developers: be concise and technical.

**About their work:** 3. **What takes up most of your time?** (e.g., "Client proposals, code review, invoicing") 4. **What would your dream AI team look like?** (e.g., "A sales person, a designer, and a code reviewer") 5. **What tools do you use daily?** (e.g., "GitHub, Figma, Slack, Notion, Stripe") 6. **Do you have any MCP servers you'd like to connect?** MCP servers let your AI team interact with external tools (databases, calendars, APIs). If the user knows of specific MCP servers, include them. If not, skip — they can add them later. Do NOT generate fake MCP endpoint URLs for tools that don't have known servers.

**About sharing:** 7. **Is this just for you, or do you want to distribute it on the marketplace?**

• **Personal use (or sharing via git)**: We'll create a project with `.claude/` structure — simpler, no plugin packaging. Others can still use it by cloning the repo.
• **Marketplace distribution**: We'll create a full plugin with `.claude-plugin/plugin.json` and `marketplace.json` for the Anthropic marketplace.

**About their setup:** 8. **What Claude plan are you on?** (Pro, Max, Team, or API)

• Use this to calibrate model guidance in Step 5. Don't set explicit models on agents — all agents inherit from the session model, giving users runtime control via `/model`.

Check the examples in `skills/scaffold/examples/` for reference architectures that might match the user's profile.

Step 2: Propose Org Structure

Based on their answers, propose an org structure. Adapt the format to their technical level:

**For technical users**, use the detailed format:

# Your AI Org: [User's Business]

## Employees (Agents)
1. **[Name]** - [What they do, 1 sentence]
   - Skills: /[skill1], /[skill2]
   - Tools: [MCP1], [MCP2]

## SOPs (Skills)
1. `/[skill]` - [What it does]

## Automation (Hooks)
- After questions: Decisions are logged automatically for future reference

## Team Meetings (Agent Teams)
Invoke with `/kickoff [team-name] [topic]`:
1. **[Team Name]**: [Agent 1] + [Agent 2] + [Agent 3] - [When to use]

## Workflow
[skill 1] → [skill 2] → [skill 3] → ...

**For non-technical users**, use plain language:

# Your AI Team: [User's Business]

Think of this as your virtual company. Here's who works for you:

## Your Employees
1. **[Name]** - Like having a [real-world role] on your team. They handle [tasks].
2. ...

## What They Can Do For You
- Say "/[skill]" and [Employee] will [what happens in plain terms]
- ...

## They Work Together Too
Say "/kickoff [team name]" to start a team meeting:
- **[Team Name]**: When you need [outcome], these employees team up: [names]

## They'll Automatically...
- Keep a log of your decisions (so you can write about your journey later)
- [Other automated behaviors]

Ask the user to review and adjust before proceeding.

Step 3: Generate Visual Org Chart

Create a JSON config file for the org chart, then run the visualization script.

# Write the config to a JSON file inside the project
config = {
    "name": "[Org Name]",
    "agents": [
        {"name": "...", "skills": [...], "mcps": [...], "description": "..."}
    ],
    "skills": [{"name": "...", "description": "..."}],
    "mcps": [{"name": "...", "description": "..."}],
    "teams": [{"name": "...", "members": [...]}],
    "lifecycle": [...]
}

Save the config JSON inside the project directory (not /tmp/). For personal use: `[name]/.claude/org-chart.json`. For marketplace: `[name]/org-chart.json`.

The `visualize-org.py` script is in this plugin's `scripts/` directory — go up two directories from this SKILL.md (`skills/scaffold/SKILL.md` → plugin root) to find it. Run:

python3 <plugin-root>/scripts/visualize-org.py --config <project>/org-chart.json --output <project>/org-chart.html && open <project>/org-chart.html

Where `<project>` is the user's project directory (for personal use, save the HTML next to the config: `[name]/.claude/org-chart.html` or `[name]/org-chart.html` for marketplace).

Tell the user: "This chart shows your entire AI team — who they are, what they can do, and how the workflow connects them. Click on any card for details."

Step 3.5: Consult Claude Code Best Practices

Before generating any files, delegate to the `claude-code-guide` subagent for authoritative guidance:

> "I'm building a Claude Code project with custom agents and skills for a [user's domain] workflow. I need: > > 1. **Complete frontmatter specs**: All supported YAML frontmatter fields for custom agents (agents/*.md) and custom skills (skills/*/SKILL.md). For each field: name, type, required/optional, default value, and when to use it. > > 2. **Agent design best practices**: How should agent markdown bodies be structured? What makes an effective agent description for routing? H