ginskill-init 1.0.0

package/skills/ai-build-ai/docs/create-mcp.md

@@ -0,0 +1,395 @@
+# Tutorial: Connect MCP Servers
+
+The Model Context Protocol (MCP) gives Claude access to external tools, databases, APIs, and services. Once connected, Claude can use MCP tools naturally as part of any conversation.
+
+---
+
+## Step 1: Understand MCP Transport Types
+
+| Transport | When to Use | Example |
+|-----------|-------------|---------|
+| **HTTP** | Remote cloud services (recommended) | `https://mcp.sentry.dev/mcp` |
+| **SSE** | Legacy remote services (deprecated, prefer HTTP) | `https://mcp.asana.com/sse` |
+| **stdio** | Local processes, custom scripts, CLI tools | `npx -y @modelcontextprotocol/server-fs` |
+
+---
+
+## Step 2: Add a Remote HTTP MCP Server
+
+```bash
+# Basic
+claude mcp add --transport http <name> <url>
+
+# With auth header
+claude mcp add --transport http <name> <url> \
+  --header "Authorization: Bearer YOUR_TOKEN"
+
+# Real examples:
+claude mcp add --transport http github https://api.githubcopilot.com/mcp/
+claude mcp add --transport http sentry https://mcp.sentry.dev/mcp
+claude mcp add --transport http notion https://mcp.notion.com/mcp
+claude mcp add --transport http hubspot https://mcp.hubspot.com/anthropic
+```
+
+For servers requiring OAuth (like GitHub, Sentry), authenticate after adding:
+```bash
+# In Claude Code session:
+/mcp
+# → Select the server → Authenticate → Follow browser flow
+```
+
+---
+
+## Step 3: Add a Local stdio MCP Server
+
+```bash
+# Basic syntax — double dash separates claude's args from server command
+claude mcp add --transport stdio <name> -- <command> [args...]
+
+# With environment variables
+claude mcp add --transport stdio <name> \
+  --env API_KEY=your-key \
+  -- npx -y @package/mcp-server
+
+# Real examples:
+claude mcp add --transport stdio filesystem \
+  -- npx -y @modelcontextprotocol/server-filesystem /Users/abc/projects
+
+claude mcp add --transport stdio db \
+  -- npx -y @bytebase/dbhub \
+  --dsn "postgresql://user:pass@localhost:5432/mydb"
+
+claude mcp add --transport stdio airtable \
+  --env AIRTABLE_API_KEY=your_key \
+  -- npx -y airtable-mcp-server
+```
+
+**Important:** All flags (`--transport`, `--env`, `--scope`) MUST come BEFORE the server name. The `--` separates Claude's flags from the server's command.
+
+---
+
+## Step 4: Choose the Right Scope
+
+```bash
+# Local (default) — only you, only this project
+claude mcp add --transport http stripe https://mcp.stripe.com
+
+# Project — shared with team via .mcp.json (commit to git)
+claude mcp add --transport http github https://api.githubcopilot.com/mcp/ --scope project
+
+# User — all your projects, personal
+claude mcp add --transport http notion https://mcp.notion.com/mcp --scope user
+```
+
+**Where config is stored:**
+- Local & User: `~/.claude.json`
+- Project: `.mcp.json` in project root (commit this!)
+
+---
+
+## Step 5: The .mcp.json Format
+
+When using `--scope project`, Claude creates/updates `.mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "github": {
+      "type": "http",
+      "url": "https://api.githubcopilot.com/mcp/"
+    },
+    "sentry": {
+      "type": "http",
+      "url": "https://mcp.sentry.dev/mcp"
+    },
+    "local-db": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "@bytebase/dbhub", "--dsn", "${DB_URL}"],
+      "env": {
+        "CACHE_DIR": "/tmp/mcp-cache"
+      }
+    }
+  }
+}
+```
+
+**Environment variable expansion in .mcp.json:**
+- `${VAR}` — expands to env var value
+- `${VAR:-default}` — uses `default` if VAR not set
+
+```json
+{
+  "mcpServers": {
+    "api": {
+      "type": "http",
+      "url": "${API_BASE_URL:-https://api.example.com}/mcp",
+      "headers": {
+        "Authorization": "Bearer ${API_TOKEN}"
+      }
+    }
+  }
+}
+```
+
+---
+
+## Step 6: Manage Your Servers
+
+```bash
+# List all configured servers
+claude mcp list
+
+# Get details for a specific server
+claude mcp get github
+
+# Remove a server
+claude mcp remove github
+
+# Import from Claude Desktop (macOS/WSL only)
+claude mcp add-from-claude-desktop
+
+# Add from JSON config directly
+claude mcp add-json my-server '{"type":"http","url":"https://example.com/mcp"}'
+
+# Check status and authenticate in Claude Code
+/mcp
+```
+
+---
+
+## Step 7: Build Your Own MCP Server
+
+For custom integrations, build an MCP server using the official SDK.
+
+### Option A: Using Node.js (MCP TypeScript SDK)
+
+```bash
+npm install @modelcontextprotocol/sdk
+```
+
+```typescript
+// my-mcp-server.ts
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+} from "@modelcontextprotocol/sdk/types.js";
+
+const server = new Server(
+  { name: "my-server", version: "1.0.0" },
+  { capabilities: { tools: {} } }
+);
+
+// Register tools
+server.setRequestHandler(ListToolsRequestSchema, async () => ({
+  tools: [
+    {
+      name: "get_data",
+      description: "Fetch data from our internal API",
+      inputSchema: {
+        type: "object",
+        properties: {
+          query: { type: "string", description: "Search query" },
+          limit: { type: "number", description: "Max results", default: 10 },
+        },
+        required: ["query"],
+      },
+    },
+  ],
+}));
+
+// Handle tool calls
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  if (request.params.name === "get_data") {
+    const { query, limit = 10 } = request.params.arguments as {
+      query: string;
+      limit?: number;
+    };
+
+    // Your implementation here
+    const results = await fetchFromAPI(query, limit);
+
+    return {
+      content: [{ type: "text", text: JSON.stringify(results, null, 2) }],
+    };
+  }
+  throw new Error(`Unknown tool: ${request.params.name}`);
+});
+
+// Start the server
+const transport = new StdioServerTransport();
+await server.connect(transport);
+```
+
+Register it:
+```bash
+claude mcp add --transport stdio my-server -- node my-mcp-server.js
+```
+
+### Option B: Using Python (MCP Python SDK)
+
+```bash
+pip install mcp
+```
+
+```python
+# my_server.py
+from mcp.server import Server
+from mcp.server.stdio import stdio_server
+from mcp.types import Tool, TextContent
+import json
+
+app = Server("my-server")
+
+@app.list_tools()
+async def list_tools() -> list[Tool]:
+    return [
+        Tool(
+            name="search_database",
+            description="Search the company database",
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "query": {"type": "string"},
+                    "table": {"type": "string", "enum": ["users", "orders", "products"]},
+                },
+                "required": ["query", "table"],
+            },
+        )
+    ]
+
+@app.call_tool()
+async def call_tool(name: str, arguments: dict) -> list[TextContent]:
+    if name == "search_database":
+        results = await query_db(arguments["query"], arguments["table"])
+        return [TextContent(type="text", text=json.dumps(results))]
+    raise ValueError(f"Unknown tool: {name}")
+
+async def main():
+    async with stdio_server() as (read_stream, write_stream):
+        await app.run(read_stream, write_stream, app.create_initialization_options())
+
+if __name__ == "__main__":
+    import asyncio
+    asyncio.run(main())
+```
+
+Register it:
+```bash
+claude mcp add --transport stdio my-db-server -- python my_server.py
+```
+
+### Option C: HTTP Server (for remote access)
+
+For a server that multiple users can access:
+
+```typescript
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import express from "express";
+
+const app = express();
+
+app.post("/mcp", async (req, res) => {
+  const server = new Server({ name: "my-server", version: "1.0.0" }, { capabilities: { tools: {} } });
+  // ... register tools ...
+
+  const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: undefined });
+  await server.connect(transport);
+  await transport.handleRequest(req, res, req.body);
+});
+
+app.listen(3000);
+```
+
+Register it:
+```bash
+claude mcp add --transport http my-server http://localhost:3000/mcp
+```
+
+---
+
+## Step 8: MCP Resources (@ mentions)
+
+MCP servers can expose resources accessible via `@mention`:
+
+```
+# In Claude Code conversation:
+@github:issue://123      ← Reference a GitHub issue
+@docs:file://api/auth    ← Reference a doc page
+@postgres:schema://users ← Reference a DB schema
+```
+
+Resources are automatically fetched when mentioned. Use `@` to see available resources from connected servers.
+
+---
+
+## Step 9: Include MCP in a Subagent
+
+Give specific MCP servers to a subagent:
+
+```yaml
+---
+name: github-agent
+description: Handle GitHub operations. Reads issues, creates PRs, checks CI.
+mcpServers:
+  - github                    # Reference already-configured server by name
+  - name: slack               # Or inline definition
+    type: http
+    url: https://mcp.slack.com/mcp
+tools: Read, Grep
+model: sonnet
+---
+
+You are a GitHub workflow specialist. When invoked:
+1. Check the current PR status
+2. Review any failing CI checks
+3. Respond to review comments
+4. Update PR description if needed
+```
+
+---
+
+## Popular MCP Servers Quick Reference
+
+```bash
+# GitHub — issues, PRs, code search
+claude mcp add --transport http github https://api.githubcopilot.com/mcp/
+
+# Sentry — error monitoring
+claude mcp add --transport http sentry https://mcp.sentry.dev/mcp
+
+# Notion — docs and pages
+claude mcp add --transport http notion https://mcp.notion.com/mcp
+
+# Slack — channels and messages (use /mcp to auth)
+claude mcp add --transport http slack https://mcp.slack.com/mcp
+
+# PostgreSQL database
+claude mcp add --transport stdio postgres \
+  -- npx -y @bytebase/dbhub \
+  --dsn "postgresql://user:pass@localhost:5432/mydb"
+
+# Local filesystem
+claude mcp add --transport stdio filesystem \
+  -- npx -y @modelcontextprotocol/server-filesystem /path/to/allow
+
+# Playwright browser automation
+claude mcp add --transport stdio playwright \
+  -- npx -y @playwright/mcp@latest
+```
+
+---
+
+## Troubleshooting
+
+| Problem | Solution |
+|---------|----------|
+| "Connection closed" on Windows | Wrap with `cmd /c`: `-- cmd /c npx -y package` |
+| Server not showing up | Run `/mcp` to check status |
+| OAuth flow fails | Use "Clear authentication" in `/mcp` and retry |
+| Large MCP output truncated | Set `MAX_MCP_OUTPUT_TOKENS=50000` env var |
+| Too many tools consuming context | `ENABLE_TOOL_SEARCH=auto` (default) or `=true` |
+| Server requires specific startup time | Set `MCP_TIMEOUT=30000` (30 seconds) |

package/skills/ai-build-ai/docs/create-skill.md

@@ -0,0 +1,299 @@
+# Tutorial: Create a New Skill
+
+A skill is a `SKILL.md` file (plus optional supporting files) that teaches Claude a reusable workflow, domain knowledge, or set of instructions. Claude auto-invokes skills when relevant, or users trigger them with `/skill-name`.
+
+---
+
+## Step 1: Understand the Structure
+
+```
+.claude/skills/<skill-name>/       ← project-level (committed to git)
+~/.claude/skills/<skill-name>/     ← personal (all projects)
+ginstudio-skills/skills/<name>/    ← this repo's plugin skills
+  ├── SKILL.md                     ← REQUIRED: instructions + frontmatter
+  ├── docs/                        ← optional: reference docs loaded on demand
+  │   └── reference.md
+  ├── scripts/                     ← optional: executable helpers
+  │   └── helper.sh
+  └── evals/
+      └── evals.json               ← optional: test cases
+```
+
+Keep `SKILL.md` under 500 lines. Move detailed references to `docs/` files and link to them.
+
+---
+
+## Step 2: Write SKILL.md
+
+Every skill needs two parts: **YAML frontmatter** (configuration) and **markdown content** (instructions).
+
+### Full Frontmatter Reference
+
+```yaml
+---
+name: my-skill                    # Becomes the /slash-command. Lowercase, hyphens only.
+description: |                    # CRITICAL: Claude reads this to decide when to use the skill.
+  **Short bold summary**: One sentence description.
+  - MANDATORY TRIGGERS: keyword1, keyword2, phrase one, phrase two
+  - Use this skill when... (describe context, not just keywords)
+
+# Optional fields:
+disable-model-invocation: true    # Only YOU can invoke (not Claude). Use for /deploy, /commit.
+user-invocable: false             # Only CLAUDE can invoke (hide from / menu). Use for background knowledge.
+allowed-tools: Read, Grep, Glob   # Tools auto-approved when this skill is active.
+model: sonnet                     # Force a model: sonnet | opus | haiku
+context: fork                     # Run in isolated subagent context (won't see conversation history)
+agent: Explore                    # Which agent type when context: fork. Built-ins: Explore, Plan, general-purpose
+argument-hint: "[topic]"          # Shown in autocomplete. Example: "[issue-number] [format]"
+---
+```
+
+### Invocation Control Matrix
+
+| Frontmatter | You can invoke | Claude can invoke | When loaded |
+|-------------|---------------|-------------------|-------------|
+| (default) | ✅ | ✅ | Description always in context, full skill loads on invocation |
+| `disable-model-invocation: true` | ✅ | ❌ | Description NOT in context, loads only when you invoke |
+| `user-invocable: false` | ❌ | ✅ | Description always in context, full skill loads on invocation |
+
+---
+
+## Step 3: Write the Instructions
+
+After the frontmatter, write clear markdown instructions. Think about what type of skill this is:
+
+### Type A: Task Skill (do-this workflow)
+
+For repeatable procedures — code review, deployment, PR creation:
+
+```markdown
+---
+name: create-pr
+description: Create a pull request with proper format. MANDATORY TRIGGERS: create PR, open PR, make PR.
+disable-model-invocation: true
+allowed-tools: Bash(gh *)
+---
+
+# Create Pull Request
+
+1. Run `git status` and `git diff main...HEAD` to understand changes
+2. Write a clear PR title (under 70 chars, imperative mood)
+3. Create PR body with Summary + Test Plan sections
+4. Run: `gh pr create --title "..." --body "..."`
+5. Return the PR URL
+```
+
+### Type B: Knowledge Skill (apply-these-rules)
+
+For domain knowledge Claude should apply inline (not a task to run):
+
+```markdown
+---
+name: api-conventions
+description: API design patterns for this codebase. Apply when writing API endpoints.
+user-invocable: false
+---
+
+# API Conventions
+
+When writing API endpoints in this project:
+- Use RESTful naming: GET /users/:id, POST /users, PATCH /users/:id
+- Always return { data, meta } shape for lists, { data } for single items
+- Error format: { error: { code, message, details } }
+- Use Zod for request validation, class-transformer for response shaping
+```
+
+### Type C: Research Skill (explore in isolation)
+
+For research that should run in a separate context:
+
+```markdown
+---
+name: deep-research
+description: Thoroughly research a topic in the codebase.
+context: fork
+agent: Explore
+---
+
+Research "$ARGUMENTS" thoroughly:
+
+1. Use Glob to find relevant files
+2. Use Grep to search for usages
+3. Read and analyze the key files
+4. Return a structured summary with file:line references
+```
+
+---
+
+## Step 4: Arguments
+
+Skills can accept arguments via `$ARGUMENTS` (all args) or `$N` (positional):
+
+```yaml
+---
+name: fix-issue
+description: Fix a GitHub issue by number. MANDATORY TRIGGERS: fix issue, implement issue.
+disable-model-invocation: true
+argument-hint: "[issue-number]"
+allowed-tools: Bash(gh *), Read, Edit, Grep
+---
+
+Fix GitHub issue #$ARGUMENTS:
+
+1. Run `gh issue view $ARGUMENTS` to read the requirements
+2. Understand what needs to be implemented
+3. Find the relevant files using Grep/Glob
+4. Implement the fix following project conventions
+5. Write or update tests
+6. Create a commit with "fix: resolve issue #$ARGUMENTS"
+```
+
+**Positional args** (`$0`, `$1`, `$2` or `$ARGUMENTS[0]`, `$ARGUMENTS[1]`):
+
+```yaml
+---
+name: migrate
+description: Migrate a component between frameworks.
+argument-hint: "[component] [from-framework] [to-framework]"
+---
+
+Migrate the $0 component from $1 to $2.
+Preserve all existing behavior, props API, and tests.
+```
+
+Run as: `/migrate SearchBar React Vue`
+
+---
+
+## Step 5: Dynamic Context Injection
+
+Use `!`command`` to run shell commands BEFORE Claude sees the skill content. The output replaces the placeholder inline — this is preprocessing, not something Claude executes.
+
+```yaml
+---
+name: pr-review
+description: Review the current pull request.
+context: fork
+agent: Explore
+allowed-tools: Bash(gh *)
+---
+
+## Pull Request Context
+- Diff: !`gh pr diff`
+- Comments: !`gh pr view --comments`
+- Changed files: !`gh pr diff --name-only`
+- CI status: !`gh pr checks`
+
+## Your Task
+Review this pull request. Focus on:
+1. Correctness — does it do what the description says?
+2. Code quality — follows project conventions?
+3. Tests — are they sufficient?
+4. Security — any vulnerabilities?
+
+Provide structured feedback grouped by severity.
+```
+
+Other useful shell injections:
+```bash
+!`cat package.json | jq '.version'`          # Project version
+!`git log --oneline -10`                      # Recent commits
+!`git diff --stat HEAD~1`                     # Last change summary
+!`node --version && npm --version`            # Environment info
+```
+
+---
+
+## Step 6: Supporting Files
+
+For complex skills, split content into multiple files. Reference them from `SKILL.md`:
+
+**SKILL.md:**
+```markdown
+## Additional Resources
+
+Read these files when you need deeper detail:
+- `docs/api-reference.md` — Full API parameter reference (read when generating API calls)
+- `docs/examples.md` — Real-world examples (read when unsure about format)
+- `scripts/validate.sh` — Run this to validate generated output
+```
+
+**docs/api-reference.md** (only loaded when Claude needs it, keeps SKILL.md lean):
+```markdown
+# API Parameter Reference
+## POST /api/v1/jobs/createTask
+...detailed params...
+```
+
+---
+
+## Step 7: Evals (Optional but Recommended)
+
+Add test cases to verify the skill works correctly:
+
+**evals/evals.json:**
+```json
+[
+  {
+    "prompt": "Review my recent code changes",
+    "expected_skill": "review-code",
+    "notes": "Should trigger on code review requests"
+  },
+  {
+    "prompt": "/my-skill some-argument",
+    "expected_behavior": "Describes what the skill should do with this input"
+  }
+]
+```
+
+---
+
+## Complete Example: The `ai-asset-generator` Pattern
+
+This project's `ai-asset-generator` skill shows the best-in-class pattern:
+
+```
+ai-asset-generator/
+├── SKILL.md           ← Overview, quick start, key patterns (under 300 lines)
+├── docs/
+│   ├── gen-image.md   ← Full API reference for image generation
+│   ├── genvideo.md    ← Full API reference for video generation
+│   └── remove-background.md
+├── lib/               ← Shared JS libraries (not loaded, executed)
+│   ├── kie-client.mjs
+│   └── bg-remove.mjs
+└── scripts/
+    └── scaffold-generator.mjs
+```
+
+Key design decisions:
+1. **SKILL.md stays lean** — overview, patterns, entry points only
+2. **Docs are lazy-loaded** — Claude reads them when it needs specific API details
+3. **Scripts do the heavy work** — Claude orchestrates, scripts execute
+4. **Clear output destinations** — explicit about where generated files go
+
+---
+
+## Checklist Before Publishing
+
+- [ ] `name` is lowercase with hyphens only (no spaces, no underscores)
+- [ ] `description` contains trigger keywords users would naturally say
+- [ ] SKILL.md is under 500 lines (move extras to `docs/`)
+- [ ] References to supporting files are explicit ("read `docs/api.md` when you need X")
+- [ ] If side effects: `disable-model-invocation: true` is set
+- [ ] If background knowledge: `user-invocable: false` is set
+- [ ] Tested with `/skill-name` directly
+- [ ] Tested that Claude auto-invokes it with natural language
+
+---
+
+## Common Mistakes
+
+| Mistake | Fix |
+|---------|-----|
+| Description too vague | Add specific trigger phrases, use MANDATORY TRIGGERS format |
+| Skill too large (>500 lines) | Split into SKILL.md + docs/*.md |
+| Forgot `disable-model-invocation: true` | Claude will run deploys automatically! |
+| No `$ARGUMENTS` but users pass args | Args get appended as `ARGUMENTS: value` at end — works but not ideal |
+| Using `context: fork` for knowledge skills | Fork = isolated subagent, won't see conversation. Use only for task skills |
+| Hardcoded paths | Use script to detect paths dynamically, or use relative paths |