ginskill-init 1.0.0

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

@@ -0,0 +1,396 @@
+# Tutorial: Create a Plugin
+
+Plugins package skills, agents, hooks, and MCP servers into a distributable unit. Use plugins when you want to share functionality across teams, publish to a marketplace, or maintain versioned releases that can be installed with one command.
+
+---
+
+## Step 1: Plugins vs Standalone Config
+
+| Aspect | Standalone (`.claude/`) | Plugin |
+|--------|------------------------|--------|
+| Skill names | `/hello` | `/my-plugin:hello` (namespaced) |
+| Sharing | Manual copy | Install via marketplace |
+| Versioning | Git-based | Semantic versioning in manifest |
+| Best for | Personal, project-specific, experiments | Team distribution, open source, reuse |
+
+**Start with standalone** config in `.claude/` for quick iteration. Convert to a plugin when you're ready to share.
+
+---
+
+## Step 2: Plugin Directory Structure
+
+```
+my-plugin/
+├── .claude-plugin/
+│   └── plugin.json          ← REQUIRED: plugin manifest
+├── skills/
+│   └── my-skill/
+│       └── SKILL.md         ← Skills (namespaced as /my-plugin:my-skill)
+├── commands/
+│   └── quick-cmd.md         ← Legacy commands format (also supported)
+├── agents/
+│   └── my-agent.md          ← Custom agents
+├── hooks/
+│   └── hooks.json           ← Hook configurations
+├── .mcp.json                ← MCP server configurations
+├── .lsp.json                ← LSP server configurations (optional)
+├── settings.json            ← Default settings when plugin is enabled
+└── README.md                ← Documentation
+```
+
+**CRITICAL:** `.claude-plugin/` only contains `plugin.json`. Everything else goes at the plugin root.
+
+---
+
+## Step 3: Create the Manifest
+
+**`.claude-plugin/plugin.json`:**
+
+```json
+{
+  "name": "my-plugin",
+  "description": "What this plugin does",
+  "version": "1.0.0",
+  "author": {
+    "name": "Your Name",
+    "email": "you@example.com"
+  },
+  "homepage": "https://github.com/you/my-plugin",
+  "repository": "https://github.com/you/my-plugin",
+  "license": "MIT"
+}
+```
+
+| Field | Required | Purpose |
+|-------|----------|---------|
+| `name` | Yes | Unique ID and skill namespace prefix. Lowercase, hyphens. |
+| `description` | Yes | Shown in plugin manager when browsing/installing. |
+| `version` | Yes | Semantic versioning (`1.0.0`). Increment for updates. |
+| `author` | No | Attribution info. |
+| `homepage` | No | Link to docs or landing page. |
+| `repository` | No | Source code URL. |
+| `license` | No | SPDX license identifier. |
+
+The `name` field becomes the namespace prefix for all skills: a skill named `review` in a plugin named `code-tools` becomes `/code-tools:review`.
+
+---
+
+## Step 4: Add Skills
+
+Skills in a plugin live in `skills/<skill-name>/SKILL.md`:
+
+```
+my-plugin/
+└── skills/
+    └── code-review/
+        └── SKILL.md
+```
+
+**`skills/code-review/SKILL.md`:**
+```yaml
+---
+name: code-review
+description: Reviews code for best practices. Use when reviewing code, checking PRs, or auditing quality.
+---
+
+# Code Review
+
+When reviewing code, check for:
+1. Security vulnerabilities
+2. Error handling completeness
+3. TypeScript type safety
+4. Test coverage
+
+...
+```
+
+After installing, use it as `/my-plugin:code-review`.
+
+Skills in plugins support all the same features as standalone skills: arguments (`$ARGUMENTS`), dynamic context (`!`cmd``), `context: fork`, `allowed-tools`, etc.
+
+---
+
+## Step 5: Add Agents
+
+Agents in plugins live in `agents/<name>.md` — exactly the same format as standalone agents:
+
+```
+my-plugin/
+└── agents/
+    └── security-reviewer.md
+```
+
+**`agents/security-reviewer.md`:**
+```yaml
+---
+name: security-reviewer
+description: Security expert. Use proactively when reviewing code changes for vulnerabilities.
+tools: Read, Grep, Glob, Bash
+model: sonnet
+---
+
+You are a security engineer specializing in web application security...
+```
+
+Agents are **not** namespaced like skills — they keep their plain `name`.
+
+---
+
+## Step 6: Add Hooks
+
+Hooks in plugins live in `hooks/hooks.json`:
+
+```
+my-plugin/
+└── hooks/
+    └── hooks.json
+```
+
+**`hooks/hooks.json`:**
+```json
+{
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": "Edit|Write",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "jq -r '.tool_input.file_path' | xargs npx prettier --write 2>/dev/null || true"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+Same format as `settings.json` hooks — just the `"hooks"` key and below.
+
+---
+
+## Step 7: Add MCP Servers
+
+MCP servers in plugins live in `.mcp.json` at the plugin root:
+
+```
+my-plugin/
+└── .mcp.json
+```
+
+**`.mcp.json`:**
+```json
+{
+  "mcpServers": {
+    "my-internal-api": {
+      "type": "stdio",
+      "command": "${CLAUDE_PLUGIN_ROOT}/servers/api-server",
+      "args": ["--config", "${CLAUDE_PLUGIN_ROOT}/config.json"],
+      "env": {
+        "API_URL": "${MY_API_URL}"
+      }
+    }
+  }
+}
+```
+
+- `${CLAUDE_PLUGIN_ROOT}` — resolved to the plugin's directory at runtime
+- MCP servers start automatically when the plugin is enabled (requires Claude Code restart to apply changes)
+- Supports `stdio`, `http`, and `sse` transport types
+
+---
+
+## Step 8: Add LSP Servers (Optional)
+
+LSP servers give Claude real-time code intelligence for languages not natively supported:
+
+**`.lsp.json`:**
+```json
+{
+  "go": {
+    "command": "gopls",
+    "args": ["serve"],
+    "extensionToLanguage": {
+      ".go": "go"
+    }
+  }
+}
+```
+
+Users need the LSP binary installed. For common languages (TypeScript, Python, Rust), use pre-built plugins from the marketplace instead.
+
+---
+
+## Step 9: Default Settings
+
+Ship default settings with your plugin via `settings.json` at the plugin root:
+
+```json
+{
+  "agent": "security-reviewer"
+}
+```
+
+Setting `agent` activates one of the plugin's custom agents as the default main thread. This changes how Claude Code behaves when the plugin is enabled. Currently only the `agent` key is supported here.
+
+---
+
+## Step 10: Test Locally
+
+Use `--plugin-dir` to load your plugin without installing:
+
+```bash
+# Load single plugin
+claude --plugin-dir ./my-plugin
+
+# Load multiple plugins
+claude --plugin-dir ./plugin-one --plugin-dir ./plugin-two
+
+# Inside Claude Code:
+/my-plugin:skill-name    # Test a skill
+/agents                  # Check agents appear
+/hooks                   # Verify hooks are registered
+/mcp                     # Check MCP servers
+```
+
+Changes to plugin files require restarting Claude Code to take effect.
+
+---
+
+## Step 11: Convert Existing Config to Plugin
+
+If you have skills/hooks in `.claude/`, convert them:
+
+```bash
+# Create plugin structure
+mkdir -p my-plugin/.claude-plugin
+
+# Create manifest
+cat > my-plugin/.claude-plugin/plugin.json << 'EOF'
+{
+  "name": "my-plugin",
+  "description": "Migrated from standalone configuration",
+  "version": "1.0.0"
+}
+EOF
+
+# Copy existing files
+cp -r .claude/skills my-plugin/      # If you have skills
+cp -r .claude/agents my-plugin/      # If you have agents
+cp -r .claude/commands my-plugin/    # If you have commands
+
+# Migrate hooks from settings.json → hooks/hooks.json
+mkdir my-plugin/hooks
+# Copy the "hooks" object from .claude/settings.json to hooks/hooks.json
+```
+
+**What changes after migration:**
+
+| Standalone | Plugin |
+|-----------|--------|
+| `/hello` | `/my-plugin:hello` |
+| `.claude/commands/` | `plugin/commands/` |
+| `.claude/settings.json` hooks | `plugin/hooks/hooks.json` |
+| Manual sharing | `claude plugin install` |
+
+---
+
+## Step 12: Distribute
+
+### Via URL/Git
+
+Users install with:
+```bash
+claude plugin install https://github.com/you/my-plugin
+```
+
+Or via marketplace if you submit to one:
+```bash
+/plugin install my-plugin  # From configured marketplace
+```
+
+### Submit to official marketplace
+
+1. Go to `claude.ai/settings/plugins/submit` or `platform.claude.com/plugins/submit`
+2. Fill out the submission form
+3. Once approved, users can install via `/plugin install plugin-name`
+
+### Via team marketplace
+
+Create a `marketplace.json` registry file and host it. Teams can point Claude Code to it:
+```bash
+claude plugin source add https://your-company.com/plugins/marketplace.json
+```
+
+---
+
+## Complete Plugin Example: Code Quality Toolkit
+
+```
+code-quality/
+├── .claude-plugin/
+│   └── plugin.json
+├── skills/
+│   ├── review/
+│   │   └── SKILL.md          # /code-quality:review
+│   └── refactor/
+│       └── SKILL.md          # /code-quality:refactor
+├── agents/
+│   └── code-reviewer.md      # Auto-review agent
+├── hooks/
+│   └── hooks.json            # Auto-format on save
+└── README.md
+```
+
+**`.claude-plugin/plugin.json`:**
+```json
+{
+  "name": "code-quality",
+  "description": "Code review, refactoring, and auto-formatting toolkit",
+  "version": "2.1.0",
+  "author": { "name": "GinStudio Team" },
+  "repository": "https://github.com/ginstudio/code-quality-plugin"
+}
+```
+
+**`hooks/hooks.json`:**
+```json
+{
+  "hooks": {
+    "PostToolUse": [{
+      "matcher": "Edit|Write",
+      "hooks": [{
+        "type": "command",
+        "command": "jq -r '.tool_input.file_path' | xargs npx prettier --write 2>/dev/null || true"
+      }]
+    }]
+  }
+}
+```
+
+**`agents/code-reviewer.md`:**
+```yaml
+---
+name: code-reviewer
+description: Expert code reviewer. Use proactively after any code changes.
+tools: Read, Grep, Glob, Bash
+model: sonnet
+memory: project
+---
+
+You are a senior code reviewer. After code changes, run git diff HEAD~1 and provide structured feedback by severity (CRITICAL/WARNING/SUGGESTION).
+```
+
+---
+
+## Checklist Before Publishing
+
+- [ ] `version` follows semver (`1.0.0`)
+- [ ] `description` clearly explains what the plugin does
+- [ ] Skills tested with `/plugin-name:skill-name`
+- [ ] Agents appear in `/agents`
+- [ ] Hooks fire correctly (test via `/hooks`)
+- [ ] MCP servers start up (check via `/mcp`)
+- [ ] `README.md` explains installation + usage
+- [ ] No secrets or credentials in plugin files
+- [ ] Plugin loads cleanly with `claude --plugin-dir ./my-plugin`

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

@@ -0,0 +1,262 @@
+# Tutorial: Sandboxing
+
+Claude Code's sandbox restricts what bash commands and their child processes can do at the **OS level** — independent of Claude's permission rules.
+
+---
+
+## Step 1: Understand How Sandboxing Works
+
+The sandbox adds OS-level enforcement ON TOP of Claude's permission system:
+
+| Layer | What it controls | How to configure |
+|-------|-----------------|-----------------|
+| **Permissions** | Which tools Claude can call | `.claude/settings.json` permissions |
+| **Sandbox** | What bash commands can access at OS level | `/sandbox` or `settings.json` sandbox config |
+
+Both layers run independently. A command can pass Claude's permission check but still be blocked by the sandbox if it tries to access a restricted path or network domain.
+
+### Platform Support
+
+| Platform | Implementation | Prerequisites |
+|----------|---------------|--------------|
+| macOS | Seatbelt (built-in) | None |
+| Linux / WSL2 | bubblewrap + socat | `sudo apt-get install bubblewrap socat` |
+| WSL1 | ❌ Not supported | Requires WSL2 kernel features |
+| Windows native | Planned | Not yet available |
+
+---
+
+## Step 2: Enable Sandboxing
+
+```bash
+# Toggle in the current session
+/sandbox
+```
+
+This opens a mode selection menu. Choose:
+
+1. **Auto-allow mode** — Sandboxed bash commands run automatically without prompts. Commands that can't be sandboxed fall through to normal permissions.
+2. **Regular permissions mode** — All commands still go through standard permission prompts, but are also sandboxed at OS level.
+
+Or enable permanently in `.claude/settings.json`:
+
+```json
+{
+  "sandbox": {
+    "enabled": true
+  }
+}
+```
+
+---
+
+## Step 3: Default Filesystem Behavior
+
+By default, sandboxed commands can:
+- **Read**: all of your filesystem EXCEPT explicitly denied directories
+- **Write**: ONLY the current working directory and subdirectories
+
+All restrictions apply to child processes too (kubectl, terraform, npm scripts, etc.).
+
+---
+
+## Step 4: Configure Filesystem Rules
+
+```json
+{
+  "sandbox": {
+    "filesystem": {
+      "allowWrite": ["//tmp/build", "~/.kube/cache"],
+      "denyWrite": ["/src/secrets/**"],
+      "denyRead": ["~/.ssh/", "~/.aws/credentials"]
+    }
+  }
+}
+```
+
+### Path Prefix Convention
+
+| Prefix | Meaning | Example |
+|--------|---------|---------|
+| `//` | Absolute filesystem path | `//tmp/build` → `/tmp/build` |
+| `~/` | Home directory | `~/.kube` → `$HOME/.kube` |
+| `/` | Relative to settings file directory | `/build` → `$SETTINGS_DIR/build` |
+| `./` or none | Relative, runtime-resolved | `./output` |
+
+**Arrays merge across config scopes.** If managed settings allow `//opt/company-tools` and you add `~/.kube`, both are active simultaneously.
+
+---
+
+## Step 5: Configure Network Rules
+
+By default, no network filtering. To restrict outbound access from bash commands:
+
+```json
+{
+  "sandbox": {
+    "network": {
+      "allowedDomains": [
+        "registry.npmjs.org",
+        "api.github.com",
+        "*.internal.company.com"
+      ],
+      "blockedDomains": ["*.social-media.com"]
+    }
+  }
+}
+```
+
+Network filtering works via a proxy running **outside** the sandbox — all subprocess traffic routes through it. When an unapproved domain is accessed:
+- Blocked at OS level
+- User gets immediate notification with options: deny, allow once, or permanently allow
+
+**Important distinction:**
+- `sandbox.network.allowedDomains` — controls what **bash commands** can reach
+- `WebFetch(domain:x)` permission rules — controls what Claude's **WebFetch tool** can access
+- These are completely separate controls
+
+### Custom Proxy
+
+For advanced logging, HTTPS inspection, or custom filtering:
+
+```json
+{
+  "sandbox": {
+    "network": {
+      "httpProxyPort": 8080,
+      "socksProxyPort": 8081
+    }
+  }
+}
+```
+
+---
+
+## Step 6: Exclude Specific Commands from Sandbox
+
+Some tools are incompatible with the sandbox. Run them outside it entirely:
+
+```json
+{
+  "sandbox": {
+    "excludedCommands": ["docker", "git"]
+  }
+}
+```
+
+**Known incompatibilities:**
+- `watchman` — incompatible with sandbox; use `jest --no-watchman` instead
+- `docker` — incompatible; add to `excludedCommands`
+
+---
+
+## Step 7: The Escape Hatch
+
+When a command fails due to sandbox restrictions, Claude can retry it with `dangerouslyDisableSandbox` — those retried commands bypass the sandbox and fall through to normal permission prompts.
+
+To disable this escape hatch entirely:
+
+```json
+{
+  "sandbox": {
+    "allowUnsandboxedCommands": false
+  }
+}
+```
+
+When set to `false`, `dangerouslyDisableSandbox` is completely ignored — useful for stricter enterprise environments.
+
+---
+
+## Step 8: Full Configuration Example
+
+```json
+{
+  "sandbox": {
+    "filesystem": {
+      "allowWrite": [
+        "//tmp/**",
+        "~/.npm/**",
+        "~/Library/Caches/**"
+      ],
+      "denyWrite": [
+        "~/.ssh/**",
+        "~/.aws/**",
+        "/etc/**"
+      ],
+      "denyRead": [
+        "~/.ssh/id_rsa",
+        "~/.aws/credentials"
+      ]
+    },
+    "network": {
+      "allowedDomains": [
+        "registry.npmjs.org",
+        "api.github.com",
+        "pypi.org",
+        "*.amazonaws.com"
+      ]
+    },
+    "excludedCommands": ["docker"],
+    "allowUnsandboxedCommands": false
+  }
+}
+```
+
+---
+
+## Step 9: Sandbox + Permissions — How They Interact
+
+| Tool | Permissions control | Sandbox applies? |
+|------|--------------------|--------------------|
+| `Read` tool | Yes — permission rules | No |
+| `Edit` / `Write` tool | Yes — permission rules | No |
+| `WebFetch` tool | Yes — `WebFetch(domain:x)` rules | No |
+| `Bash` command | Yes — permission rules | **Yes** — OS-level enforcement |
+| Bash child processes | Inherited from Bash | **Yes** — all child processes sandboxed |
+
+**Key insight:** `Edit`/`Read` deny rules and `sandbox.filesystem.denyRead`/`denyWrite` are **merged** — both apply simultaneously. So `Edit(.env)` deny in permissions blocks the Edit tool, while `denyWrite: [".env"]` in sandbox blocks any bash command that tries to write `.env`.
+
+---
+
+## Step 10: Security Limitations to Know
+
+1. **Network filtering does not inspect traffic content** — domain-level only; domain fronting may bypass it
+2. **Broad domains** — allowing `github.com` could theoretically enable data exfiltration via repository uploads
+3. **Unix sockets** — `allowUnixSockets` can grant sandbox bypass; allowing `/var/run/docker.sock` effectively grants host system access
+4. **Filesystem write permissions** — allowing writes to `$PATH` dirs or shell configs (`.bashrc`, `.zshrc`) enables privilege escalation
+5. **Weak nested sandbox** — `enableWeakerNestedSandbox: true` (for Docker environments without privileged namespaces) considerably weakens security
+
+### Linux / WSL2 inside Docker
+
+```json
+{
+  "sandbox": {
+    "enableWeakerNestedSandbox": true
+  }
+}
+```
+
+Only use when additional isolation is enforced externally (e.g., the Docker container itself is isolated).
+
+---
+
+## Quick Reference
+
+```bash
+# Enable/disable sandbox interactively
+/sandbox
+
+# Open source sandbox runtime (sandbox arbitrary programs, including MCP servers)
+npx @anthropic-ai/sandbox-runtime <command>
+
+# Install prerequisites on Linux/WSL2
+sudo apt-get install bubblewrap socat     # Ubuntu/Debian
+sudo dnf install bubblewrap socat         # Fedora
+```
+
+**Sandbox applies to:** Bash commands and all their child processes.
+
+**Sandbox does NOT apply to:** Read, Edit, Write, Glob, Grep, WebFetch, MCP tools.
+
+**Rule priority:** `denyRead` / `denyWrite` always win over `allowWrite`.

package/skills/ai-build-ai/scripts/load-tutorial.sh

@@ -0,0 +1,54 @@
+#!/bin/bash
+# load-tutorial.sh — Loads the right tutorial doc based on the topic argument.
+# Used by ai-build-ai SKILL.md via the !`command` dynamic context injection.
+#
+# Usage: load-tutorial.sh [topic]
+# Topics: skill | agent | mcp | headless | hooks | plugin | teams | memory | permissions | overview (default)
+
+SKILL_DIR="$(cd "$(dirname "$0")/.." && pwd)"
+TOPIC="${1:-overview}"
+
+# Normalize input: lowercase, strip leading /, trim spaces
+TOPIC=$(echo "$TOPIC" | tr '[:upper:]' '[:lower:]' | sed 's|^/||' | xargs)
+
+case "$TOPIC" in
+  skill|skills|create-skill|new-skill|add-skill|write-skill)
+    cat "$SKILL_DIR/docs/create-skill.md"
+    ;;
+  agent|agents|subagent|subagents|create-agent|new-agent|add-agent|custom-agent)
+    cat "$SKILL_DIR/docs/create-agent.md"
+    ;;
+  mcp|mcp-server|create-mcp|new-mcp|add-mcp|model-context-protocol|server)
+    cat "$SKILL_DIR/docs/create-mcp.md"
+    ;;
+  headless|headless-mode|programmatic|cli|sdk|agent-sdk|automation|script|ci|cicd|pipeline|github-actions|gitlab)
+    cat "$SKILL_DIR/docs/headless-mode.md"
+    ;;
+  hook|hooks|lifecycle|event|events|automation|pretooluse|posttooluse|sessionstart|stop)
+    cat "$SKILL_DIR/docs/hooks.md"
+    ;;
+  plugin|plugins|distribute|distribution|marketplace|package|publish)
+    cat "$SKILL_DIR/docs/plugins.md"
+    ;;
+  team|teams|agent-team|agent-teams|multi-agent|parallel|teammate|teammates)
+    cat "$SKILL_DIR/docs/agent-teams.md"
+    ;;
+  memory|claude-md|claudemd|rules|persistent|instructions|context|remember)
+    cat "$SKILL_DIR/docs/memory-claude-md.md"
+    ;;
+  permission|permissions|allow|deny|rule|rules|access|bypasspermissions)
+    cat "$SKILL_DIR/docs/permissions.md"
+    ;;
+  sandbox|sandboxing|isolat*|seatbelt|bubblewrap|filesystem|network-filter)
+    cat "$SKILL_DIR/docs/sandbox.md"
+    ;;
+  checkpoint|checkpointing|rewind|restore|fork|session|resume|undo)
+    cat "$SKILL_DIR/docs/checkpointing.md"
+    ;;
+  output-style|output-styles|style|styles|tone|explanatory|learning)
+    cat "$SKILL_DIR/docs/output-styles.md"
+    ;;
+  *)
+    cat "$SKILL_DIR/docs/overview.md"
+    ;;
+esac