gin-skills 1.0.0

package/skills/ai-build-ai/SKILL.md

@@ -0,0 +1,127 @@
+---
+name: ai-build-ai
+description: |
+  **AI Build AI**: Master guide for extending Claude Code — creating skills, custom subagents (agents), MCP servers, hooks, plugins, agent teams, running Claude programmatically, and more.
+  - MANDATORY TRIGGERS: create skill, new skill, add skill, write skill, build skill, create agent, new agent, add subagent, custom agent, create MCP, add MCP server, connect MCP, build MCP, headless mode, agent SDK, run claude programmatically, claude -p, how to extend claude, claude extensibility, how to create, how to build, hooks, plugin, agent team, team lead, multi-agent, multi-pass, verification workflow, orchestrate agents, sandbox, checkpoint, rewind, output style
+  - Use this skill when the user wants to: create or design a new Claude Code skill, build a custom subagent/agent, connect an MCP server or build their own, run Claude programmatically via CLI or SDK, configure hooks, build a plugin, set up agent teams, configure sandboxing, use checkpointing, or change output styles.
+  - Invoke the correct tutorial based on the topic argument.
+argument-hint: "[skill | agent | mcp | headless | hooks | plugins | teams | team-lead | memory | permissions | sandbox | checkpoint | output-styles]"
+disable-model-invocation: false
+---
+
+# AI Build AI
+
+You are an expert guide for extending Claude Code. Load the right tutorial based on what the user wants to build.
+
+## Tutorial Routing
+
+Run this to load the relevant tutorial:
+
+!`bash skills/skills/ai-build-ai/scripts/load-tutorial.sh $ARGUMENTS`
+
+---
+
+## How to Use This Skill
+
+After reading the tutorial above, help the user build their extension by:
+
+1. **Understanding their goal** — What do they want to create? What problem does it solve?
+2. **Choosing the right type** — Skill vs Agent vs MCP vs Headless (see decision table below)
+3. **Following the tutorial** — Apply the patterns from the loaded tutorial
+4. **Creating files** — Write the actual SKILL.md / agent .md / scripts / config
+5. **Testing** — Guide them through testing the new extension
+
+---
+
+## Decision Table: What Should I Build?
+
+| Goal | Build This |
+|------|-----------|
+| Teach Claude a repeatable workflow (code review, PR creation, deploy) | **Skill** |
+| Add domain knowledge Claude should always apply (API conventions, style guide) | **Skill** (`user-invocable: false`) |
+| Run heavy/verbose operations without polluting main context | **Subagent** |
+| Give Claude access to GitHub, Slack, databases, external APIs | **MCP Server** |
+| Run Claude in CI/CD, scripts, or automation | **Headless / Agent SDK** |
+| Run Claude in GitHub Actions | **Headless** (`/ai-build-ai headless`) |
+| Build an app that uses Claude as the AI backend | **Agent SDK** |
+| Isolate tool access (read-only, specific commands) | **Subagent** |
+| Auto-format files, block dangerous commands, send notifications | **Hooks** |
+| Distribute extensions to a team or community | **Plugin** |
+| Parallel work where teammates need to communicate | **Agent Teams** |
+| Orchestrate multi-agent workflow with quality gates and multi-pass review | **Team Lead** (`/ai-build-ai team-lead`) |
+| Persist coding standards across sessions | **CLAUDE.md / Memory** |
+| Restrict what files/commands Claude can touch | **Permissions** |
+| Add OS-level protection for bash commands | **Sandbox** |
+| Undo mistakes or experiment safely | **Checkpointing** |
+| Change Claude's tone, verbosity, or teaching style | **Output Style** |
+
+---
+
+## Topic Commands
+
+The user can invoke with a specific topic to load the deep tutorial immediately:
+
+| Command | What Loads |
+|---------|-----------|
+| `/ai-build-ai skill` | Create SKILL.md, frontmatter, arguments, dynamic context, supporting files |
+| `/ai-build-ai agent` | Create subagents, tools, models, memory, hooks, worktree isolation |
+| `/ai-build-ai mcp` | Connect remote/local MCP servers, build your own MCP server |
+| `/ai-build-ai headless` | `claude -p`, output formats, GitHub Actions, CI/CD, Python/TypeScript SDK |
+| `/ai-build-ai hooks` | All hook events, types, exit codes, matchers, notification matchers, recipes |
+| `/ai-build-ai plugins` | Plugin manifest, structure, skills/agents/hooks/MCP in plugins, distribution |
+| `/ai-build-ai teams` | Agent teams: enable, start, control, display modes, use cases |
+| `/ai-build-ai team-lead` | Team lead workflow: multi-agent orchestration, multi-pass verification, quality gates |
+| `/ai-build-ai memory` | CLAUDE.md, .claude/rules/, auto memory, imports, monorepo setup |
+| `/ai-build-ai permissions` | Allow/deny rules, modes, Bash/Read/Edit/WebFetch/MCP/Agent rules |
+| `/ai-build-ai sandbox` | OS-level enforcement, filesystem rules, network filtering |
+| `/ai-build-ai checkpoint` | Rewind, fork, session management, summarize from here |
+| `/ai-build-ai output-styles` | Built-in styles, custom styles, keep-coding-instructions |
+| `/ai-build-ai` | Overview of all 13 extension types + decision table |
+
+---
+
+## Supporting Files
+
+- `docs/overview.md` — Overview + decision table (loaded when no topic given)
+- `docs/create-skill.md` — Complete skill creation guide with examples
+- `docs/create-agent.md` — Complete agent creation guide with examples
+- `docs/create-mcp.md` — MCP server setup + building your own
+- `docs/headless-mode.md` — Programmatic usage, GitHub Actions, CI/CD, Agent SDK
+- `docs/hooks.md` — All hook events, types, matchers, notification matchers, recipes
+- `docs/plugins.md` — Plugin manifest, structure, distribution
+- `docs/agent-teams.md` — Team architecture, display modes, use cases
+- `docs/team-lead-workflow.md` — Team lead orchestration, multi-pass verification, specialist definitions
+- `docs/memory-claude-md.md` — CLAUDE.md, rules/, auto memory, imports
+- `docs/permissions.md` — Permission modes, rule syntax, examples
+- `docs/sandbox.md` — OS-level sandboxing, filesystem and network rules
+- `docs/checkpointing.md` — Rewind, fork, session management
+- `docs/output-styles.md` — Built-in and custom output styles
+- `scripts/load-tutorial.sh` — Routes to the right doc based on argument
+
+---
+
+## After Creating an Extension
+
+### For Skills
+1. Test auto-trigger: describe your use case naturally, confirm Claude loads the skill
+2. Test direct invoke: `/skill-name [args]`
+3. Check `SKILL.md` is under 500 lines — move excess to `docs/`
+4. Add to `ginstudio-skills/skills/` to share with the team (this repo)
+
+### For Agents
+1. Run `/agents` to verify the agent appears
+2. Ask Claude: "Use the [agent-name] agent to [task]"
+3. Check tool restrictions work correctly
+4. Enable `memory` if the agent should learn across sessions
+
+### For MCP Servers
+1. Run `claude mcp list` to confirm the server is registered
+2. In Claude Code, type `/mcp` to check server status
+3. Try using an MCP tool naturally: "Check GitHub for open PRs"
+4. Use `--scope project` + commit `.mcp.json` to share with your team
+
+### For Headless
+1. Test with a simple prompt first: `claude -p "hello" --output-format json`
+2. Verify tool permissions: use `--allowedTools` explicitly
+3. Check output format: pipe through `jq` to validate JSON structure
+4. Add to CI/CD workflow as a step

package/skills/ai-build-ai/docs/agent-teams.md

@@ -0,0 +1,293 @@
+# Tutorial: Agent Teams
+
+Agent teams let you coordinate multiple Claude Code instances working together. One session acts as the **team lead**, assigning tasks. Teammates work independently in their own context windows and can communicate directly with each other.
+
+---
+
+## Step 1: Agent Teams vs Subagents
+
+| | Subagents | Agent Teams |
+|--|-----------|-------------|
+| **Context** | Own window, reports back to main | Own window, fully independent |
+| **Communication** | One-way: report results to main agent | Direct messaging between teammates |
+| **Coordination** | Main agent manages all work | Shared task list, self-coordinating |
+| **Best for** | Focused tasks where only result matters | Complex work needing inter-agent discussion |
+| **Token cost** | Lower | Higher (each teammate = separate Claude instance) |
+
+**Use agent teams when:**
+- Teammates need to share findings and challenge each other (e.g., parallel hypothesis testing)
+- Work spans multiple independent domains (frontend + backend + tests)
+- You need sustained parallelism that exceeds one context window
+
+**Use subagents when:**
+- You just need parallel execution of isolated tasks
+- Workers only need to report back, not communicate
+- You want lower token cost
+
+---
+
+## Step 2: Enable Agent Teams
+
+Agent teams are **experimental** and disabled by default. Enable via `.claude/settings.json`:
+
+```json
+{
+  "env": {
+    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
+  }
+}
+```
+
+Or set in your shell environment:
+```bash
+export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1
+claude
+```
+
+---
+
+## Step 3: Start a Team
+
+Just describe the task and ask for a team:
+
+```
+Create an agent team to explore this codebase from different angles:
+one teammate on security, one on performance, one on maintainability.
+Have them each analyze and report findings.
+```
+
+Claude creates the team, spawns teammates, assigns tasks, and synthesizes results.
+
+You can also specify details:
+```
+Create a team with 4 teammates to refactor these modules in parallel.
+Use Sonnet for each teammate.
+```
+
+Claude won't create a team without your approval.
+
+---
+
+## Step 4: Display Modes
+
+**In-process (default):** all teammates run inside your terminal.
+- Press `Shift+Down` to cycle through teammates
+- Type to message the selected teammate
+- Press `Enter` to view a teammate's session, `Escape` to interrupt
+- Press `Ctrl+T` to toggle the task list
+
+**Split-panes:** each teammate gets its own pane (requires tmux or iTerm2).
+- See all teammates' output simultaneously
+- Click a pane to interact directly
+
+Configure in settings:
+```json
+{
+  "teammateMode": "in-process"
+}
+```
+
+Or for one session:
+```bash
+claude --teammate-mode in-process
+```
+
+**Auto** (default): uses split-panes if already in tmux, in-process otherwise.
+
+Install tmux for split-pane mode:
+```bash
+brew install tmux  # macOS
+```
+
+---
+
+## Step 5: Control the Team
+
+### Talk to teammates directly
+
+In in-process mode: press `Shift+Down` to cycle to the teammate, then type.
+In split-pane mode: click their pane.
+
+### Assign tasks
+
+Tell the lead to assign specific work:
+```
+Ask the security teammate to focus only on the auth module
+```
+
+Or teammates can self-claim from the shared task list.
+
+### Require plan approval before implementation
+
+```
+Spawn an architect teammate to refactor the auth module.
+Require plan approval before they make any changes.
+```
+
+The teammate stays in read-only plan mode until the lead approves. If rejected, they revise and resubmit.
+
+### Broadcast to all teammates
+
+```
+Tell all teammates to focus on critical issues only
+```
+
+Use sparingly — costs scale with team size.
+
+### Shut down a teammate
+
+```
+Ask the researcher teammate to shut down
+```
+
+### Clean up the team when done
+
+```
+Clean up the team
+```
+
+Always use the lead for cleanup. The lead checks all teammates have shut down first.
+
+---
+
+## Step 6: Architecture Details
+
+**Components:**
+- **Team lead**: the main Claude Code session, spawns and coordinates teammates
+- **Teammates**: separate Claude Code instances, each with their own context window
+- **Task list**: shared work items (`~/.claude/tasks/{team-name}/`)
+- **Mailbox**: direct messaging between agents (delivered automatically)
+
+**Team config stored at:** `~/.claude/teams/{team-name}/config.json`
+
+**Context each teammate gets:**
+- CLAUDE.md from project
+- MCP servers
+- Skills
+- The spawn prompt from the lead
+- Does NOT get the lead's conversation history
+
+**Permissions:** teammates inherit the lead's permission settings. If lead uses `--dangerously-skip-permissions`, all teammates do too.
+
+---
+
+## Step 7: Quality Gates with Hooks
+
+Use hooks to enforce rules across the team:
+
+```json
+{
+  "hooks": {
+    "TeammateIdle": [{
+      "hooks": [{
+        "type": "prompt",
+        "prompt": "Check if the teammate has completed all assigned tasks. If incomplete work remains, respond with {\"ok\": false, \"reason\": \"what still needs to be done\"}."
+      }]
+    }],
+    "TaskCompleted": [{
+      "hooks": [{
+        "type": "agent",
+        "prompt": "Verify the task was actually completed: run tests for the changed files and confirm they pass. Return {\"ok\": false, \"reason\": \"failing tests\"} if tests fail.",
+        "timeout": 60
+      }]
+    }]
+  }
+}
+```
+
+- `TeammateIdle` — fires when teammate goes idle. Exit code 2 / `"ok": false` sends feedback and keeps them working.
+- `TaskCompleted` — fires when a task is marked complete. Can block completion.
+
+---
+
+## Step 8: Use Case Examples
+
+### Parallel code review
+
+```
+Create an agent team to review PR #142. Spawn three reviewers:
+- One focused on security implications
+- One checking performance impact
+- One validating test coverage
+Have them each review and report findings.
+```
+
+### Competing hypotheses debugging
+
+```
+Users report the app exits after one message instead of staying connected.
+Spawn 5 agent teammates to investigate different hypotheses. Have them talk
+to each other to try to disprove each other's theories, like a scientific debate.
+Update the findings doc with whatever consensus emerges.
+```
+
+### Cross-layer feature implementation
+
+```
+Implement the new payment flow across:
+- Backend: API endpoints and service logic
+- Frontend: UI components and state management
+- Mobile: React Native screens
+- Tests: E2E test coverage
+
+Create a team with 4 teammates, one per layer. Have the backend teammate
+finish the API contracts first, then the others can work in parallel.
+```
+
+---
+
+## Step 9: Best Practices
+
+**Team size:** start with 3-5 teammates. More teammates = more coordination overhead and higher token cost.
+
+**Task sizing:**
+- Too small: coordination overhead exceeds benefit
+- Too large: teammates work too long without check-ins, risk wasted effort
+- Ideal: 5-6 tasks per teammate, each producing a clear deliverable
+
+**Avoid file conflicts:** two teammates editing the same file causes overwrites. Assign each teammate different files.
+
+**Give enough context in spawn prompt:** teammates don't inherit conversation history — include task-specific details in the prompt.
+
+**Monitor and steer:** check in on progress, redirect approaches not working, synthesize findings as they come in.
+
+**Wait for teammates:** if the lead starts implementing instead of waiting:
+```
+Wait for your teammates to complete their tasks before proceeding
+```
+
+---
+
+## Step 10: Known Limitations (Experimental)
+
+- **No session resumption with in-process teammates**: `/resume` doesn't restore them. Spawn new teammates if needed.
+- **Task status can lag**: teammates sometimes fail to mark tasks complete. Check manually if stuck.
+- **Shutdown can be slow**: teammates finish current tool call before shutting down.
+- **One team per session**: a lead can only manage one team at a time.
+- **No nested teams**: teammates cannot spawn their own teams.
+- **Lead is fixed**: the session that creates the team leads forever.
+- **Split panes don't work in**: VS Code integrated terminal, Windows Terminal, Ghostty.
+
+---
+
+## Quick Reference
+
+```bash
+# Enable agent teams
+echo '{"env":{"CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS":"1"}}' > .claude/settings.json
+
+# Start a team (in Claude Code):
+"Create an agent team with 3 teammates to research X, Y, Z in parallel"
+
+# Navigate between teammates (in-process mode):
+Shift+Down         # Cycle to next teammate
+Ctrl+T             # Toggle task list
+Enter              # View teammate's session
+Escape             # Interrupt current teammate turn
+
+# Control the team:
+"Ask teammate [name] to focus on [specific area]"
+"Require plan approval before any teammate makes changes"
+"Ask all teammates to shut down"
+"Clean up the team"
+```

package/skills/ai-build-ai/docs/checkpointing.md

@@ -0,0 +1,161 @@
+# Tutorial: Checkpointing & Rewind
+
+Claude Code automatically saves checkpoints before each file edit. Rewind any mistake without losing work — across sessions.
+
+---
+
+## Step 1: How Checkpoints Work
+
+- Created automatically before each file edit
+- One checkpoint per **user prompt** (not per individual file change within a prompt)
+- Persist across sessions (accessible when you resume)
+- Auto-cleaned after 30 days
+
+**What checkpoints track:**
+- File changes made by Edit, Write, and NotebookEdit tools
+
+**What checkpoints do NOT track:**
+- Files modified by bash commands (`rm`, `mv`, `cp`, shell scripts)
+- Changes made outside Claude Code (manual edits in your editor)
+- Edits from other concurrent Claude sessions on the same files
+
+---
+
+## Step 2: Open the Rewind Menu
+
+```bash
+Esc+Esc      # Press Escape twice
+/rewind      # Same effect
+/checkpoint  # Alias
+```
+
+This opens a scrollable list of all prompts from the session. Select the checkpoint you want to revert to.
+
+---
+
+## Step 3: Rewind Options
+
+When you select a checkpoint, you have 5 choices:
+
+| Option | What it does |
+|--------|-------------|
+| **Restore code and conversation** | Reverts both file changes AND conversation history to that point |
+| **Restore conversation** | Rewinds messages only; keeps current code state |
+| **Restore code** | Reverts file changes only; keeps full conversation history |
+| **Summarize from here** | Compresses conversation from this point forward; early messages stay intact |
+| **Never mind** | Exit without making any changes |
+
+After any restore option, the original prompt from the selected message is placed back in your input field.
+
+---
+
+## Step 4: Summarize from Here
+
+**"Summarize from here"** is a targeted context management tool — different from `/compact`:
+
+```
+/rewind → select message → "Summarize from here"
+```
+
+- Messages BEFORE the selected point remain in **full detail**
+- Messages AFTER (and including) the selected point are replaced with an AI summary
+- The original messages are still stored in the session transcript (Claude can still reference them)
+- Optionally provide instructions to guide what the summary focuses on
+
+| | `/compact` | "Summarize from here" |
+|-|------------|----------------------|
+| Scope | Entire conversation | From selected point forward |
+| Preserves early context in full | No | Yes |
+| Use when | Context is almost full, start fresh | You want to keep early context detailed |
+
+---
+
+## Step 5: Fork a Session
+
+To experiment on a branch without losing your current state:
+
+```bash
+# Fork via command (creates a new session from the current point)
+/fork
+
+# Fork with a name
+/fork experiment-v2
+
+# Fork from CLI (branches off the most recent conversation)
+claude --continue --fork-session
+```
+
+Forked sessions appear **grouped under their root session** in the session picker. The original session stays completely intact.
+
+---
+
+## Step 6: Session Management
+
+### CLI Flags
+
+```bash
+# Resume most recent conversation in the current directory
+claude --continue
+
+# Open interactive session picker
+claude --resume
+
+# Resume a specific session by name
+claude --resume auth-refactor
+
+# Resume the session linked to a specific GitHub PR
+claude --from-pr 123
+```
+
+### In-Session Commands
+
+```bash
+# Name the current session for easy resuming later
+/rename auth-refactor
+
+# Switch to a different conversation without exiting
+/resume
+
+# Fork current conversation at this point
+/fork
+```
+
+### Session Picker Keyboard Shortcuts
+
+| Key | Action |
+|-----|--------|
+| `P` | Preview session content |
+| `R` | Rename highlighted session |
+| `/` | Search / filter sessions |
+| `A` | Toggle: current directory / all projects |
+| `B` | Filter by current git branch |
+| `→` / `←` | Expand / collapse grouped sessions |
+
+---
+
+## Quick Reference
+
+```bash
+Esc+Esc         # Open rewind menu
+/rewind         # Same as Esc+Esc
+/fork           # Fork current session at this point
+/compact        # Compact the entire conversation
+
+claude --continue         # Resume most recent conversation
+claude --resume           # Interactive session picker
+claude --resume <name>    # Resume by name
+claude --from-pr 123      # Resume session linked to a PR
+```
+
+**Restore code only** (keep conversation):
+→ `/rewind` → select checkpoint → **Restore code**
+
+**Restore conversation only** (keep code):
+→ `/rewind` → select checkpoint → **Restore conversation**
+
+**Compress context from a point**:
+→ `/rewind` → select checkpoint → **Summarize from here**
+
+---
+
+**Design intent:** Checkpointing is "local undo" that complements Git's "permanent history". Use Git for versioning your work across the project; use checkpointing for in-session recovery from mistakes.