ginskill-init 1.0.0

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

@@ -0,0 +1,162 @@
+# AI Build AI — Overview
+
+You are helping the user understand and use Claude Code's extensibility system. Claude Code can be extended in nine ways:
+
+---
+
+## The Nine Extension Types
+
+### 1. Skills (`/ai-build-ai skill`)
+**What:** Reusable prompt playbooks stored as `SKILL.md` files. Auto-invoked by Claude or triggered with `/skill-name`.
+**When:** Repeatable workflows, domain knowledge, step-by-step procedures Claude should follow consistently.
+**Location:** `.claude/skills/<name>/SKILL.md` (project) | `~/.claude/skills/<name>/SKILL.md` (personal)
+
+### 2. Custom Subagents (`/ai-build-ai agent`)
+**What:** Specialized AI assistants with their own context window, system prompt, tools, and permissions.
+**When:** Context isolation for verbose tasks, restricted tool access, parallel workloads, domain specialists.
+**Location:** `.claude/agents/<name>.md` (project) | `~/.claude/agents/<name>.md` (personal)
+
+### 3. MCP Servers (`/ai-build-ai mcp`)
+**What:** External tools and data sources connected via Model Context Protocol. Gives Claude access to GitHub, databases, Slack, APIs.
+**When:** Claude needs to interact with external systems.
+**Command:** `claude mcp add --transport http|sse|stdio <name> <url-or-command>`
+
+### 4. Headless / Agent SDK (`/ai-build-ai headless`)
+**What:** Running Claude programmatically from scripts, CI/CD, or the Python/TypeScript SDK.
+**When:** Automation, batch processing, CI/CD integration, building apps with Claude as the AI.
+**Key flag:** `claude -p "your prompt" --allowedTools "Read,Edit,Bash"`
+
+### 5. Hooks (`/ai-build-ai hooks`)
+**What:** Shell commands / HTTP endpoints / LLM prompts that fire automatically at lifecycle points (PreToolUse, PostToolUse, SessionStart, Stop, etc.).
+**When:** Auto-format files on save, block dangerous commands, inject context, send notifications, enforce rules deterministically.
+**Location:** `.claude/settings.json` under `"hooks"` key
+
+### 6. Plugins (`/ai-build-ai plugins`)
+**What:** Packaged bundles of skills + agents + hooks + MCP servers with a manifest (`plugin.json`), versioning, and marketplace distribution.
+**When:** Sharing across teams/community, versioned releases, one-command installs.
+**Structure:** `my-plugin/.claude-plugin/plugin.json` + `skills/`, `agents/`, `hooks/`, `.mcp.json`
+
+### 7. Agent Teams (`/ai-build-ai teams`)
+**What:** Multiple Claude Code instances coordinated as a team — a lead assigns tasks, teammates work independently and communicate directly.
+**When:** Complex parallel work needing inter-agent discussion, competing hypothesis testing, cross-layer features.
+**Enable:** `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` (experimental)
+
+### 8. CLAUDE.md & Memory (`/ai-build-ai memory`)
+**What:** Persistent instructions (CLAUDE.md) and auto-learning (auto memory) that survive across sessions.
+**When:** Project conventions, coding standards, architecture decisions, personal workflow preferences.
+**Location:** `./CLAUDE.md`, `~/.claude/CLAUDE.md`, `.claude/rules/*.md`
+
+### 9. Permissions (`/ai-build-ai permissions`)
+**What:** Fine-grained control over which tools, files, and domains Claude can access — allow/deny/ask rules.
+**When:** Restricting Claude to safe operations, CI/CD automation, enterprise policy enforcement.
+**Location:** `.claude/settings.json` under `"permissions"` key
+
+### 10. Sandbox (`/ai-build-ai sandbox`)
+**What:** OS-level enforcement that restricts what bash commands (and their child processes) can read, write, or access on the network — independent of Claude's permission rules.
+**When:** Extra security for untrusted scripts, preventing accidental writes to sensitive files, restricting outbound network access.
+**Platform:** macOS (Seatbelt), Linux/WSL2 (bubblewrap+socat)
+
+### 11. Checkpointing (`/ai-build-ai checkpoint`)
+**What:** Automatic snapshots before every file edit. Rewind code, conversation, or both to any previous state. Fork sessions to experiment without losing work.
+**When:** Recovering from mistakes, experimenting with risky changes, managing context.
+**How:** `Esc+Esc` or `/rewind` to open rewind menu; `claude --continue` / `--resume` to manage sessions.
+
+### 12. Output Styles (`/ai-build-ai output-styles`)
+**What:** Modify Claude's communication style — tone, verbosity, teaching mode. Replaces sections of Claude's default system prompt.
+**When:** Learning mode, pair programming style, domain expert persona, ultra-concise mode.
+**Location:** `~/.claude/output-styles/` (personal) or `.claude/output-styles/` (project)
+
+---
+
+## 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 | **Skill** (`user-invocable: false`) |
+| Isolate verbose output from main conversation context | **Subagent** |
+| Restrict tools for a specific task type | **Subagent** |
+| Connect to GitHub / Slack / database / internal API | **MCP Server** |
+| Build your own custom MCP server | **MCP Server** (build it with the MCP SDK) |
+| Run Claude in CI/CD, scripts, or automation | **Headless / Agent SDK** |
+| Build an app that uses Claude as the AI backend | **Agent SDK** (Python/TypeScript) |
+| Auto-format files after every edit | **Hook** (PostToolUse) |
+| Block dangerous commands deterministically | **Hook** (PreToolUse) |
+| Send notifications when Claude needs input | **Hook** (Notification) |
+| Enforce rules that must ALWAYS apply (not just Claude deciding) | **Hook** |
+| Share extensions with your team or community | **Plugin** |
+| Distribute versioned, installable extensions | **Plugin** |
+| Parallel work needing teammates to discuss with each other | **Agent Teams** |
+| Persist coding standards for the whole team | **CLAUDE.md** (committed) |
+| Restrict what files/commands Claude can touch | **Permissions** |
+| Enterprise-wide policy enforcement | **Managed Permissions** |
+| Add OS-level protection for bash commands | **Sandbox** |
+| Block bash from accessing secrets or network | **Sandbox** |
+| Undo a mistake without losing other work | **Checkpointing** (`Esc+Esc`) |
+| Change Claude's tone or teaching style | **Output Style** |
+| Create a "learning mode" or "mentor mode" | **Output Style** |
+
+---
+
+## Quick Start
+
+```bash
+# 1. Create a skill
+mkdir -p .claude/skills/my-skill
+cat > .claude/skills/my-skill/SKILL.md << 'EOF'
+---
+name: my-skill
+description: What this skill does and when to use it
+---
+# Instructions for Claude...
+EOF
+
+# 2. Create a subagent
+mkdir -p .claude/agents
+cat > .claude/agents/my-agent.md << 'EOF'
+---
+name: my-agent
+description: When Claude should delegate to this agent
+tools: Read, Grep, Glob
+model: haiku
+---
+You are a specialized agent...
+EOF
+
+# 3. Add a hook (in .claude/settings.json)
+# { "hooks": { "PostToolUse": [{ "matcher": "Edit|Write", "hooks": [{ "type": "command", "command": "..." }] }] } }
+
+# 4. Add an MCP server
+claude mcp add --transport http github https://api.githubcopilot.com/mcp/
+
+# 5. Run Claude programmatically
+claude -p "Summarize this project" --output-format json
+
+# 6. Create CLAUDE.md
+/init   # Auto-generates from codebase
+
+# 7. Create a plugin
+mkdir -p my-plugin/.claude-plugin
+echo '{"name":"my-plugin","description":"...","version":"1.0.0"}' > my-plugin/.claude-plugin/plugin.json
+claude --plugin-dir ./my-plugin   # Test it
+```
+
+---
+
+## Topic Commands
+
+| Command | Loads |
+|---------|-------|
+| `/ai-build-ai skill` | SKILL.md format, frontmatter, arguments, dynamic context, examples |
+| `/ai-build-ai agent` | Subagent config, tools, models, memory, hooks, examples |
+| `/ai-build-ai mcp` | MCP server setup + building your own MCP server |
+| `/ai-build-ai headless` | `claude -p`, output formats, CI/CD, Python/TS SDK |
+| `/ai-build-ai hooks` | All hook events, types, exit codes, 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 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, path prefixes |
+| `/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` | This overview + decision table |

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

@@ -0,0 +1,391 @@
+# Tutorial: Permissions
+
+Claude Code has a permission system to control what tools, files, and domains Claude can access. Configure it in `settings.json` or manage interactively with `/permissions`.
+
+---
+
+## Step 1: The Permission Tiers
+
+| Tool type | Default behavior |
+|-----------|----------------|
+| Read-only (Read, Grep, Glob) | No approval needed |
+| Bash commands | Prompts first time per project per command |
+| File modification (Edit, Write) | Prompts, "yes don't ask again" lasts until session end |
+
+Rules are evaluated: **deny → ask → allow**. The first matching rule wins.
+
+---
+
+## Step 2: Permission Modes
+
+Set `defaultMode` in `.claude/settings.json`:
+
+```json
+{
+  "defaultMode": "acceptEdits"
+}
+```
+
+| Mode | Behavior |
+|------|----------|
+| `default` | Standard: prompts on first use of each tool |
+| `acceptEdits` | Auto-accepts file edits for the session |
+| `plan` | Read-only: Claude can analyze but not modify files or execute commands |
+| `dontAsk` | Auto-denies tools unless pre-approved via rules |
+| `bypassPermissions` | Skips ALL permission prompts (only in safe/isolated environments) |
+
+---
+
+## Step 3: Permission Rules
+
+Define allow/deny rules in `.claude/settings.json`:
+
+```json
+{
+  "permissions": {
+    "allow": [
+      "Bash(npm run *)",
+      "Bash(git commit *)",
+      "Read",
+      "Edit(/src/**)"
+    ],
+    "deny": [
+      "Bash(git push *)",
+      "Bash(rm -rf *)",
+      "Edit(.env)"
+    ]
+  }
+}
+```
+
+You can also set `ask` rules to force a prompt even if normally auto-allowed:
+```json
+{
+  "permissions": {
+    "ask": ["Bash(git push *)"]
+  }
+}
+```
+
+---
+
+## Step 4: Rule Syntax
+
+### Match all uses of a tool
+```
+Bash          ← any bash command
+Read          ← any file read
+Edit          ← any file edit
+WebFetch      ← any web fetch
+```
+
+### Exact match
+```
+Bash(npm run build)        ← only this exact command
+Read(./.env)               ← only this file
+```
+
+### Wildcard prefix matching (`*`)
+```
+Bash(npm run *)            ← any command starting with "npm run "
+Bash(git *)                ← any git command
+Bash(* --version)          ← any command ending with " --version"
+Bash(git * main)           ← git checkout main, git merge main, etc.
+```
+
+**Space before `*` matters:**
+- `Bash(ls *)` — matches `ls -la` but NOT `lsof` (word boundary enforced)
+- `Bash(ls*)` — matches both `ls -la` AND `lsof` (no boundary)
+
+**Shell operators are NOT trusted:**
+- `Bash(safe-cmd *)` will NOT give permission to `safe-cmd && dangerous-cmd`
+- Claude Code is operator-aware — each chained command is checked separately
+
+### File path patterns
+
+For `Read` and `Edit` rules, use gitignore-style patterns:
+
+| Pattern prefix | Meaning | Example |
+|---------------|---------|---------|
+| `//path` | Absolute from filesystem root | `Read(//Users/alice/secrets/**)` |
+| `~/path` | From home directory | `Read(~/.ssh/*)` |
+| `/path` | Relative to project root | `Edit(/src/**/*.ts)` |
+| `path` | Relative to cwd | `Read(*.env)` |
+
+```json
+{
+  "permissions": {
+    "allow": [
+      "Edit(/src/**/*.ts)",
+      "Edit(/src/**/*.tsx)",
+      "Read"
+    ],
+    "deny": [
+      "Edit(.env)",
+      "Edit(package-lock.json)",
+      "Read(//etc/passwd)"
+    ]
+  }
+}
+```
+
+Note: `*` matches files in one directory, `**` matches recursively.
+
+### WebFetch rules
+
+```
+WebFetch(domain:github.com)      ← only github.com
+WebFetch(domain:api.example.com) ← only this API
+```
+
+### MCP tool rules
+
+```
+mcp__puppeteer                   ← all tools from puppeteer MCP server
+mcp__puppeteer__*                ← same (wildcard form)
+mcp__github__search_repositories ← specific tool from github server
+mcp__.*__write.*                 ← any "write" tool across all MCP servers (regex)
+```
+
+### Agent/Subagent rules
+
+```
+Agent(Explore)              ← the Explore built-in agent
+Agent(Plan)                 ← the Plan built-in agent
+Agent(my-custom-agent)      ← your custom agent
+```
+
+To block Claude from using specific agents:
+```json
+{
+  "permissions": {
+    "deny": ["Agent(Explore)", "Agent(dangerous-agent)"]
+  }
+}
+```
+
+---
+
+## Step 5: Practical Configuration Examples
+
+### Safe exploration mode (read-only + specific bash)
+
+```json
+{
+  "permissions": {
+    "allow": [
+      "Read",
+      "Bash(git log *)",
+      "Bash(git diff *)",
+      "Bash(git status)",
+      "Bash(npm test *)",
+      "Bash(* --help *)",
+      "Bash(* --version)"
+    ],
+    "deny": [
+      "Edit",
+      "Write",
+      "Bash(git push *)",
+      "Bash(rm *)",
+      "Bash(sudo *)"
+    ]
+  }
+}
+```
+
+### Development workflow (allow most, deny dangerous)
+
+```json
+{
+  "permissions": {
+    "allow": [
+      "Read",
+      "Edit(/src/**)",
+      "Edit(/tests/**)",
+      "Write(/src/**)",
+      "Bash(npm run *)",
+      "Bash(bun *)",
+      "Bash(git commit *)",
+      "Bash(git add *)",
+      "Bash(git diff *)",
+      "Bash(git log *)",
+      "Bash(git status)"
+    ],
+    "deny": [
+      "Edit(.env)",
+      "Edit(.env.local)",
+      "Edit(package-lock.json)",
+      "Bash(git push *)",
+      "Bash(rm -rf *)",
+      "Bash(sudo *)",
+      "Bash(curl *)",
+      "Bash(wget *)"
+    ]
+  }
+}
+```
+
+### CI/CD (fully open for automation)
+
+For automated pipelines in isolated environments:
+```json
+{
+  "defaultMode": "bypassPermissions"
+}
+```
+
+Or via CLI flag: `claude -p "..." --dangerously-skip-permissions`
+
+---
+
+## Step 6: Settings Files and Precedence
+
+Permissions can be set at multiple levels. Higher priority wins for conflicting rules:
+
+```
+1. Managed policy settings     ← Highest (org admin, can't be overridden)
+2. CLI flags (--disallowedTools)
+3. .claude/settings.local.json (project-local, not committed)
+4. .claude/settings.json       (project-level, committed to git)
+5. ~/.claude/settings.json     ← Lowest (personal defaults)
+```
+
+**Example: deny list via CLI:**
+```bash
+claude --disallowedTools "Agent(Explore),Bash(rm *)"
+```
+
+**Example: settings.json with all permission options:**
+```json
+{
+  "defaultMode": "default",
+  "permissions": {
+    "allow": [
+      "Bash(npm run *)",
+      "Read",
+      "Edit(/src/**)"
+    ],
+    "ask": [
+      "Bash(git push *)"
+    ],
+    "deny": [
+      "Bash(sudo *)",
+      "Edit(.env)"
+    ]
+  }
+}
+```
+
+---
+
+## Step 7: Extend Permissions with Hooks
+
+For dynamic, context-aware permission decisions, use `PreToolUse` hooks:
+
+```json
+{
+  "hooks": {
+    "PreToolUse": [{
+      "matcher": "Bash",
+      "hooks": [{
+        "type": "command",
+        "command": ".claude/hooks/validate-commands.sh"
+      }]
+    }]
+  }
+}
+```
+
+```bash
+#!/bin/bash
+# .claude/hooks/validate-commands.sh
+INPUT=$(cat)
+CMD=$(echo "$INPUT" | jq -r '.tool_input.command // empty')
+
+# Block production deployments without approval
+if echo "$CMD" | grep -q "deploy.*production"; then
+  echo "Blocked: production deployments require manual approval from lead" >&2
+  exit 2
+fi
+
+# Block database migrations in non-migration sessions
+if echo "$CMD" | grep -q "migrate.*run"; then
+  echo "Blocked: run migrations via the /migrate skill instead" >&2
+  exit 2
+fi
+
+exit 0
+```
+
+Hooks run before the permission system, giving you fine-grained runtime control that static rules can't provide.
+
+---
+
+## Step 8: Working Directories
+
+By default, Claude accesses files in its launch directory. Extend access:
+
+```bash
+# At startup
+claude --add-dir /path/to/shared-lib --add-dir /path/to/config
+
+# During session
+/add-dir /path/to/new-directory
+
+# Permanently in settings
+```
+
+**In settings.json:**
+```json
+{
+  "additionalDirectories": [
+    "/path/to/shared-lib",
+    "../sibling-project"
+  ]
+}
+```
+
+Files in additional directories follow the same permission rules as the main working directory.
+
+---
+
+## Step 9: Managed / Enterprise Settings
+
+For org-wide policies, admins deploy settings to:
+- macOS: `/Library/Application Support/ClaudeCode/`
+- Linux/WSL: `/etc/claude-code/`
+- Windows: `C:\Program Files\ClaudeCode\`
+
+**Managed-only settings** (can only be set by admin):
+
+| Setting | Effect |
+|---------|--------|
+| `disableBypassPermissionsMode: "disable"` | Prevents `bypassPermissions` mode entirely |
+| `allowManagedPermissionRulesOnly: true` | Only managed rules apply; users can't add their own |
+| `allowManagedHooksOnly: true` | Only managed hooks run; user/project hooks blocked |
+| `allowManagedMcpServersOnly: true` | Only managed MCP server allowlist applies |
+
+---
+
+## Quick Reference
+
+```bash
+# View and manage permissions interactively
+/permissions
+
+# Allow specific tools via CLI
+claude --allowedTools "Read,Edit,Bash(npm run *)"
+
+# Deny specific tools via CLI
+claude --disallowedTools "Agent(Explore),Bash(rm *)"
+
+# Skip all permissions (CI only!)
+claude -p "..." --dangerously-skip-permissions
+
+# Run in plan mode (read-only, no edits)
+claude --default-permission-mode plan
+```
+
+**Rule priority:** `deny > ask > allow` — deny always wins.
+
+**Rule tip:** Use hooks for dynamic decisions, rules for static patterns.