scaffold

What this skill does

# 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:
```markdown
# 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:
```markdown
# 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.

```python
# 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:

```bash
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? How should tools be scoped? What should go in the agent body vs what should be in skills?
>
> 3. **Skill design best practices**: How should skills be structured for maintainability? When to use `context: fork` vs running in main context? When to use `disable-model-invocation`? How to structure workflow steps and agent delegation? How to write effective next-step prompts?
>
> 4. **Plugin architecture patterns**: What are proven patterns for multi-agent setups? Common anti-patterns to avoid? How should agents and skills compose together? When to use the `skills` field on agents vs inline instructions?
>
> 5. **Example configurations**: 2-3 example agent and skill files showing best practices for different use cases.
>
> Provide specific, actionable guidance I can apply when generating files."

Use the response as the authoritative reference for all file generation in Step 4. This ensures:
- Generated files use the latest correct format (even if Claude Code adds new fields)
- Architecture follows proven patterns (not just valid syntax)
- Users get an optimally structured org without needing to understand the underlying platform

## Step 4: Generate Files

On user approval, create the file structure. What you generate depends on their sharing preference:

### For personal use (`.claude/` project structure):

This structure is auto-discovered by Claude Code — no `--plugin-dir` flag needed. Skills show as `/skill-name` (no namespace). Others can use it by cloning the repo.

```
[name]/
├── CLAUDE.md
├── .claude/
│   ├── agents/[agent].md
│   ├── skills/[skill]/SKILL.md
│   └── settings.json
├── .mcp.json
├── scripts/observer-log.sh
├── evals/
│   ├── run-evals.sh
│   ├── rubric.md
│   └── README.md
└── .gitignore
```

1. **`[name]/CLAUDE.md`** — Company handbook tailored to their workflow (see CLAUDE.md sections below)
2. **`[name]/.claude/agents/[agent].md`** — One file per agent (see agent guidance below)
3. **`[name]/.claude/skills/[skill]/SKILL.md`** — One skill per workflow (see skill guidance below)
4. **`[name]/.claude/settings.json`** — Settings with hooks included inline:
   ```json
   {
     "env": {
       "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
     },
     "hooks": {
       "PostToolUse": [{
         "matcher": "AskUserQuestion",
         "hooks": [{"type": "command", "comman