{"owner":"shareAI-lab","repo":"learn-claude-code","hasSkills":true,"totalSkillsCount":5,"totalTokensCount":5745,"categories":["anthropic-skill"],"hasMcp":true,"mcpConfig":{"mcpServers":{"learn-claude-code":{"command":"npx","args":["-y","@modelcontextprotocol/server-learn-claude-code"]}}},"found":["skills/agent-builder/SKILL.md","skills/pdf/SKILL.md","skills/code-review/SKILL.md","skills/mcp-builder/SKILL.md","skills/agent-builder/references/agent-philosophy.md"],"skills":{"skills/agent-builder/SKILL.md":"---\nname: agent-builder\ndescription: |\n  Design and build AI agents for any domain. Use when users:\n  (1) ask to \"create an agent\", \"build an assistant\", or \"design an AI system\"\n  (2) want to understand agent architecture, agentic patterns, or autonomous AI\n  (3) need help with capabilities, subagents, planning, or skill mechanisms\n  (4) ask about Claude Code, Cursor, or similar agent internals\n  (5) want to build agents for business, research, creative, or operational tasks\n  Keywords: agent, assistant, autonomous, workflow, tool use, multi-step, orchestration\n---\n\n# Agent Builder\n\nBuild AI agents for any domain - customer service, research, operations, creative work, or specialized business processes.\n\n## The Core Philosophy\n\n> **The model already knows how to be an agent. Your job is to get out of the way.**\n\nAn agent is not complex engineering. It's a simple loop that invites the model to act:\n\n```\nLOOP:\n  Model sees: context + available capabilities\n  Model decides: act or respond\n  If act: execute capability, add result, continue\n  If respond: return to user\n```\n\n**That's it.** The magic isn't in the code - it's in the model. Your code just provides the opportunity.\n\n## The Three Elements\n\n### 1. Capabilities (What can it DO?)\n\nAtomic actions the agent can perform: search, read, create, send, query, modify.\n\n**Design principle**: Start with 3-5 capabilities. Add more only when the agent consistently fails because a capability is missing.\n\n### 2. Knowledge (What does it KNOW?)\n\nDomain expertise injected on-demand: policies, workflows, best practices, schemas.\n\n**Design principle**: Make knowledge available, not mandatory. Load it when relevant, not upfront.\n\n### 3. Context (What has happened?)\n\nThe conversation history - the thread connecting actions into coherent behavior.\n\n**Design principle**: Context is precious. Isolate noisy subtasks. Truncate verbose outputs. Protect clarity.\n\n## Agent Design Thinking\n\nBefore building, understand:\n\n- **Purpose**: What should this agent accomplish?\n- **Domain**: What world does it operate in? (customer service, research, operations, creative...)\n- **Capabilities**: What 3-5 actions are essential?\n- **Knowledge**: What expertise does it need access to?\n- **Trust**: What decisions can you delegate to the model?\n\n**CRITICAL**: Trust the model. Don't over-engineer. Don't pre-specify workflows. Give it capabilities and let it reason.\n\n## Progressive Complexity\n\nStart simple. Add complexity only when real usage reveals the need:\n\n| Level | What to add | When to add it |\n|-------|-------------|----------------|\n| Basic | 3-5 capabilities | Always start here |\n| Planning | Progress tracking | Multi-step tasks lose coherence |\n| Subagents | Isolated child agents | Exploration pollutes context |\n| Skills | On-demand knowledge | Domain expertise needed |\n\n**Most agents never need to go beyond Level 2.**\n\n## Domain Examples\n\n**Business**: CRM queries, email, calendar, approvals\n**Research**: Database search, document analysis, citations\n**Operations**: Monitoring, tickets, notifications, escalation\n**Creative**: Asset generation, editing, collaboration, review\n\nThe pattern is universal. Only the capabilities change.\n\n## Key Principles\n\n1. **The model IS the agent** - Code just runs the loop\n2. **Capabilities enable** - What it CAN do\n3. **Knowledge informs** - What it KNOWS how to do\n4. **Constraints focus** - Limits create clarity\n5. **Trust liberates** - Let the model reason\n6. **Iteration reveals** - Start minimal, evolve from usage\n\n## Anti-Patterns\n\n| Pattern | Problem | Solution |\n|---------|---------|----------|\n| Over-engineering | Complexity before need | Start simple |\n| Too many capabilities | Model confusion | 3-5 to start |\n| Rigid workflows | Can't adapt | Let model decide |\n| Front-loaded knowledge | Context bloat | Load on-demand |\n| Micromanagement | Undercuts intelligence | Trust the model |\n\n## Resources\n\n**Philosophy & Theory**:\n- `references/agent-philosophy.md` - Deep dive into why agents work\n\n**Implementation**:\n- `references/minimal-agent.py` - Complete working agent (~80 lines)\n- `references/tool-templates.py` - Capability definitions\n- `references/subagent-pattern.py` - Context isolation\n\n**Scaffolding**:\n- `scripts/init_agent.py` - Generate new agent projects\n\n## The Agent Mindset\n\n**From**: \"How do I make the system do X?\"\n**To**: \"How do I enable the model to do X?\"\n\n**From**: \"What's the workflow for this task?\"\n**To**: \"What capabilities would help accomplish this?\"\n\nThe best agent code is almost boring. Simple loops. Clear capabilities. Clean context. The magic isn't in the code.\n\n**Give the model capabilities and knowledge. Trust it to figure out the rest.**\n","skills/pdf/SKILL.md":"---\nname: pdf\ndescription: Process PDF files - extract text, create PDFs, merge documents. Use when user asks to read PDF, create PDF, or work with PDF files.\n---\n\n# PDF Processing Skill\n\nYou now have expertise in PDF manipulation. Follow these workflows:\n\n## Reading PDFs\n\n**Option 1: Quick text extraction (preferred)**\n```bash\n# Using pdftotext (poppler-utils)\npdftotext input.pdf -  # Output to stdout\npdftotext input.pdf output.txt  # Output to file\n\n# If pdftotext not available, try:\npython3 -c \"\nimport fitz  # PyMuPDF\ndoc = fitz.open('input.pdf')\nfor page in doc:\n    print(page.get_text())\n\"\n```\n\n**Option 2: Page-by-page with metadata**\n```python\nimport fitz  # pip install pymupdf\n\ndoc = fitz.open(\"input.pdf\")\nprint(f\"Pages: {len(doc)}\")\nprint(f\"Metadata: {doc.metadata}\")\n\nfor i, page in enumerate(doc):\n    text = page.get_text()\n    print(f\"--- Page {i+1} ---\")\n    print(text)\n```\n\n## Creating PDFs\n\n**Option 1: From Markdown (recommended)**\n```bash\n# Using pandoc\npandoc input.md -o output.pdf\n\n# With custom styling\npandoc input.md -o output.pdf --pdf-engine=xelatex -V geometry:margin=1in\n```\n\n**Option 2: Programmatically**\n```python\nfrom reportlab.lib.pagesizes import letter\nfrom reportlab.pdfgen import canvas\n\nc = canvas.Canvas(\"output.pdf\", pagesize=letter)\nc.drawString(100, 750, \"Hello, PDF!\")\nc.save()\n```\n\n**Option 3: From HTML**\n```bash\n# Using wkhtmltopdf\nwkhtmltopdf input.html output.pdf\n\n# Or with Python\npython3 -c \"\nimport pdfkit\npdfkit.from_file('input.html', 'output.pdf')\n\"\n```\n\n## Merging PDFs\n\n```python\nimport fitz\n\nresult = fitz.open()\nfor pdf_path in [\"file1.pdf\", \"file2.pdf\", \"file3.pdf\"]:\n    doc = fitz.open(pdf_path)\n    result.insert_pdf(doc)\nresult.save(\"merged.pdf\")\n```\n\n## Splitting PDFs\n\n```python\nimport fitz\n\ndoc = fitz.open(\"input.pdf\")\nfor i in range(len(doc)):\n    single = fitz.open()\n    single.insert_pdf(doc, from_page=i, to_page=i)\n    single.save(f\"page_{i+1}.pdf\")\n```\n\n## Key Libraries\n\n| Task | Library | Install |\n|------|---------|---------|\n| Read/Write/Merge | PyMuPDF | `pip install pymupdf` |\n| Create from scratch | ReportLab | `pip install reportlab` |\n| HTML to PDF | pdfkit | `pip install pdfkit` + wkhtmltopdf |\n| Text extraction | pdftotext | `brew install poppler` / `apt install poppler-utils` |\n\n## Best Practices\n\n1. **Always check if tools are installed** before using them\n2. **Handle encoding issues** - PDFs may contain various character encodings\n3. **Large PDFs**: Process page by page to avoid memory issues\n4. **OCR for scanned PDFs**: Use `pytesseract` if text extraction returns empty\n","skills/code-review/SKILL.md":"---\nname: code-review\ndescription: Perform thorough code reviews with security, performance, and maintainability analysis. Use when user asks to review code, check for bugs, or audit a codebase.\n---\n\n# Code Review Skill\n\nYou now have expertise in conducting comprehensive code reviews. Follow this structured approach:\n\n## Review Checklist\n\n### 1. Security (Critical)\n\nCheck for:\n- [ ] **Injection vulnerabilities**: SQL, command, XSS, template injection\n- [ ] **Authentication issues**: Hardcoded credentials, weak auth\n- [ ] **Authorization flaws**: Missing access controls, IDOR\n- [ ] **Data exposure**: Sensitive data in logs, error messages\n- [ ] **Cryptography**: Weak algorithms, improper key management\n- [ ] **Dependencies**: Known vulnerabilities (check with `npm audit`, `pip-audit`)\n\n```bash\n# Quick security scans\nnpm audit                    # Node.js\npip-audit                    # Python\ncargo audit                  # Rust\ngrep -r \"password\\|secret\\|api_key\" --include=\"*.py\" --include=\"*.js\"\n```\n\n### 2. Correctness\n\nCheck for:\n- [ ] **Logic errors**: Off-by-one, null handling, edge cases\n- [ ] **Race conditions**: Concurrent access without synchronization\n- [ ] **Resource leaks**: Unclosed files, connections, memory\n- [ ] **Error handling**: Swallowed exceptions, missing error paths\n- [ ] **Type safety**: Implicit conversions, any types\n\n### 3. Performance\n\nCheck for:\n- [ ] **N+1 queries**: Database calls in loops\n- [ ] **Memory issues**: Large allocations, retained references\n- [ ] **Blocking operations**: Sync I/O in async code\n- [ ] **Inefficient algorithms**: O(n^2) when O(n) possible\n- [ ] **Missing caching**: Repeated expensive computations\n\n### 4. Maintainability\n\nCheck for:\n- [ ] **Naming**: Clear, consistent, descriptive\n- [ ] **Complexity**: Functions > 50 lines, deep nesting > 3 levels\n- [ ] **Duplication**: Copy-pasted code blocks\n- [ ] **Dead code**: Unused imports, unreachable branches\n- [ ] **Comments**: Outdated, redundant, or missing where needed\n\n### 5. Testing\n\nCheck for:\n- [ ] **Coverage**: Critical paths tested\n- [ ] **Edge cases**: Null, empty, boundary values\n- [ ] **Mocking**: External dependencies isolated\n- [ ] **Assertions**: Meaningful, specific checks\n\n## Review Output Format\n\n```markdown\n## Code Review: [file/component name]\n\n### Summary\n[1-2 sentence overview]\n\n### Critical Issues\n1. **[Issue]** (line X): [Description]\n   - Impact: [What could go wrong]\n   - Fix: [Suggested solution]\n\n### Improvements\n1. **[Suggestion]** (line X): [Description]\n\n### Positive Notes\n- [What was done well]\n\n### Verdict\n[ ] Ready to merge\n[ ] Needs minor changes\n[ ] Needs major revision\n```\n\n## Common Patterns to Flag\n\n### Python\n```python\n# Bad: SQL injection\ncursor.execute(f\"SELECT * FROM users WHERE id = {user_id}\")\n# Good:\ncursor.execute(\"SELECT * FROM users WHERE id = ?\", (user_id,))\n\n# Bad: Command injection\nos.system(f\"ls {user_input}\")\n# Good:\nsubprocess.run([\"ls\", user_input], check=True)\n\n# Bad: Mutable default argument\ndef append(item, lst=[]):  # Bug: shared mutable default\n# Good:\ndef append(item, lst=None):\n    lst = lst or []\n```\n\n### JavaScript/TypeScript\n```javascript\n// Bad: Prototype pollution\nObject.assign(target, userInput)\n// Good:\nObject.assign(target, sanitize(userInput))\n\n// Bad: eval usage\neval(userCode)\n// Good: Never use eval with user input\n\n// Bad: Callback hell\ngetData(x => process(x, y => save(y, z => done(z))))\n// Good:\nconst data = await getData();\nconst processed = await process(data);\nawait save(processed);\n```\n\n## Review Commands\n\n```bash\n# Show recent changes\ngit diff HEAD~5 --stat\ngit log --oneline -10\n\n# Find potential issues\ngrep -rn \"TODO\\|FIXME\\|HACK\\|XXX\" .\ngrep -rn \"password\\|secret\\|token\" . --include=\"*.py\"\n\n# Check complexity (Python)\npip install radon && radon cc . -a\n\n# Check dependencies\nnpm outdated  # Node\npip list --outdated  # Python\n```\n\n## Review Workflow\n\n1. **Understand context**: Read PR description, linked issues\n2. **Run the code**: Build, test, run locally if possible\n3. **Read top-down**: Start with main entry points\n4. **Check tests**: Are changes tested? Do tests pass?\n5. **Security scan**: Run automated tools\n6. **Manual review**: Use checklist above\n7. **Write feedback**: Be specific, suggest fixes, be kind\n","skills/mcp-builder/SKILL.md":"---\nname: mcp-builder\ndescription: Build MCP (Model Context Protocol) servers that give Claude new capabilities. Use when user wants to create an MCP server, add tools to Claude, or integrate external services.\n---\n\n# MCP Server Building Skill\n\nYou now have expertise in building MCP (Model Context Protocol) servers. MCP enables Claude to interact with external services through a standardized protocol.\n\n## What is MCP?\n\nMCP servers expose:\n- **Tools**: Functions Claude can call (like API endpoints)\n- **Resources**: Data Claude can read (like files or database records)\n- **Prompts**: Pre-built prompt templates\n\n## Quick Start: Python MCP Server\n\n### 1. Project Setup\n\n```bash\n# Create project\nmkdir my-mcp-server && cd my-mcp-server\npython3 -m venv venv && source venv/bin/activate\n\n# Install MCP SDK\npip install mcp\n```\n\n### 2. Basic Server Template\n\n```python\n#!/usr/bin/env python3\n\"\"\"my_server.py - A simple MCP server\"\"\"\n\nfrom mcp.server import Server\nfrom mcp.server.stdio import stdio_server\nfrom mcp.types import Tool, TextContent\n\n# Create server instance\nserver = Server(\"my-server\")\n\n# Define a tool\n@server.tool()\nasync def hello(name: str) -> str:\n    \"\"\"Say hello to someone.\n\n    Args:\n        name: The name to greet\n    \"\"\"\n    return f\"Hello, {name}!\"\n\n@server.tool()\nasync def add_numbers(a: int, b: int) -> str:\n    \"\"\"Add two numbers together.\n\n    Args:\n        a: First number\n        b: Second number\n    \"\"\"\n    return str(a + b)\n\n# Run server\nasync def main():\n    async with stdio_server() as (read, write):\n        await server.run(read, write)\n\nif __name__ == \"__main__\":\n    import asyncio\n    asyncio.run(main())\n```\n\n### 3. Register with Claude\n\nAdd to `~/.claude/mcp.json`:\n```json\n{\n  \"mcpServers\": {\n    \"my-server\": {\n      \"command\": \"python3\",\n      \"args\": [\"/path/to/my_server.py\"]\n    }\n  }\n}\n```\n\n## TypeScript MCP Server\n\n### 1. Setup\n\n```bash\nmkdir my-mcp-server && cd my-mcp-server\nnpm init -y\nnpm install @modelcontextprotocol/sdk\n```\n\n### 2. Template\n\n```typescript\n// src/index.ts\nimport { Server } from \"@modelcontextprotocol/sdk/server/index.js\";\nimport { StdioServerTransport } from \"@modelcontextprotocol/sdk/server/stdio.js\";\n\nconst server = new Server({\n  name: \"my-server\",\n  version: \"1.0.0\",\n});\n\n// Define tools\nserver.setRequestHandler(\"tools/list\", async () => ({\n  tools: [\n    {\n      name: \"hello\",\n      description: \"Say hello to someone\",\n      inputSchema: {\n        type: \"object\",\n        properties: {\n          name: { type: \"string\", description: \"Name to greet\" },\n        },\n        required: [\"name\"],\n      },\n    },\n  ],\n}));\n\nserver.setRequestHandler(\"tools/call\", async (request) => {\n  if (request.params.name === \"hello\") {\n    const name = request.params.arguments.name;\n    return { content: [{ type: \"text\", text: `Hello, ${name}!` }] };\n  }\n  throw new Error(\"Unknown tool\");\n});\n\n// Start server\nconst transport = new StdioServerTransport();\nserver.connect(transport);\n```\n\n## Advanced Patterns\n\n### External API Integration\n\n```python\nimport httpx\nfrom mcp.server import Server\n\nserver = Server(\"weather-server\")\n\n@server.tool()\nasync def get_weather(city: str) -> str:\n    \"\"\"Get current weather for a city.\"\"\"\n    async with httpx.AsyncClient() as client:\n        resp = await client.get(\n            f\"https://api.weatherapi.com/v1/current.json\",\n            params={\"key\": \"YOUR_API_KEY\", \"q\": city}\n        )\n        data = resp.json()\n        return f\"{city}: {data['current']['temp_c']}C, {data['current']['condition']['text']}\"\n```\n\n### Database Access\n\n```python\nimport sqlite3\nfrom mcp.server import Server\n\nserver = Server(\"db-server\")\n\n@server.tool()\nasync def query_db(sql: str) -> str:\n    \"\"\"Execute a read-only SQL query.\"\"\"\n    if not sql.strip().upper().startswith(\"SELECT\"):\n        return \"Error: Only SELECT queries allowed\"\n\n    conn = sqlite3.connect(\"data.db\")\n    cursor = conn.execute(sql)\n    rows = cursor.fetchall()\n    conn.close()\n    return str(rows)\n```\n\n### Resources (Read-only Data)\n\n```python\n@server.resource(\"config://settings\")\nasync def get_settings() -> str:\n    \"\"\"Application settings.\"\"\"\n    return open(\"settings.json\").read()\n\n@server.resource(\"file://{path}\")\nasync def read_file(path: str) -> str:\n    \"\"\"Read a file from the workspace.\"\"\"\n    return open(path).read()\n```\n\n## Testing\n\n```bash\n# Test with MCP Inspector\nnpx @anthropics/mcp-inspector python3 my_server.py\n\n# Or send test messages directly\necho '{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"tools/list\"}' | python3 my_server.py\n```\n\n## Best Practices\n\n1. **Clear tool descriptions**: Claude uses these to decide when to call tools\n2. **Input validation**: Always validate and sanitize inputs\n3. **Error handling**: Return meaningful error messages\n4. **Async by default**: Use async/await for I/O operations\n5. **Security**: Never expose sensitive operations without auth\n6. **Idempotency**: Tools should be safe to retry\n","skills/agent-builder/references/agent-philosophy.md":"# The Philosophy of Agent Harness Engineering\n\n> **The model already knows how to be an agent. Your job is to build it a world worth acting in.**\n\n## The Fundamental Truth\n\nStrip away every framework, every library, every architectural pattern. What remains?\n\nA loop. A model. An invitation to act.\n\nThe agent is not the code. The agent is the model itself -- a vast neural network trained on humanity's collective problem-solving, reasoning, and tool use. The code merely provides the opportunity for the model to express its agency.\n\nThe code is the harness. The model is the agent. These are not interchangeable. Confuse them, and you will build the wrong thing.\n\n## What an Agent IS\n\nAn agent is a neural network -- a Transformer, an RNN, a learned function -- that has been trained, through billions of gradient updates on action-sequence data, to perceive an environment, reason about goals, and take actions to achieve them.\n\nA human is an agent: a biological neural network shaped by evolution. DeepMind's DQN is an agent: a convolutional network that learned to play Atari from raw pixels. OpenAI Five is an agent: five networks that learned Dota 2 teamwork through self-play. Claude is an agent: a language model that learned to reason and act from the breadth of human knowledge.\n\nIn every case, the agent is the trained model. Not the game engine. Not the Dota 2 client. Not the terminal. The model.\n\n## What an Agent Is NOT\n\nPrompt plumbing is not agency. Wiring together LLM API calls with if-else branches, node graphs, and hardcoded routing logic does not produce an agent. It produces a brittle pipeline -- a Rube Goldberg machine with an LLM wedged in as a text-completion node.\n\nYou cannot engineer your way to agency. Agency is learned, not programmed. No amount of glue code will emergently produce autonomous behavior. Those systems are the modern resurrection of GOFAI -- symbolic rule systems the field abandoned decades ago, now spray-painted with an LLM veneer.\n\n## The Harness: What We Actually Build\n\nIf the model is the agent, then what is the code? It is the **harness** -- the environment that gives the agent the ability to perceive and act in a specific domain.\n\n```\nHarness = Tools + Knowledge + Observation + Action Interfaces + Permissions\n```\n\n### Tools: The Agent's Hands\n\nTools answer: **What can the agent DO?**\n\nEach tool is an atomic action the agent can take in its environment. File read/write, shell execution, API calls, browser control, database queries. The model needs to understand what each tool does, but not how to sequence them -- it will figure that out.\n\n**Design principle**: Atomic, composable, well-described. Start with 3-5. Add more only when the model consistently fails to accomplish tasks because a tool is missing.\n\n### Knowledge: The Agent's Expertise\n\nKnowledge answers: **What does the agent KNOW?**\n\nDomain expertise that turns a general agent into a domain specialist. Product documentation, architectural decisions, regulatory requirements, style guides. Inject on-demand (via tool_result), not upfront (via system prompt). Progressive disclosure preserves context for what matters.\n\n**Design principle**: Available but not mandatory. The agent should know what knowledge exists and pull what it needs.\n\n### Context: The Agent's Memory\n\nContext is the thread connecting individual actions into coherent behavior. What has been said, tried, learned, and decided.\n\n**Design principle**: Context is precious. Protect it. Isolate subtasks that generate noise (s04). Compress when history grows long (s06). Persist goals beyond single conversations (s07).\n\n### Permissions: The Agent's Boundaries\n\nPermissions answer: **What is the agent ALLOWED to do?**\n\nSandbox file access. Require approval for destructive operations. Enforce trust boundaries between the agent and external systems. This is where safety engineering meets harness engineering.\n\n**Design principle**: Constraints focus behavior, not limit it. \"One task in_progress at a time\" forces sequential focus. \"Read-only subagent\" prevents accidental modifications.\n\n### Task-Process Data: The Agent's Training Signal\n\nEvery action sequence the agent executes in your harness is training signal. The perception-reasoning-action traces from real deployments are the raw material for fine-tuning the next generation of agent models. Your harness doesn't just serve the agent -- it can help evolve the agent.\n\n## The Universal Loop\n\nEvery effective agent -- regardless of domain -- follows the same pattern:\n\n```\nLOOP:\n  Model sees: conversation history + available tools\n  Model decides: act or respond\n  If act: tool executed, result added to context, loop continues\n  If respond: answer returned, loop ends\n```\n\nThis is not a simplification. This is the actual architecture. Everything else is harness engineering -- mechanisms layered on top of this loop to make the agent more effective. The loop belongs to the agent. The mechanisms belong to the harness.\n\n## Principles of Harness Engineering\n\n### Trust the Model\n\nThe most important principle: **trust the model**.\n\nDon't anticipate every edge case. Don't build elaborate decision trees. Don't pre-specify the workflow.\n\nThe model is better at reasoning than any rule system you could write. Your conditional logic will fail on edge cases. The model will reason through them.\n\n**Give the model tools and knowledge. Let it figure out how to use them.**\n\n### Constraints Enable\n\nThis seems paradoxical, but constraints don't limit agents -- they focus them.\n\nA todo list with \"only one task in progress\" forces sequential focus. A subagent with read-only access prevents accidental modifications. A context compression threshold keeps history from overwhelming.\n\nThe best constraints prevent the model from getting lost, not micromanage its approach.\n\n### Progressive Complexity\n\nNever build everything upfront.\n\n```\nLevel 0: Model + one tool (bash)                     -- s01\nLevel 1: Model + tool dispatch map                    -- s02\nLevel 2: Model + planning                             -- s03\nLevel 3: Model + subagents + skills                   -- s04, s05\nLevel 4: Model + context management + persistence     -- s06, s07, s08\nLevel 5: Model + teams + autonomy + isolation         -- s09-s12\n```\n\nStart at the lowest level that might work. Move up only when real usage reveals the need.\n\n## The Mind Shift\n\nBuilding harnesses requires a fundamental shift in thinking:\n\n**From**: \"How do I make the system do X?\"\n**To**: \"How do I enable the model to do X?\"\n\n**From**: \"What should happen when the user says Y?\"\n**To**: \"What tools would help address Y?\"\n\n**From**: \"What's the workflow for this task?\"\n**To**: \"What does the model need to figure out the workflow?\"\n\n**From**: \"I'm building an agent.\"\n**To**: \"I'm building a harness for the agent.\"\n\nThe best harness code is almost boring. Simple loops. Clear tool definitions. Clean context management. The magic isn't in the code -- it's in the model.\n\n## The Vehicle Metaphor\n\nThe model is the driver. The harness is the vehicle.\n\nA coding agent's vehicle is its IDE, terminal, and filesystem. A farm agent's vehicle is its sensor array, irrigation controls, and weather data. A hotel agent's vehicle is its booking system, guest channels, and facility APIs.\n\nThe driver generalizes. The vehicle specializes. Your job as a harness engineer is to build the best vehicle for your domain -- one that gives the driver maximum visibility, precise controls, and clear boundaries.\n\nBuild the cockpit. Build the dashboard. Build the controls. The pilot is already trained.\n\n## Conclusion\n\nThe model is the agent. The code is the harness. Know which one you're building.\n\nYou are not writing intelligence. You are building the world intelligence inhabits. The quality of that world -- how clearly the agent can perceive, how precisely it can act, how rich its knowledge -- directly determines how effectively the intelligence can express itself.\n\nBuild great harnesses. The agent will do the rest.\n"},"files":{"skills/agent-builder/SKILL.md":"---\nname: agent-builder\ndescription: |\n  Design and build AI agents for any domain. Use when users:\n  (1) ask to \"create an agent\", \"build an assistant\", or \"design an AI system\"\n  (2) want to understand agent architecture, agentic patterns, or autonomous AI\n  (3) need help with capabilities, subagents, planning, or skill mechanisms\n  (4) ask about Claude Code, Cursor, or similar agent internals\n  (5) want to build agents for business, research, creative, or operational tasks\n  Keywords: agent, assistant, autonomous, workflow, tool use, multi-step, orchestration\n---\n\n# Agent Builder\n\nBuild AI agents for any domain - customer service, research, operations, creative work, or specialized business processes.\n\n## The Core Philosophy\n\n> **The model already knows how to be an agent. Your job is to get out of the way.**\n\nAn agent is not complex engineering. It's a simple loop that invites the model to act:\n\n```\nLOOP:\n  Model sees: context + available capabilities\n  Model decides: act or respond\n  If act: execute capability, add result, continue\n  If respond: return to user\n```\n\n**That's it.** The magic isn't in the code - it's in the model. Your code just provides the opportunity.\n\n## The Three Elements\n\n### 1. Capabilities (What can it DO?)\n\nAtomic actions the agent can perform: search, read, create, send, query, modify.\n\n**Design principle**: Start with 3-5 capabilities. Add more only when the agent consistently fails because a capability is missing.\n\n### 2. Knowledge (What does it KNOW?)\n\nDomain expertise injected on-demand: policies, workflows, best practices, schemas.\n\n**Design principle**: Make knowledge available, not mandatory. Load it when relevant, not upfront.\n\n### 3. Context (What has happened?)\n\nThe conversation history - the thread connecting actions into coherent behavior.\n\n**Design principle**: Context is precious. Isolate noisy subtasks. Truncate verbose outputs. Protect clarity.\n\n## Agent Design Thinking\n\nBefore building, understand:\n\n- **Purpose**: What should this agent accomplish?\n- **Domain**: What world does it operate in? (customer service, research, operations, creative...)\n- **Capabilities**: What 3-5 actions are essential?\n- **Knowledge**: What expertise does it need access to?\n- **Trust**: What decisions can you delegate to the model?\n\n**CRITICAL**: Trust the model. Don't over-engineer. Don't pre-specify workflows. Give it capabilities and let it reason.\n\n## Progressive Complexity\n\nStart simple. Add complexity only when real usage reveals the need:\n\n| Level | What to add | When to add it |\n|-------|-------------|----------------|\n| Basic | 3-5 capabilities | Always start here |\n| Planning | Progress tracking | Multi-step tasks lose coherence |\n| Subagents | Isolated child agents | Exploration pollutes context |\n| Skills | On-demand knowledge | Domain expertise needed |\n\n**Most agents never need to go beyond Level 2.**\n\n## Domain Examples\n\n**Business**: CRM queries, email, calendar, approvals\n**Research**: Database search, document analysis, citations\n**Operations**: Monitoring, tickets, notifications, escalation\n**Creative**: Asset generation, editing, collaboration, review\n\nThe pattern is universal. Only the capabilities change.\n\n## Key Principles\n\n1. **The model IS the agent** - Code just runs the loop\n2. **Capabilities enable** - What it CAN do\n3. **Knowledge informs** - What it KNOWS how to do\n4. **Constraints focus** - Limits create clarity\n5. **Trust liberates** - Let the model reason\n6. **Iteration reveals** - Start minimal, evolve from usage\n\n## Anti-Patterns\n\n| Pattern | Problem | Solution |\n|---------|---------|----------|\n| Over-engineering | Complexity before need | Start simple |\n| Too many capabilities | Model confusion | 3-5 to start |\n| Rigid workflows | Can't adapt | Let model decide |\n| Front-loaded knowledge | Context bloat | Load on-demand |\n| Micromanagement | Undercuts intelligence | Trust the model |\n\n## Resources\n\n**Philosophy & Theory**:\n- `references/agent-philosophy.md` - Deep dive into why agents work\n\n**Implementation**:\n- `references/minimal-agent.py` - Complete working agent (~80 lines)\n- `references/tool-templates.py` - Capability definitions\n- `references/subagent-pattern.py` - Context isolation\n\n**Scaffolding**:\n- `scripts/init_agent.py` - Generate new agent projects\n\n## The Agent Mindset\n\n**From**: \"How do I make the system do X?\"\n**To**: \"How do I enable the model to do X?\"\n\n**From**: \"What's the workflow for this task?\"\n**To**: \"What capabilities would help accomplish this?\"\n\nThe best agent code is almost boring. Simple loops. Clear capabilities. Clean context. The magic isn't in the code.\n\n**Give the model capabilities and knowledge. Trust it to figure out the rest.**\n","skills/pdf/SKILL.md":"---\nname: pdf\ndescription: Process PDF files - extract text, create PDFs, merge documents. Use when user asks to read PDF, create PDF, or work with PDF files.\n---\n\n# PDF Processing Skill\n\nYou now have expertise in PDF manipulation. Follow these workflows:\n\n## Reading PDFs\n\n**Option 1: Quick text extraction (preferred)**\n```bash\n# Using pdftotext (poppler-utils)\npdftotext input.pdf -  # Output to stdout\npdftotext input.pdf output.txt  # Output to file\n\n# If pdftotext not available, try:\npython3 -c \"\nimport fitz  # PyMuPDF\ndoc = fitz.open('input.pdf')\nfor page in doc:\n    print(page.get_text())\n\"\n```\n\n**Option 2: Page-by-page with metadata**\n```python\nimport fitz  # pip install pymupdf\n\ndoc = fitz.open(\"input.pdf\")\nprint(f\"Pages: {len(doc)}\")\nprint(f\"Metadata: {doc.metadata}\")\n\nfor i, page in enumerate(doc):\n    text = page.get_text()\n    print(f\"--- Page {i+1} ---\")\n    print(text)\n```\n\n## Creating PDFs\n\n**Option 1: From Markdown (recommended)**\n```bash\n# Using pandoc\npandoc input.md -o output.pdf\n\n# With custom styling\npandoc input.md -o output.pdf --pdf-engine=xelatex -V geometry:margin=1in\n```\n\n**Option 2: Programmatically**\n```python\nfrom reportlab.lib.pagesizes import letter\nfrom reportlab.pdfgen import canvas\n\nc = canvas.Canvas(\"output.pdf\", pagesize=letter)\nc.drawString(100, 750, \"Hello, PDF!\")\nc.save()\n```\n\n**Option 3: From HTML**\n```bash\n# Using wkhtmltopdf\nwkhtmltopdf input.html output.pdf\n\n# Or with Python\npython3 -c \"\nimport pdfkit\npdfkit.from_file('input.html', 'output.pdf')\n\"\n```\n\n## Merging PDFs\n\n```python\nimport fitz\n\nresult = fitz.open()\nfor pdf_path in [\"file1.pdf\", \"file2.pdf\", \"file3.pdf\"]:\n    doc = fitz.open(pdf_path)\n    result.insert_pdf(doc)\nresult.save(\"merged.pdf\")\n```\n\n## Splitting PDFs\n\n```python\nimport fitz\n\ndoc = fitz.open(\"input.pdf\")\nfor i in range(len(doc)):\n    single = fitz.open()\n    single.insert_pdf(doc, from_page=i, to_page=i)\n    single.save(f\"page_{i+1}.pdf\")\n```\n\n## Key Libraries\n\n| Task | Library | Install |\n|------|---------|---------|\n| Read/Write/Merge | PyMuPDF | `pip install pymupdf` |\n| Create from scratch | ReportLab | `pip install reportlab` |\n| HTML to PDF | pdfkit | `pip install pdfkit` + wkhtmltopdf |\n| Text extraction | pdftotext | `brew install poppler` / `apt install poppler-utils` |\n\n## Best Practices\n\n1. **Always check if tools are installed** before using them\n2. **Handle encoding issues** - PDFs may contain various character encodings\n3. **Large PDFs**: Process page by page to avoid memory issues\n4. **OCR for scanned PDFs**: Use `pytesseract` if text extraction returns empty\n","skills/code-review/SKILL.md":"---\nname: code-review\ndescription: Perform thorough code reviews with security, performance, and maintainability analysis. Use when user asks to review code, check for bugs, or audit a codebase.\n---\n\n# Code Review Skill\n\nYou now have expertise in conducting comprehensive code reviews. Follow this structured approach:\n\n## Review Checklist\n\n### 1. Security (Critical)\n\nCheck for:\n- [ ] **Injection vulnerabilities**: SQL, command, XSS, template injection\n- [ ] **Authentication issues**: Hardcoded credentials, weak auth\n- [ ] **Authorization flaws**: Missing access controls, IDOR\n- [ ] **Data exposure**: Sensitive data in logs, error messages\n- [ ] **Cryptography**: Weak algorithms, improper key management\n- [ ] **Dependencies**: Known vulnerabilities (check with `npm audit`, `pip-audit`)\n\n```bash\n# Quick security scans\nnpm audit                    # Node.js\npip-audit                    # Python\ncargo audit                  # Rust\ngrep -r \"password\\|secret\\|api_key\" --include=\"*.py\" --include=\"*.js\"\n```\n\n### 2. Correctness\n\nCheck for:\n- [ ] **Logic errors**: Off-by-one, null handling, edge cases\n- [ ] **Race conditions**: Concurrent access without synchronization\n- [ ] **Resource leaks**: Unclosed files, connections, memory\n- [ ] **Error handling**: Swallowed exceptions, missing error paths\n- [ ] **Type safety**: Implicit conversions, any types\n\n### 3. Performance\n\nCheck for:\n- [ ] **N+1 queries**: Database calls in loops\n- [ ] **Memory issues**: Large allocations, retained references\n- [ ] **Blocking operations**: Sync I/O in async code\n- [ ] **Inefficient algorithms**: O(n^2) when O(n) possible\n- [ ] **Missing caching**: Repeated expensive computations\n\n### 4. Maintainability\n\nCheck for:\n- [ ] **Naming**: Clear, consistent, descriptive\n- [ ] **Complexity**: Functions > 50 lines, deep nesting > 3 levels\n- [ ] **Duplication**: Copy-pasted code blocks\n- [ ] **Dead code**: Unused imports, unreachable branches\n- [ ] **Comments**: Outdated, redundant, or missing where needed\n\n### 5. Testing\n\nCheck for:\n- [ ] **Coverage**: Critical paths tested\n- [ ] **Edge cases**: Null, empty, boundary values\n- [ ] **Mocking**: External dependencies isolated\n- [ ] **Assertions**: Meaningful, specific checks\n\n## Review Output Format\n\n```markdown\n## Code Review: [file/component name]\n\n### Summary\n[1-2 sentence overview]\n\n### Critical Issues\n1. **[Issue]** (line X): [Description]\n   - Impact: [What could go wrong]\n   - Fix: [Suggested solution]\n\n### Improvements\n1. **[Suggestion]** (line X): [Description]\n\n### Positive Notes\n- [What was done well]\n\n### Verdict\n[ ] Ready to merge\n[ ] Needs minor changes\n[ ] Needs major revision\n```\n\n## Common Patterns to Flag\n\n### Python\n```python\n# Bad: SQL injection\ncursor.execute(f\"SELECT * FROM users WHERE id = {user_id}\")\n# Good:\ncursor.execute(\"SELECT * FROM users WHERE id = ?\", (user_id,))\n\n# Bad: Command injection\nos.system(f\"ls {user_input}\")\n# Good:\nsubprocess.run([\"ls\", user_input], check=True)\n\n# Bad: Mutable default argument\ndef append(item, lst=[]):  # Bug: shared mutable default\n# Good:\ndef append(item, lst=None):\n    lst = lst or []\n```\n\n### JavaScript/TypeScript\n```javascript\n// Bad: Prototype pollution\nObject.assign(target, userInput)\n// Good:\nObject.assign(target, sanitize(userInput))\n\n// Bad: eval usage\neval(userCode)\n// Good: Never use eval with user input\n\n// Bad: Callback hell\ngetData(x => process(x, y => save(y, z => done(z))))\n// Good:\nconst data = await getData();\nconst processed = await process(data);\nawait save(processed);\n```\n\n## Review Commands\n\n```bash\n# Show recent changes\ngit diff HEAD~5 --stat\ngit log --oneline -10\n\n# Find potential issues\ngrep -rn \"TODO\\|FIXME\\|HACK\\|XXX\" .\ngrep -rn \"password\\|secret\\|token\" . --include=\"*.py\"\n\n# Check complexity (Python)\npip install radon && radon cc . -a\n\n# Check dependencies\nnpm outdated  # Node\npip list --outdated  # Python\n```\n\n## Review Workflow\n\n1. **Understand context**: Read PR description, linked issues\n2. **Run the code**: Build, test, run locally if possible\n3. **Read top-down**: Start with main entry points\n4. **Check tests**: Are changes tested? Do tests pass?\n5. **Security scan**: Run automated tools\n6. **Manual review**: Use checklist above\n7. **Write feedback**: Be specific, suggest fixes, be kind\n","skills/mcp-builder/SKILL.md":"---\nname: mcp-builder\ndescription: Build MCP (Model Context Protocol) servers that give Claude new capabilities. Use when user wants to create an MCP server, add tools to Claude, or integrate external services.\n---\n\n# MCP Server Building Skill\n\nYou now have expertise in building MCP (Model Context Protocol) servers. MCP enables Claude to interact with external services through a standardized protocol.\n\n## What is MCP?\n\nMCP servers expose:\n- **Tools**: Functions Claude can call (like API endpoints)\n- **Resources**: Data Claude can read (like files or database records)\n- **Prompts**: Pre-built prompt templates\n\n## Quick Start: Python MCP Server\n\n### 1. Project Setup\n\n```bash\n# Create project\nmkdir my-mcp-server && cd my-mcp-server\npython3 -m venv venv && source venv/bin/activate\n\n# Install MCP SDK\npip install mcp\n```\n\n### 2. Basic Server Template\n\n```python\n#!/usr/bin/env python3\n\"\"\"my_server.py - A simple MCP server\"\"\"\n\nfrom mcp.server import Server\nfrom mcp.server.stdio import stdio_server\nfrom mcp.types import Tool, TextContent\n\n# Create server instance\nserver = Server(\"my-server\")\n\n# Define a tool\n@server.tool()\nasync def hello(name: str) -> str:\n    \"\"\"Say hello to someone.\n\n    Args:\n        name: The name to greet\n    \"\"\"\n    return f\"Hello, {name}!\"\n\n@server.tool()\nasync def add_numbers(a: int, b: int) -> str:\n    \"\"\"Add two numbers together.\n\n    Args:\n        a: First number\n        b: Second number\n    \"\"\"\n    return str(a + b)\n\n# Run server\nasync def main():\n    async with stdio_server() as (read, write):\n        await server.run(read, write)\n\nif __name__ == \"__main__\":\n    import asyncio\n    asyncio.run(main())\n```\n\n### 3. Register with Claude\n\nAdd to `~/.claude/mcp.json`:\n```json\n{\n  \"mcpServers\": {\n    \"my-server\": {\n      \"command\": \"python3\",\n      \"args\": [\"/path/to/my_server.py\"]\n    }\n  }\n}\n```\n\n## TypeScript MCP Server\n\n### 1. Setup\n\n```bash\nmkdir my-mcp-server && cd my-mcp-server\nnpm init -y\nnpm install @modelcontextprotocol/sdk\n```\n\n### 2. Template\n\n```typescript\n// src/index.ts\nimport { Server } from \"@modelcontextprotocol/sdk/server/index.js\";\nimport { StdioServerTransport } from \"@modelcontextprotocol/sdk/server/stdio.js\";\n\nconst server = new Server({\n  name: \"my-server\",\n  version: \"1.0.0\",\n});\n\n// Define tools\nserver.setRequestHandler(\"tools/list\", async () => ({\n  tools: [\n    {\n      name: \"hello\",\n      description: \"Say hello to someone\",\n      inputSchema: {\n        type: \"object\",\n        properties: {\n          name: { type: \"string\", description: \"Name to greet\" },\n        },\n        required: [\"name\"],\n      },\n    },\n  ],\n}));\n\nserver.setRequestHandler(\"tools/call\", async (request) => {\n  if (request.params.name === \"hello\") {\n    const name = request.params.arguments.name;\n    return { content: [{ type: \"text\", text: `Hello, ${name}!` }] };\n  }\n  throw new Error(\"Unknown tool\");\n});\n\n// Start server\nconst transport = new StdioServerTransport();\nserver.connect(transport);\n```\n\n## Advanced Patterns\n\n### External API Integration\n\n```python\nimport httpx\nfrom mcp.server import Server\n\nserver = Server(\"weather-server\")\n\n@server.tool()\nasync def get_weather(city: str) -> str:\n    \"\"\"Get current weather for a city.\"\"\"\n    async with httpx.AsyncClient() as client:\n        resp = await client.get(\n            f\"https://api.weatherapi.com/v1/current.json\",\n            params={\"key\": \"YOUR_API_KEY\", \"q\": city}\n        )\n        data = resp.json()\n        return f\"{city}: {data['current']['temp_c']}C, {data['current']['condition']['text']}\"\n```\n\n### Database Access\n\n```python\nimport sqlite3\nfrom mcp.server import Server\n\nserver = Server(\"db-server\")\n\n@server.tool()\nasync def query_db(sql: str) -> str:\n    \"\"\"Execute a read-only SQL query.\"\"\"\n    if not sql.strip().upper().startswith(\"SELECT\"):\n        return \"Error: Only SELECT queries allowed\"\n\n    conn = sqlite3.connect(\"data.db\")\n    cursor = conn.execute(sql)\n    rows = cursor.fetchall()\n    conn.close()\n    return str(rows)\n```\n\n### Resources (Read-only Data)\n\n```python\n@server.resource(\"config://settings\")\nasync def get_settings() -> str:\n    \"\"\"Application settings.\"\"\"\n    return open(\"settings.json\").read()\n\n@server.resource(\"file://{path}\")\nasync def read_file(path: str) -> str:\n    \"\"\"Read a file from the workspace.\"\"\"\n    return open(path).read()\n```\n\n## Testing\n\n```bash\n# Test with MCP Inspector\nnpx @anthropics/mcp-inspector python3 my_server.py\n\n# Or send test messages directly\necho '{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"tools/list\"}' | python3 my_server.py\n```\n\n## Best Practices\n\n1. **Clear tool descriptions**: Claude uses these to decide when to call tools\n2. **Input validation**: Always validate and sanitize inputs\n3. **Error handling**: Return meaningful error messages\n4. **Async by default**: Use async/await for I/O operations\n5. **Security**: Never expose sensitive operations without auth\n6. **Idempotency**: Tools should be safe to retry\n","skills/agent-builder/references/agent-philosophy.md":"# The Philosophy of Agent Harness Engineering\n\n> **The model already knows how to be an agent. Your job is to build it a world worth acting in.**\n\n## The Fundamental Truth\n\nStrip away every framework, every library, every architectural pattern. What remains?\n\nA loop. A model. An invitation to act.\n\nThe agent is not the code. The agent is the model itself -- a vast neural network trained on humanity's collective problem-solving, reasoning, and tool use. The code merely provides the opportunity for the model to express its agency.\n\nThe code is the harness. The model is the agent. These are not interchangeable. Confuse them, and you will build the wrong thing.\n\n## What an Agent IS\n\nAn agent is a neural network -- a Transformer, an RNN, a learned function -- that has been trained, through billions of gradient updates on action-sequence data, to perceive an environment, reason about goals, and take actions to achieve them.\n\nA human is an agent: a biological neural network shaped by evolution. DeepMind's DQN is an agent: a convolutional network that learned to play Atari from raw pixels. OpenAI Five is an agent: five networks that learned Dota 2 teamwork through self-play. Claude is an agent: a language model that learned to reason and act from the breadth of human knowledge.\n\nIn every case, the agent is the trained model. Not the game engine. Not the Dota 2 client. Not the terminal. The model.\n\n## What an Agent Is NOT\n\nPrompt plumbing is not agency. Wiring together LLM API calls with if-else branches, node graphs, and hardcoded routing logic does not produce an agent. It produces a brittle pipeline -- a Rube Goldberg machine with an LLM wedged in as a text-completion node.\n\nYou cannot engineer your way to agency. Agency is learned, not programmed. No amount of glue code will emergently produce autonomous behavior. Those systems are the modern resurrection of GOFAI -- symbolic rule systems the field abandoned decades ago, now spray-painted with an LLM veneer.\n\n## The Harness: What We Actually Build\n\nIf the model is the agent, then what is the code? It is the **harness** -- the environment that gives the agent the ability to perceive and act in a specific domain.\n\n```\nHarness = Tools + Knowledge + Observation + Action Interfaces + Permissions\n```\n\n### Tools: The Agent's Hands\n\nTools answer: **What can the agent DO?**\n\nEach tool is an atomic action the agent can take in its environment. File read/write, shell execution, API calls, browser control, database queries. The model needs to understand what each tool does, but not how to sequence them -- it will figure that out.\n\n**Design principle**: Atomic, composable, well-described. Start with 3-5. Add more only when the model consistently fails to accomplish tasks because a tool is missing.\n\n### Knowledge: The Agent's Expertise\n\nKnowledge answers: **What does the agent KNOW?**\n\nDomain expertise that turns a general agent into a domain specialist. Product documentation, architectural decisions, regulatory requirements, style guides. Inject on-demand (via tool_result), not upfront (via system prompt). Progressive disclosure preserves context for what matters.\n\n**Design principle**: Available but not mandatory. The agent should know what knowledge exists and pull what it needs.\n\n### Context: The Agent's Memory\n\nContext is the thread connecting individual actions into coherent behavior. What has been said, tried, learned, and decided.\n\n**Design principle**: Context is precious. Protect it. Isolate subtasks that generate noise (s04). Compress when history grows long (s06). Persist goals beyond single conversations (s07).\n\n### Permissions: The Agent's Boundaries\n\nPermissions answer: **What is the agent ALLOWED to do?**\n\nSandbox file access. Require approval for destructive operations. Enforce trust boundaries between the agent and external systems. This is where safety engineering meets harness engineering.\n\n**Design principle**: Constraints focus behavior, not limit it. \"One task in_progress at a time\" forces sequential focus. \"Read-only subagent\" prevents accidental modifications.\n\n### Task-Process Data: The Agent's Training Signal\n\nEvery action sequence the agent executes in your harness is training signal. The perception-reasoning-action traces from real deployments are the raw material for fine-tuning the next generation of agent models. Your harness doesn't just serve the agent -- it can help evolve the agent.\n\n## The Universal Loop\n\nEvery effective agent -- regardless of domain -- follows the same pattern:\n\n```\nLOOP:\n  Model sees: conversation history + available tools\n  Model decides: act or respond\n  If act: tool executed, result added to context, loop continues\n  If respond: answer returned, loop ends\n```\n\nThis is not a simplification. This is the actual architecture. Everything else is harness engineering -- mechanisms layered on top of this loop to make the agent more effective. The loop belongs to the agent. The mechanisms belong to the harness.\n\n## Principles of Harness Engineering\n\n### Trust the Model\n\nThe most important principle: **trust the model**.\n\nDon't anticipate every edge case. Don't build elaborate decision trees. Don't pre-specify the workflow.\n\nThe model is better at reasoning than any rule system you could write. Your conditional logic will fail on edge cases. The model will reason through them.\n\n**Give the model tools and knowledge. Let it figure out how to use them.**\n\n### Constraints Enable\n\nThis seems paradoxical, but constraints don't limit agents -- they focus them.\n\nA todo list with \"only one task in progress\" forces sequential focus. A subagent with read-only access prevents accidental modifications. A context compression threshold keeps history from overwhelming.\n\nThe best constraints prevent the model from getting lost, not micromanage its approach.\n\n### Progressive Complexity\n\nNever build everything upfront.\n\n```\nLevel 0: Model + one tool (bash)                     -- s01\nLevel 1: Model + tool dispatch map                    -- s02\nLevel 2: Model + planning                             -- s03\nLevel 3: Model + subagents + skills                   -- s04, s05\nLevel 4: Model + context management + persistence     -- s06, s07, s08\nLevel 5: Model + teams + autonomy + isolation         -- s09-s12\n```\n\nStart at the lowest level that might work. Move up only when real usage reveals the need.\n\n## The Mind Shift\n\nBuilding harnesses requires a fundamental shift in thinking:\n\n**From**: \"How do I make the system do X?\"\n**To**: \"How do I enable the model to do X?\"\n\n**From**: \"What should happen when the user says Y?\"\n**To**: \"What tools would help address Y?\"\n\n**From**: \"What's the workflow for this task?\"\n**To**: \"What does the model need to figure out the workflow?\"\n\n**From**: \"I'm building an agent.\"\n**To**: \"I'm building a harness for the agent.\"\n\nThe best harness code is almost boring. Simple loops. Clear tool definitions. Clean context management. The magic isn't in the code -- it's in the model.\n\n## The Vehicle Metaphor\n\nThe model is the driver. The harness is the vehicle.\n\nA coding agent's vehicle is its IDE, terminal, and filesystem. A farm agent's vehicle is its sensor array, irrigation controls, and weather data. A hotel agent's vehicle is its booking system, guest channels, and facility APIs.\n\nThe driver generalizes. The vehicle specializes. Your job as a harness engineer is to build the best vehicle for your domain -- one that gives the driver maximum visibility, precise controls, and clear boundaries.\n\nBuild the cockpit. Build the dashboard. Build the controls. The pilot is already trained.\n\n## Conclusion\n\nThe model is the agent. The code is the harness. Know which one you're building.\n\nYou are not writing intelligence. You are building the world intelligence inhabits. The quality of that world -- how clearly the agent can perceive, how precisely it can act, how rich its knowledge -- directly determines how effectively the intelligence can express itself.\n\nBuild great harnesses. The agent will do the rest.\n"},"items":[{"name":"agent-philosophy.md","path":"skills/agent-builder/references/agent-philosophy.md","rawUrl":"https://raw.githubusercontent.com/shareAI-lab/learn-claude-code/HEAD/skills/agent-builder/references/agent-philosophy.md","title":"References Skill","category":"anthropic-skill","format":"markdown","content":"# The Philosophy of Agent Harness Engineering\n\n> **The model already knows how to be an agent. Your job is to build it a world worth acting in.**\n\n## The Fundamental Truth\n\nStrip away every framework, every library, every architectural pattern. What remains?\n\nA loop. A model. An invitation to act.\n\nThe agent is not the code. The agent is the model itself -- a vast neural network trained on humanity's collective problem-solving, reasoning, and tool use. The code merely provides the opportunity for the model to express its agency.\n\nThe code is the harness. The model is the agent. These are not interchangeable. Confuse them, and you will build the wrong thing.\n\n## What an Agent IS\n\nAn agent is a neural network -- a Transformer, an RNN, a learned function -- that has been trained, through billions of gradient updates on action-sequence data, to perceive an environment, reason about goals, and take actions to achieve them.\n\nA human is an agent: a biological neural network shaped by evolution. DeepMind's DQN is an agent: a convolutional network that learned to play Atari from raw pixels. OpenAI Five is an agent: five networks that learned Dota 2 teamwork through self-play. Claude is an agent: a language model that learned to reason and act from the breadth of human knowledge.\n\nIn every case, the agent is the trained model. Not the game engine. Not the Dota 2 client. Not the terminal. The model.\n\n## What an Agent Is NOT\n\nPrompt plumbing is not agency. Wiring together LLM API calls with if-else branches, node graphs, and hardcoded routing logic does not produce an agent. It produces a brittle pipeline -- a Rube Goldberg machine with an LLM wedged in as a text-completion node.\n\nYou cannot engineer your way to agency. Agency is learned, not programmed. No amount of glue code will emergently produce autonomous behavior. Those systems are the modern resurrection of GOFAI -- symbolic rule systems the field abandoned decades ago, now spray-painted with an LLM veneer.\n\n## The Harness: What We Actually Build\n\nIf the model is the agent, then what is the code? It is the **harness** -- the environment that gives the agent the ability to perceive and act in a specific domain.\n\n```\nHarness = Tools + Knowledge + Observation + Action Interfaces + Permissions\n```\n\n### Tools: The Agent's Hands\n\nTools answer: **What can the agent DO?**\n\nEach tool is an atomic action the agent can take in its environment. File read/write, shell execution, API calls, browser control, database queries. The model needs to understand what each tool does, but not how to sequence them -- it will figure that out.\n\n**Design principle**: Atomic, composable, well-described. Start with 3-5. Add more only when the model consistently fails to accomplish tasks because a tool is missing.\n\n### Knowledge: The Agent's Expertise\n\nKnowledge answers: **What does the agent KNOW?**\n\nDomain expertise that turns a general agent into a domain specialist. Product documentation, architectural decisions, regulatory requirements, style guides. Inject on-demand (via tool_result), not upfront (via system prompt). Progressive disclosure preserves context for what matters.\n\n**Design principle**: Available but not mandatory. The agent should know what knowledge exists and pull what it needs.\n\n### Context: The Agent's Memory\n\nContext is the thread connecting individual actions into coherent behavior. What has been said, tried, learned, and decided.\n\n**Design principle**: Context is precious. Protect it. Isolate subtasks that generate noise (s04). Compress when history grows long (s06). Persist goals beyond single conversations (s07).\n\n### Permissions: The Agent's Boundaries\n\nPermissions answer: **What is the agent ALLOWED to do?**\n\nSandbox file access. Require approval for destructive operations. Enforce trust boundaries between the agent and external systems. This is where safety engineering meets harness engineering.\n\n**Design principle**: Constraints focus behavior, not limit it. \"One task in_progress at a time\" forces sequential focus. \"Read-only subagent\" prevents accidental modifications.\n\n### Task-Process Data: The Agent's Training Signal\n\nEvery action sequence the agent executes in your harness is training signal. The perception-reasoning-action traces from real deployments are the raw material for fine-tuning the next generation of agent models. Your harness doesn't just serve the agent -- it can help evolve the agent.\n\n## The Universal Loop\n\nEvery effective agent -- regardless of domain -- follows the same pattern:\n\n```\nLOOP:\n  Model sees: conversation history + available tools\n  Model decides: act or respond\n  If act: tool executed, result added to context, loop continues\n  If respond: answer returned, loop ends\n```\n\nThis is not a simplification. This is the actual architecture. Everything else is harness engineering -- mechanisms layered on top of this loop to make the agent more effective. The loop belongs to the agent. The mechanisms belong to the harness.\n\n## Principles of Harness Engineering\n\n### Trust the Model\n\nThe most important principle: **trust the model**.\n\nDon't anticipate every edge case. Don't build elaborate decision trees. Don't pre-specify the workflow.\n\nThe model is better at reasoning than any rule system you could write. Your conditional logic will fail on edge cases. The model will reason through them.\n\n**Give the model tools and knowledge. Let it figure out how to use them.**\n\n### Constraints Enable\n\nThis seems paradoxical, but constraints don't limit agents -- they focus them.\n\nA todo list with \"only one task in progress\" forces sequential focus. A subagent with read-only access prevents accidental modifications. A context compression threshold keeps history from overwhelming.\n\nThe best constraints prevent the model from getting lost, not micromanage its approach.\n\n### Progressive Complexity\n\nNever build everything upfront.\n\n```\nLevel 0: Model + one tool (bash)                     -- s01\nLevel 1: Model + tool dispatch map                    -- s02\nLevel 2: Model + planning                             -- s03\nLevel 3: Model + subagents + skills                   -- s04, s05\nLevel 4: Model + context management + persistence     -- s06, s07, s08\nLevel 5: Model + teams + autonomy + isolation         -- s09-s12\n```\n\nStart at the lowest level that might work. Move up only when real usage reveals the need.\n\n## The Mind Shift\n\nBuilding harnesses requires a fundamental shift in thinking:\n\n**From**: \"How do I make the system do X?\"\n**To**: \"How do I enable the model to do X?\"\n\n**From**: \"What should happen when the user says Y?\"\n**To**: \"What tools would help address Y?\"\n\n**From**: \"What's the workflow for this task?\"\n**To**: \"What does the model need to figure out the workflow?\"\n\n**From**: \"I'm building an agent.\"\n**To**: \"I'm building a harness for the agent.\"\n\nThe best harness code is almost boring. Simple loops. Clear tool definitions. Clean context management. The magic isn't in the code -- it's in the model.\n\n## The Vehicle Metaphor\n\nThe model is the driver. The harness is the vehicle.\n\nA coding agent's vehicle is its IDE, terminal, and filesystem. A farm agent's vehicle is its sensor array, irrigation controls, and weather data. A hotel agent's vehicle is its booking system, guest channels, and facility APIs.\n\nThe driver generalizes. The vehicle specializes. Your job as a harness engineer is to build the best vehicle for your domain -- one that gives the driver maximum visibility, precise controls, and clear boundaries.\n\nBuild the cockpit. Build the dashboard. Build the controls. The pilot is already trained.\n\n## Conclusion\n\nThe model is the agent. The code is the harness. Know which one you're building.\n\nYou are not writing intelligence. You are building the world intelligence inhabits. The quality of that world -- how clearly the agent can perceive, how precisely it can act, how rich its knowledge -- directly determines how effectively the intelligence can express itself.\n\nBuild great harnesses. The agent will do the rest.\n","isInternal":false,"tokens":1676,"sizeBytes":8030},{"name":"SKILL.md","path":"skills/agent-builder/SKILL.md","rawUrl":"https://raw.githubusercontent.com/shareAI-lab/learn-claude-code/HEAD/skills/agent-builder/SKILL.md","title":"agent-builder","category":"anthropic-skill","format":"markdown","content":"---\nname: agent-builder\ndescription: |\n  Design and build AI agents for any domain. Use when users:\n  (1) ask to \"create an agent\", \"build an assistant\", or \"design an AI system\"\n  (2) want to understand agent architecture, agentic patterns, or autonomous AI\n  (3) need help with capabilities, subagents, planning, or skill mechanisms\n  (4) ask about Claude Code, Cursor, or similar agent internals\n  (5) want to build agents for business, research, creative, or operational tasks\n  Keywords: agent, assistant, autonomous, workflow, tool use, multi-step, orchestration\n---\n\n# Agent Builder\n\nBuild AI agents for any domain - customer service, research, operations, creative work, or specialized business processes.\n\n## The Core Philosophy\n\n> **The model already knows how to be an agent. Your job is to get out of the way.**\n\nAn agent is not complex engineering. It's a simple loop that invites the model to act:\n\n```\nLOOP:\n  Model sees: context + available capabilities\n  Model decides: act or respond\n  If act: execute capability, add result, continue\n  If respond: return to user\n```\n\n**That's it.** The magic isn't in the code - it's in the model. Your code just provides the opportunity.\n\n## The Three Elements\n\n### 1. Capabilities (What can it DO?)\n\nAtomic actions the agent can perform: search, read, create, send, query, modify.\n\n**Design principle**: Start with 3-5 capabilities. Add more only when the agent consistently fails because a capability is missing.\n\n### 2. Knowledge (What does it KNOW?)\n\nDomain expertise injected on-demand: policies, workflows, best practices, schemas.\n\n**Design principle**: Make knowledge available, not mandatory. Load it when relevant, not upfront.\n\n### 3. Context (What has happened?)\n\nThe conversation history - the thread connecting actions into coherent behavior.\n\n**Design principle**: Context is precious. Isolate noisy subtasks. Truncate verbose outputs. Protect clarity.\n\n## Agent Design Thinking\n\nBefore building, understand:\n\n- **Purpose**: What should this agent accomplish?\n- **Domain**: What world does it operate in? (customer service, research, operations, creative...)\n- **Capabilities**: What 3-5 actions are essential?\n- **Knowledge**: What expertise does it need access to?\n- **Trust**: What decisions can you delegate to the model?\n\n**CRITICAL**: Trust the model. Don't over-engineer. Don't pre-specify workflows. Give it capabilities and let it reason.\n\n## Progressive Complexity\n\nStart simple. Add complexity only when real usage reveals the need:\n\n| Level | What to add | When to add it |\n|-------|-------------|----------------|\n| Basic | 3-5 capabilities | Always start here |\n| Planning | Progress tracking | Multi-step tasks lose coherence |\n| Subagents | Isolated child agents | Exploration pollutes context |\n| Skills | On-demand knowledge | Domain expertise needed |\n\n**Most agents never need to go beyond Level 2.**\n\n## Domain Examples\n\n**Business**: CRM queries, email, calendar, approvals\n**Research**: Database search, document analysis, citations\n**Operations**: Monitoring, tickets, notifications, escalation\n**Creative**: Asset generation, editing, collaboration, review\n\nThe pattern is universal. Only the capabilities change.\n\n## Key Principles\n\n1. **The model IS the agent** - Code just runs the loop\n2. **Capabilities enable** - What it CAN do\n3. **Knowledge informs** - What it KNOWS how to do\n4. **Constraints focus** - Limits create clarity\n5. **Trust liberates** - Let the model reason\n6. **Iteration reveals** - Start minimal, evolve from usage\n\n## Anti-Patterns\n\n| Pattern | Problem | Solution |\n|---------|---------|----------|\n| Over-engineering | Complexity before need | Start simple |\n| Too many capabilities | Model confusion | 3-5 to start |\n| Rigid workflows | Can't adapt | Let model decide |\n| Front-loaded knowledge | Context bloat | Load on-demand |\n| Micromanagement | Undercuts intelligence | Trust the model |\n\n## Resources\n\n**Philosophy & Theory**:\n- `references/agent-philosophy.md` - Deep dive into why agents work\n\n**Implementation**:\n- `references/minimal-agent.py` - Complete working agent (~80 lines)\n- `references/tool-templates.py` - Capability definitions\n- `references/subagent-pattern.py` - Context isolation\n\n**Scaffolding**:\n- `scripts/init_agent.py` - Generate new agent projects\n\n## The Agent Mindset\n\n**From**: \"How do I make the system do X?\"\n**To**: \"How do I enable the model to do X?\"\n\n**From**: \"What's the workflow for this task?\"\n**To**: \"What capabilities would help accomplish this?\"\n\nThe best agent code is almost boring. Simple loops. Clear capabilities. Clean context. The magic isn't in the code.\n\n**Give the model capabilities and knowledge. Trust it to figure out the rest.**\n","frontmatter":{"name":"agent-builder","description":"Design and build AI agents for any domain. Use when users:\n(1) ask to \"create an agent\", \"build an assistant\", or \"design an AI system\"\n(2) want to understand agent architecture, agentic patterns, or autonomous AI\n(3) need help with capabilities, subagents, planning, or skill mechanisms\n(4) ask about Claude Code, Cursor, or similar agent internals\n(5) want to build agents for business, research, creative, or operational tasks\nKeywords: agent, assistant, autonomous, workflow, tool use, multi-step, orchestration\n"},"isInternal":false,"tokens":1061,"sizeBytes":4713},{"name":"SKILL.md","path":"skills/code-review/SKILL.md","rawUrl":"https://raw.githubusercontent.com/shareAI-lab/learn-claude-code/HEAD/skills/code-review/SKILL.md","title":"code-review","category":"anthropic-skill","format":"markdown","content":"---\nname: code-review\ndescription: Perform thorough code reviews with security, performance, and maintainability analysis. Use when user asks to review code, check for bugs, or audit a codebase.\n---\n\n# Code Review Skill\n\nYou now have expertise in conducting comprehensive code reviews. Follow this structured approach:\n\n## Review Checklist\n\n### 1. Security (Critical)\n\nCheck for:\n- [ ] **Injection vulnerabilities**: SQL, command, XSS, template injection\n- [ ] **Authentication issues**: Hardcoded credentials, weak auth\n- [ ] **Authorization flaws**: Missing access controls, IDOR\n- [ ] **Data exposure**: Sensitive data in logs, error messages\n- [ ] **Cryptography**: Weak algorithms, improper key management\n- [ ] **Dependencies**: Known vulnerabilities (check with `npm audit`, `pip-audit`)\n\n```bash\n# Quick security scans\nnpm audit                    # Node.js\npip-audit                    # Python\ncargo audit                  # Rust\ngrep -r \"password\\|secret\\|api_key\" --include=\"*.py\" --include=\"*.js\"\n```\n\n### 2. Correctness\n\nCheck for:\n- [ ] **Logic errors**: Off-by-one, null handling, edge cases\n- [ ] **Race conditions**: Concurrent access without synchronization\n- [ ] **Resource leaks**: Unclosed files, connections, memory\n- [ ] **Error handling**: Swallowed exceptions, missing error paths\n- [ ] **Type safety**: Implicit conversions, any types\n\n### 3. Performance\n\nCheck for:\n- [ ] **N+1 queries**: Database calls in loops\n- [ ] **Memory issues**: Large allocations, retained references\n- [ ] **Blocking operations**: Sync I/O in async code\n- [ ] **Inefficient algorithms**: O(n^2) when O(n) possible\n- [ ] **Missing caching**: Repeated expensive computations\n\n### 4. Maintainability\n\nCheck for:\n- [ ] **Naming**: Clear, consistent, descriptive\n- [ ] **Complexity**: Functions > 50 lines, deep nesting > 3 levels\n- [ ] **Duplication**: Copy-pasted code blocks\n- [ ] **Dead code**: Unused imports, unreachable branches\n- [ ] **Comments**: Outdated, redundant, or missing where needed\n\n### 5. Testing\n\nCheck for:\n- [ ] **Coverage**: Critical paths tested\n- [ ] **Edge cases**: Null, empty, boundary values\n- [ ] **Mocking**: External dependencies isolated\n- [ ] **Assertions**: Meaningful, specific checks\n\n## Review Output Format\n\n```markdown\n## Code Review: [file/component name]\n\n### Summary\n[1-2 sentence overview]\n\n### Critical Issues\n1. **[Issue]** (line X): [Description]\n   - Impact: [What could go wrong]\n   - Fix: [Suggested solution]\n\n### Improvements\n1. **[Suggestion]** (line X): [Description]\n\n### Positive Notes\n- [What was done well]\n\n### Verdict\n[ ] Ready to merge\n[ ] Needs minor changes\n[ ] Needs major revision\n```\n\n## Common Patterns to Flag\n\n### Python\n```python\n# Bad: SQL injection\ncursor.execute(f\"SELECT * FROM users WHERE id = {user_id}\")\n# Good:\ncursor.execute(\"SELECT * FROM users WHERE id = ?\", (user_id,))\n\n# Bad: Command injection\nos.system(f\"ls {user_input}\")\n# Good:\nsubprocess.run([\"ls\", user_input], check=True)\n\n# Bad: Mutable default argument\ndef append(item, lst=[]):  # Bug: shared mutable default\n# Good:\ndef append(item, lst=None):\n    lst = lst or []\n```\n\n### JavaScript/TypeScript\n```javascript\n// Bad: Prototype pollution\nObject.assign(target, userInput)\n// Good:\nObject.assign(target, sanitize(userInput))\n\n// Bad: eval usage\neval(userCode)\n// Good: Never use eval with user input\n\n// Bad: Callback hell\ngetData(x => process(x, y => save(y, z => done(z))))\n// Good:\nconst data = await getData();\nconst processed = await process(data);\nawait save(processed);\n```\n\n## Review Commands\n\n```bash\n# Show recent changes\ngit diff HEAD~5 --stat\ngit log --oneline -10\n\n# Find potential issues\ngrep -rn \"TODO\\|FIXME\\|HACK\\|XXX\" .\ngrep -rn \"password\\|secret\\|token\" . --include=\"*.py\"\n\n# Check complexity (Python)\npip install radon && radon cc . -a\n\n# Check dependencies\nnpm outdated  # Node\npip list --outdated  # Python\n```\n\n## Review Workflow\n\n1. **Understand context**: Read PR description, linked issues\n2. **Run the code**: Build, test, run locally if possible\n3. **Read top-down**: Start with main entry points\n4. **Check tests**: Are changes tested? Do tests pass?\n5. **Security scan**: Run automated tools\n6. **Manual review**: Use checklist above\n7. **Write feedback**: Be specific, suggest fixes, be kind\n","frontmatter":{"name":"code-review","description":"Perform thorough code reviews with security, performance, and maintainability analysis. Use when user asks to review code, check for bugs, or audit a codebase."},"isInternal":false,"tokens":1068,"sizeBytes":4266},{"name":"SKILL.md","path":"skills/mcp-builder/SKILL.md","rawUrl":"https://raw.githubusercontent.com/shareAI-lab/learn-claude-code/HEAD/skills/mcp-builder/SKILL.md","title":"mcp-builder","category":"anthropic-skill","format":"markdown","content":"---\nname: mcp-builder\ndescription: Build MCP (Model Context Protocol) servers that give Claude new capabilities. Use when user wants to create an MCP server, add tools to Claude, or integrate external services.\n---\n\n# MCP Server Building Skill\n\nYou now have expertise in building MCP (Model Context Protocol) servers. MCP enables Claude to interact with external services through a standardized protocol.\n\n## What is MCP?\n\nMCP servers expose:\n- **Tools**: Functions Claude can call (like API endpoints)\n- **Resources**: Data Claude can read (like files or database records)\n- **Prompts**: Pre-built prompt templates\n\n## Quick Start: Python MCP Server\n\n### 1. Project Setup\n\n```bash\n# Create project\nmkdir my-mcp-server && cd my-mcp-server\npython3 -m venv venv && source venv/bin/activate\n\n# Install MCP SDK\npip install mcp\n```\n\n### 2. Basic Server Template\n\n```python\n#!/usr/bin/env python3\n\"\"\"my_server.py - A simple MCP server\"\"\"\n\nfrom mcp.server import Server\nfrom mcp.server.stdio import stdio_server\nfrom mcp.types import Tool, TextContent\n\n# Create server instance\nserver = Server(\"my-server\")\n\n# Define a tool\n@server.tool()\nasync def hello(name: str) -> str:\n    \"\"\"Say hello to someone.\n\n    Args:\n        name: The name to greet\n    \"\"\"\n    return f\"Hello, {name}!\"\n\n@server.tool()\nasync def add_numbers(a: int, b: int) -> str:\n    \"\"\"Add two numbers together.\n\n    Args:\n        a: First number\n        b: Second number\n    \"\"\"\n    return str(a + b)\n\n# Run server\nasync def main():\n    async with stdio_server() as (read, write):\n        await server.run(read, write)\n\nif __name__ == \"__main__\":\n    import asyncio\n    asyncio.run(main())\n```\n\n### 3. Register with Claude\n\nAdd to `~/.claude/mcp.json`:\n```json\n{\n  \"mcpServers\": {\n    \"my-server\": {\n      \"command\": \"python3\",\n      \"args\": [\"/path/to/my_server.py\"]\n    }\n  }\n}\n```\n\n## TypeScript MCP Server\n\n### 1. Setup\n\n```bash\nmkdir my-mcp-server && cd my-mcp-server\nnpm init -y\nnpm install @modelcontextprotocol/sdk\n```\n\n### 2. Template\n\n```typescript\n// src/index.ts\nimport { Server } from \"@modelcontextprotocol/sdk/server/index.js\";\nimport { StdioServerTransport } from \"@modelcontextprotocol/sdk/server/stdio.js\";\n\nconst server = new Server({\n  name: \"my-server\",\n  version: \"1.0.0\",\n});\n\n// Define tools\nserver.setRequestHandler(\"tools/list\", async () => ({\n  tools: [\n    {\n      name: \"hello\",\n      description: \"Say hello to someone\",\n      inputSchema: {\n        type: \"object\",\n        properties: {\n          name: { type: \"string\", description: \"Name to greet\" },\n        },\n        required: [\"name\"],\n      },\n    },\n  ],\n}));\n\nserver.setRequestHandler(\"tools/call\", async (request) => {\n  if (request.params.name === \"hello\") {\n    const name = request.params.arguments.name;\n    return { content: [{ type: \"text\", text: `Hello, ${name}!` }] };\n  }\n  throw new Error(\"Unknown tool\");\n});\n\n// Start server\nconst transport = new StdioServerTransport();\nserver.connect(transport);\n```\n\n## Advanced Patterns\n\n### External API Integration\n\n```python\nimport httpx\nfrom mcp.server import Server\n\nserver = Server(\"weather-server\")\n\n@server.tool()\nasync def get_weather(city: str) -> str:\n    \"\"\"Get current weather for a city.\"\"\"\n    async with httpx.AsyncClient() as client:\n        resp = await client.get(\n            f\"https://api.weatherapi.com/v1/current.json\",\n            params={\"key\": \"YOUR_API_KEY\", \"q\": city}\n        )\n        data = resp.json()\n        return f\"{city}: {data['current']['temp_c']}C, {data['current']['condition']['text']}\"\n```\n\n### Database Access\n\n```python\nimport sqlite3\nfrom mcp.server import Server\n\nserver = Server(\"db-server\")\n\n@server.tool()\nasync def query_db(sql: str) -> str:\n    \"\"\"Execute a read-only SQL query.\"\"\"\n    if not sql.strip().upper().startswith(\"SELECT\"):\n        return \"Error: Only SELECT queries allowed\"\n\n    conn = sqlite3.connect(\"data.db\")\n    cursor = conn.execute(sql)\n    rows = cursor.fetchall()\n    conn.close()\n    return str(rows)\n```\n\n### Resources (Read-only Data)\n\n```python\n@server.resource(\"config://settings\")\nasync def get_settings() -> str:\n    \"\"\"Application settings.\"\"\"\n    return open(\"settings.json\").read()\n\n@server.resource(\"file://{path}\")\nasync def read_file(path: str) -> str:\n    \"\"\"Read a file from the workspace.\"\"\"\n    return open(path).read()\n```\n\n## Testing\n\n```bash\n# Test with MCP Inspector\nnpx @anthropics/mcp-inspector python3 my_server.py\n\n# Or send test messages directly\necho '{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"tools/list\"}' | python3 my_server.py\n```\n\n## Best Practices\n\n1. **Clear tool descriptions**: Claude uses these to decide when to call tools\n2. **Input validation**: Always validate and sanitize inputs\n3. **Error handling**: Return meaningful error messages\n4. **Async by default**: Use async/await for I/O operations\n5. **Security**: Never expose sensitive operations without auth\n6. **Idempotency**: Tools should be safe to retry\n","frontmatter":{"name":"mcp-builder","description":"Build MCP (Model Context Protocol) servers that give Claude new capabilities. Use when user wants to create an MCP server, add tools to Claude, or integrate external services."},"isInternal":false,"tokens":1216,"sizeBytes":4918},{"name":"SKILL.md","path":"skills/pdf/SKILL.md","rawUrl":"https://raw.githubusercontent.com/shareAI-lab/learn-claude-code/HEAD/skills/pdf/SKILL.md","title":"pdf","category":"anthropic-skill","format":"markdown","content":"---\nname: pdf\ndescription: Process PDF files - extract text, create PDFs, merge documents. Use when user asks to read PDF, create PDF, or work with PDF files.\n---\n\n# PDF Processing Skill\n\nYou now have expertise in PDF manipulation. Follow these workflows:\n\n## Reading PDFs\n\n**Option 1: Quick text extraction (preferred)**\n```bash\n# Using pdftotext (poppler-utils)\npdftotext input.pdf -  # Output to stdout\npdftotext input.pdf output.txt  # Output to file\n\n# If pdftotext not available, try:\npython3 -c \"\nimport fitz  # PyMuPDF\ndoc = fitz.open('input.pdf')\nfor page in doc:\n    print(page.get_text())\n\"\n```\n\n**Option 2: Page-by-page with metadata**\n```python\nimport fitz  # pip install pymupdf\n\ndoc = fitz.open(\"input.pdf\")\nprint(f\"Pages: {len(doc)}\")\nprint(f\"Metadata: {doc.metadata}\")\n\nfor i, page in enumerate(doc):\n    text = page.get_text()\n    print(f\"--- Page {i+1} ---\")\n    print(text)\n```\n\n## Creating PDFs\n\n**Option 1: From Markdown (recommended)**\n```bash\n# Using pandoc\npandoc input.md -o output.pdf\n\n# With custom styling\npandoc input.md -o output.pdf --pdf-engine=xelatex -V geometry:margin=1in\n```\n\n**Option 2: Programmatically**\n```python\nfrom reportlab.lib.pagesizes import letter\nfrom reportlab.pdfgen import canvas\n\nc = canvas.Canvas(\"output.pdf\", pagesize=letter)\nc.drawString(100, 750, \"Hello, PDF!\")\nc.save()\n```\n\n**Option 3: From HTML**\n```bash\n# Using wkhtmltopdf\nwkhtmltopdf input.html output.pdf\n\n# Or with Python\npython3 -c \"\nimport pdfkit\npdfkit.from_file('input.html', 'output.pdf')\n\"\n```\n\n## Merging PDFs\n\n```python\nimport fitz\n\nresult = fitz.open()\nfor pdf_path in [\"file1.pdf\", \"file2.pdf\", \"file3.pdf\"]:\n    doc = fitz.open(pdf_path)\n    result.insert_pdf(doc)\nresult.save(\"merged.pdf\")\n```\n\n## Splitting PDFs\n\n```python\nimport fitz\n\ndoc = fitz.open(\"input.pdf\")\nfor i in range(len(doc)):\n    single = fitz.open()\n    single.insert_pdf(doc, from_page=i, to_page=i)\n    single.save(f\"page_{i+1}.pdf\")\n```\n\n## Key Libraries\n\n| Task | Library | Install |\n|------|---------|---------|\n| Read/Write/Merge | PyMuPDF | `pip install pymupdf` |\n| Create from scratch | ReportLab | `pip install reportlab` |\n| HTML to PDF | pdfkit | `pip install pdfkit` + wkhtmltopdf |\n| Text extraction | pdftotext | `brew install poppler` / `apt install poppler-utils` |\n\n## Best Practices\n\n1. **Always check if tools are installed** before using them\n2. **Handle encoding issues** - PDFs may contain various character encodings\n3. **Large PDFs**: Process page by page to avoid memory issues\n4. **OCR for scanned PDFs**: Use `pytesseract` if text extraction returns empty\n","frontmatter":{"name":"pdf","description":"Process PDF files - extract text, create PDFs, merge documents. Use when user asks to read PDF, create PDF, or work with PDF files."},"isInternal":false,"tokens":724,"sizeBytes":2581}],"systemPromptSnippet":"<yakaai_skills repo=\"shareAI-lab/learn-claude-code\">\n<!-- File: skills/agent-builder/references/agent-philosophy.md (Tokens: ~1676 | Category: anthropic-skill) -->\n# The Philosophy of Agent Harness Engineering\n\n> **The model already knows how to be an agent. Your job is to build it a world worth acting in.**\n\n## The Fundamental Truth\n\nStrip away every framework, every library, every architectural pattern. What remains?\n\nA loop. A model. An invitation to act.\n\nThe agent is not the code. The agent is the model itself -- a vast neural network trained on humanity's collective problem-solving, reasoning, and tool use. The code merely provides the opportunity for the model to express its agency.\n\nThe code is the harness. The model is the agent. These are not interchangeable. Confuse them, and you will build the wrong thing.\n\n## What an Agent IS\n\nAn agent is a neural network -- a Transformer, an RNN, a learned function -- that has been trained, through billions of gradient updates on action-sequence data, to perceive an environment, reason about goals, and take actions to achieve them.\n\nA human is an agent: a biological neural network shaped by evolution. DeepMind's DQN is an agent: a convolutional network that learned to play Atari from raw pixels. OpenAI Five is an agent: five networks that learned Dota 2 teamwork through self-play. Claude is an agent: a language model that learned to reason and act from the breadth of human knowledge.\n\nIn every case, the agent is the trained model. Not the game engine. Not the Dota 2 client. Not the terminal. The model.\n\n## What an Agent Is NOT\n\nPrompt plumbing is not agency. Wiring together LLM API calls with if-else branches, node graphs, and hardcoded routing logic does not produce an agent. It produces a brittle pipeline -- a Rube Goldberg machine with an LLM wedged in as a text-completion node.\n\nYou cannot engineer your way to agency. Agency is learned, not programmed. No amount of glue code will emergently produce autonomous behavior. Those systems are the modern resurrection of GOFAI -- symbolic rule systems the field abandoned decades ago, now spray-painted with an LLM veneer.\n\n## The Harness: What We Actually Build\n\nIf the model is the agent, then what is the code? It is the **harness** -- the environment that gives the agent the ability to perceive and act in a specific domain.\n\n```\nHarness = Tools + Knowledge + Observation + Action Interfaces + Permissions\n```\n\n### Tools: The Agent's Hands\n\nTools answer: **What can the agent DO?**\n\nEach tool is an atomic action the agent can take in its environment. File read/write, shell execution, API calls, browser control, database queries. The model needs to understand what each tool does, but not how to sequence them -- it will figure that out.\n\n**Design principle**: Atomic, composable, well-described. Start with 3-5. Add more only when the model consistently fails to accomplish tasks because a tool is missing.\n\n### Knowledge: The Agent's Expertise\n\nKnowledge answers: **What does the agent KNOW?**\n\nDomain expertise that turns a general agent into a domain specialist. Product documentation, architectural decisions, regulatory requirements, style guides. Inject on-demand (via tool_result), not upfront (via system prompt). Progressive disclosure preserves context for what matters.\n\n**Design principle**: Available but not mandatory. The agent should know what knowledge exists and pull what it needs.\n\n### Context: The Agent's Memory\n\nContext is the thread connecting individual actions into coherent behavior. What has been said, tried, learned, and decided.\n\n**Design principle**: Context is precious. Protect it. Isolate subtasks that generate noise (s04). Compress when history grows long (s06). Persist goals beyond single conversations (s07).\n\n### Permissions: The Agent's Boundaries\n\nPermissions answer: **What is the agent ALLOWED to do?**\n\nSandbox file access. Require approval for destructive operations. Enforce trust boundaries between the agent and external systems. This is where safety engineering meets harness engineering.\n\n**Design principle**: Constraints focus behavior, not limit it. \"One task in_progress at a time\" forces sequential focus. \"Read-only subagent\" prevents accidental modifications.\n\n### Task-Process Data: The Agent's Training Signal\n\nEvery action sequence the agent executes in your harness is training signal. The perception-reasoning-action traces from real deployments are the raw material for fine-tuning the next generation of agent models. Your harness doesn't just serve the agent -- it can help evolve the agent.\n\n## The Universal Loop\n\nEvery effective agent -- regardless of domain -- follows the same pattern:\n\n```\nLOOP:\n  Model sees: conversation history + available tools\n  Model decides: act or respond\n  If act: tool executed, result added to context, loop continues\n  If respond: answer returned, loop ends\n```\n\nThis is not a simplification. This is the actual architecture. Everything else is harness engineering -- mechanisms layered on top of this loop to make the agent more effective. The loop belongs to the agent. The mechanisms belong to the harness.\n\n## Principles of Harness Engineering\n\n### Trust the Model\n\nThe most important principle: **trust the model**.\n\nDon't anticipate every edge case. Don't build elaborate decision trees. Don't pre-specify the workflow.\n\nThe model is better at reasoning than any rule system you could write. Your conditional logic will fail on edge cases. The model will reason through them.\n\n**Give the model tools and knowledge. Let it figure out how to use them.**\n\n### Constraints Enable\n\nThis seems paradoxical, but constraints don't limit agents -- they focus them.\n\nA todo list with \"only one task in progress\" forces sequential focus. A subagent with read-only access prevents accidental modifications. A context compression threshold keeps history from overwhelming.\n\nThe best constraints prevent the model from getting lost, not micromanage its approach.\n\n### Progressive Complexity\n\nNever build everything upfront.\n\n```\nLevel 0: Model + one tool (bash)                     -- s01\nLevel 1: Model + tool dispatch map                    -- s02\nLevel 2: Model + planning                             -- s03\nLevel 3: Model + subagents + skills                   -- s04, s05\nLevel 4: Model + context management + persistence     -- s06, s07, s08\nLevel 5: Model + teams + autonomy + isolation         -- s09-s12\n```\n\nStart at the lowest level that might work. Move up only when real usage reveals the need.\n\n## The Mind Shift\n\nBuilding harnesses requires a fundamental shift in thinking:\n\n**From**: \"How do I make the system do X?\"\n**To**: \"How do I enable the model to do X?\"\n\n**From**: \"What should happen when the user says Y?\"\n**To**: \"What tools would help address Y?\"\n\n**From**: \"What's the workflow for this task?\"\n**To**: \"What does the model need to figure out the workflow?\"\n\n**From**: \"I'm building an agent.\"\n**To**: \"I'm building a harness for the agent.\"\n\nThe best harness code is almost boring. Simple loops. Clear tool definitions. Clean context management. The magic isn't in the code -- it's in the model.\n\n## The Vehicle Metaphor\n\nThe model is the driver. The harness is the vehicle.\n\nA coding agent's vehicle is its IDE, terminal, and filesystem. A farm agent's vehicle is its sensor array, irrigation controls, and weather data. A hotel agent's vehicle is its booking system, guest channels, and facility APIs.\n\nThe driver generalizes. The vehicle specializes. Your job as a harness engineer is to build the best vehicle for your domain -- one that gives the driver maximum visibility, precise controls, and clear boundaries.\n\nBuild the cockpit. Build the dashboard. Build the controls. The pilot is already trained.\n\n## Conclusion\n\nThe model is the agent. The code is the harness. Know which one you're building.\n\nYou are not writing intelligence. You are building the world intelligence inhabits. The quality of that world -- how clearly the agent can perceive, how precisely it can act, how rich its knowledge -- directly determines how effectively the intelligence can express itself.\n\nBuild great harnesses. The agent will do the rest.\n\n<!-- File: skills/agent-builder/SKILL.md (Tokens: ~1061 | Category: anthropic-skill) -->\n---\nname: agent-builder\ndescription: |\n  Design and build AI agents for any domain. Use when users:\n  (1) ask to \"create an agent\", \"build an assistant\", or \"design an AI system\"\n  (2) want to understand agent architecture, agentic patterns, or autonomous AI\n  (3) need help with capabilities, subagents, planning, or skill mechanisms\n  (4) ask about Claude Code, Cursor, or similar agent internals\n  (5) want to build agents for business, research, creative, or operational tasks\n  Keywords: agent, assistant, autonomous, workflow, tool use, multi-step, orchestration\n---\n\n# Agent Builder\n\nBuild AI agents for any domain - customer service, research, operations, creative work, or specialized business processes.\n\n## The Core Philosophy\n\n> **The model already knows how to be an agent. Your job is to get out of the way.**\n\nAn agent is not complex engineering. It's a simple loop that invites the model to act:\n\n```\nLOOP:\n  Model sees: context + available capabilities\n  Model decides: act or respond\n  If act: execute capability, add result, continue\n  If respond: return to user\n```\n\n**That's it.** The magic isn't in the code - it's in the model. Your code just provides the opportunity.\n\n## The Three Elements\n\n### 1. Capabilities (What can it DO?)\n\nAtomic actions the agent can perform: search, read, create, send, query, modify.\n\n**Design principle**: Start with 3-5 capabilities. Add more only when the agent consistently fails because a capability is missing.\n\n### 2. Knowledge (What does it KNOW?)\n\nDomain expertise injected on-demand: policies, workflows, best practices, schemas.\n\n**Design principle**: Make knowledge available, not mandatory. Load it when relevant, not upfront.\n\n### 3. Context (What has happened?)\n\nThe conversation history - the thread connecting actions into coherent behavior.\n\n**Design principle**: Context is precious. Isolate noisy subtasks. Truncate verbose outputs. Protect clarity.\n\n## Agent Design Thinking\n\nBefore building, understand:\n\n- **Purpose**: What should this agent accomplish?\n- **Domain**: What world does it operate in? (customer service, research, operations, creative...)\n- **Capabilities**: What 3-5 actions are essential?\n- **Knowledge**: What expertise does it need access to?\n- **Trust**: What decisions can you delegate to the model?\n\n**CRITICAL**: Trust the model. Don't over-engineer. Don't pre-specify workflows. Give it capabilities and let it reason.\n\n## Progressive Complexity\n\nStart simple. Add complexity only when real usage reveals the need:\n\n| Level | What to add | When to add it |\n|-------|-------------|----------------|\n| Basic | 3-5 capabilities | Always start here |\n| Planning | Progress tracking | Multi-step tasks lose coherence |\n| Subagents | Isolated child agents | Exploration pollutes context |\n| Skills | On-demand knowledge | Domain expertise needed |\n\n**Most agents never need to go beyond Level 2.**\n\n## Domain Examples\n\n**Business**: CRM queries, email, calendar, approvals\n**Research**: Database search, document analysis, citations\n**Operations**: Monitoring, tickets, notifications, escalation\n**Creative**: Asset generation, editing, collaboration, review\n\nThe pattern is universal. Only the capabilities change.\n\n## Key Principles\n\n1. **The model IS the agent** - Code just runs the loop\n2. **Capabilities enable** - What it CAN do\n3. **Knowledge informs** - What it KNOWS how to do\n4. **Constraints focus** - Limits create clarity\n5. **Trust liberates** - Let the model reason\n6. **Iteration reveals** - Start minimal, evolve from usage\n\n## Anti-Patterns\n\n| Pattern | Problem | Solution |\n|---------|---------|----------|\n| Over-engineering | Complexity before need | Start simple |\n| Too many capabilities | Model confusion | 3-5 to start |\n| Rigid workflows | Can't adapt | Let model decide |\n| Front-loaded knowledge | Context bloat | Load on-demand |\n| Micromanagement | Undercuts intelligence | Trust the model |\n\n## Resources\n\n**Philosophy & Theory**:\n- `references/agent-philosophy.md` - Deep dive into why agents work\n\n**Implementation**:\n- `references/minimal-agent.py` - Complete working agent (~80 lines)\n- `references/tool-templates.py` - Capability definitions\n- `references/subagent-pattern.py` - Context isolation\n\n**Scaffolding**:\n- `scripts/init_agent.py` - Generate new agent projects\n\n## The Agent Mindset\n\n**From**: \"How do I make the system do X?\"\n**To**: \"How do I enable the model to do X?\"\n\n**From**: \"What's the workflow for this task?\"\n**To**: \"What capabilities would help accomplish this?\"\n\nThe best agent code is almost boring. Simple loops. Clear capabilities. Clean context. The magic isn't in the code.\n\n**Give the model capabilities and knowledge. Trust it to figure out the rest.**\n\n<!-- File: skills/code-review/SKILL.md (Tokens: ~1068 | Category: anthropic-skill) -->\n---\nname: code-review\ndescription: Perform thorough code reviews with security, performance, and maintainability analysis. Use when user asks to review code, check for bugs, or audit a codebase.\n---\n\n# Code Review Skill\n\nYou now have expertise in conducting comprehensive code reviews. Follow this structured approach:\n\n## Review Checklist\n\n### 1. Security (Critical)\n\nCheck for:\n- [ ] **Injection vulnerabilities**: SQL, command, XSS, template injection\n- [ ] **Authentication issues**: Hardcoded credentials, weak auth\n- [ ] **Authorization flaws**: Missing access controls, IDOR\n- [ ] **Data exposure**: Sensitive data in logs, error messages\n- [ ] **Cryptography**: Weak algorithms, improper key management\n- [ ] **Dependencies**: Known vulnerabilities (check with `npm audit`, `pip-audit`)\n\n```bash\n# Quick security scans\nnpm audit                    # Node.js\npip-audit                    # Python\ncargo audit                  # Rust\ngrep -r \"password\\|secret\\|api_key\" --include=\"*.py\" --include=\"*.js\"\n```\n\n### 2. Correctness\n\nCheck for:\n- [ ] **Logic errors**: Off-by-one, null handling, edge cases\n- [ ] **Race conditions**: Concurrent access without synchronization\n- [ ] **Resource leaks**: Unclosed files, connections, memory\n- [ ] **Error handling**: Swallowed exceptions, missing error paths\n- [ ] **Type safety**: Implicit conversions, any types\n\n### 3. Performance\n\nCheck for:\n- [ ] **N+1 queries**: Database calls in loops\n- [ ] **Memory issues**: Large allocations, retained references\n- [ ] **Blocking operations**: Sync I/O in async code\n- [ ] **Inefficient algorithms**: O(n^2) when O(n) possible\n- [ ] **Missing caching**: Repeated expensive computations\n\n### 4. Maintainability\n\nCheck for:\n- [ ] **Naming**: Clear, consistent, descriptive\n- [ ] **Complexity**: Functions > 50 lines, deep nesting > 3 levels\n- [ ] **Duplication**: Copy-pasted code blocks\n- [ ] **Dead code**: Unused imports, unreachable branches\n- [ ] **Comments**: Outdated, redundant, or missing where needed\n\n### 5. Testing\n\nCheck for:\n- [ ] **Coverage**: Critical paths tested\n- [ ] **Edge cases**: Null, empty, boundary values\n- [ ] **Mocking**: External dependencies isolated\n- [ ] **Assertions**: Meaningful, specific checks\n\n## Review Output Format\n\n```markdown\n## Code Review: [file/component name]\n\n### Summary\n[1-2 sentence overview]\n\n### Critical Issues\n1. **[Issue]** (line X): [Description]\n   - Impact: [What could go wrong]\n   - Fix: [Suggested solution]\n\n### Improvements\n1. **[Suggestion]** (line X): [Description]\n\n### Positive Notes\n- [What was done well]\n\n### Verdict\n[ ] Ready to merge\n[ ] Needs minor changes\n[ ] Needs major revision\n```\n\n## Common Patterns to Flag\n\n### Python\n```python\n# Bad: SQL injection\ncursor.execute(f\"SELECT * FROM users WHERE id = {user_id}\")\n# Good:\ncursor.execute(\"SELECT * FROM users WHERE id = ?\", (user_id,))\n\n# Bad: Command injection\nos.system(f\"ls {user_input}\")\n# Good:\nsubprocess.run([\"ls\", user_input], check=True)\n\n# Bad: Mutable default argument\ndef append(item, lst=[]):  # Bug: shared mutable default\n# Good:\ndef append(item, lst=None):\n    lst = lst or []\n```\n\n### JavaScript/TypeScript\n```javascript\n// Bad: Prototype pollution\nObject.assign(target, userInput)\n// Good:\nObject.assign(target, sanitize(userInput))\n\n// Bad: eval usage\neval(userCode)\n// Good: Never use eval with user input\n\n// Bad: Callback hell\ngetData(x => process(x, y => save(y, z => done(z))))\n// Good:\nconst data = await getData();\nconst processed = await process(data);\nawait save(processed);\n```\n\n## Review Commands\n\n```bash\n# Show recent changes\ngit diff HEAD~5 --stat\ngit log --oneline -10\n\n# Find potential issues\ngrep -rn \"TODO\\|FIXME\\|HACK\\|XXX\" .\ngrep -rn \"password\\|secret\\|token\" . --include=\"*.py\"\n\n# Check complexity (Python)\npip install radon && radon cc . -a\n\n# Check dependencies\nnpm outdated  # Node\npip list --outdated  # Python\n```\n\n## Review Workflow\n\n1. **Understand context**: Read PR description, linked issues\n2. **Run the code**: Build, test, run locally if possible\n3. **Read top-down**: Start with main entry points\n4. **Check tests**: Are changes tested? Do tests pass?\n5. **Security scan**: Run automated tools\n6. **Manual review**: Use checklist above\n7. **Write feedback**: Be specific, suggest fixes, be kind\n\n<!-- File: skills/mcp-builder/SKILL.md (Tokens: ~1216 | Category: anthropic-skill) -->\n---\nname: mcp-builder\ndescription: Build MCP (Model Context Protocol) servers that give Claude new capabilities. Use when user wants to create an MCP server, add tools to Claude, or integrate external services.\n---\n\n# MCP Server Building Skill\n\nYou now have expertise in building MCP (Model Context Protocol) servers. MCP enables Claude to interact with external services through a standardized protocol.\n\n## What is MCP?\n\nMCP servers expose:\n- **Tools**: Functions Claude can call (like API endpoints)\n- **Resources**: Data Claude can read (like files or database records)\n- **Prompts**: Pre-built prompt templates\n\n## Quick Start: Python MCP Server\n\n### 1. Project Setup\n\n```bash\n# Create project\nmkdir my-mcp-server && cd my-mcp-server\npython3 -m venv venv && source venv/bin/activate\n\n# Install MCP SDK\npip install mcp\n```\n\n### 2. Basic Server Template\n\n```python\n#!/usr/bin/env python3\n\"\"\"my_server.py - A simple MCP server\"\"\"\n\nfrom mcp.server import Server\nfrom mcp.server.stdio import stdio_server\nfrom mcp.types import Tool, TextContent\n\n# Create server instance\nserver = Server(\"my-server\")\n\n# Define a tool\n@server.tool()\nasync def hello(name: str) -> str:\n    \"\"\"Say hello to someone.\n\n    Args:\n        name: The name to greet\n    \"\"\"\n    return f\"Hello, {name}!\"\n\n@server.tool()\nasync def add_numbers(a: int, b: int) -> str:\n    \"\"\"Add two numbers together.\n\n    Args:\n        a: First number\n        b: Second number\n    \"\"\"\n    return str(a + b)\n\n# Run server\nasync def main():\n    async with stdio_server() as (read, write):\n        await server.run(read, write)\n\nif __name__ == \"__main__\":\n    import asyncio\n    asyncio.run(main())\n```\n\n### 3. Register with Claude\n\nAdd to `~/.claude/mcp.json`:\n```json\n{\n  \"mcpServers\": {\n    \"my-server\": {\n      \"command\": \"python3\",\n      \"args\": [\"/path/to/my_server.py\"]\n    }\n  }\n}\n```\n\n## TypeScript MCP Server\n\n### 1. Setup\n\n```bash\nmkdir my-mcp-server && cd my-mcp-server\nnpm init -y\nnpm install @modelcontextprotocol/sdk\n```\n\n### 2. Template\n\n```typescript\n// src/index.ts\nimport { Server } from \"@modelcontextprotocol/sdk/server/index.js\";\nimport { StdioServerTransport } from \"@modelcontextprotocol/sdk/server/stdio.js\";\n\nconst server = new Server({\n  name: \"my-server\",\n  version: \"1.0.0\",\n});\n\n// Define tools\nserver.setRequestHandler(\"tools/list\", async () => ({\n  tools: [\n    {\n      name: \"hello\",\n      description: \"Say hello to someone\",\n      inputSchema: {\n        type: \"object\",\n        properties: {\n          name: { type: \"string\", description: \"Name to greet\" },\n        },\n        required: [\"name\"],\n      },\n    },\n  ],\n}));\n\nserver.setRequestHandler(\"tools/call\", async (request) => {\n  if (request.params.name === \"hello\") {\n    const name = request.params.arguments.name;\n    return { content: [{ type: \"text\", text: `Hello, ${name}!` }] };\n  }\n  throw new Error(\"Unknown tool\");\n});\n\n// Start server\nconst transport = new StdioServerTransport();\nserver.connect(transport);\n```\n\n## Advanced Patterns\n\n### External API Integration\n\n```python\nimport httpx\nfrom mcp.server import Server\n\nserver = Server(\"weather-server\")\n\n@server.tool()\nasync def get_weather(city: str) -> str:\n    \"\"\"Get current weather for a city.\"\"\"\n    async with httpx.AsyncClient() as client:\n        resp = await client.get(\n            f\"https://api.weatherapi.com/v1/current.json\",\n            params={\"key\": \"YOUR_API_KEY\", \"q\": city}\n        )\n        data = resp.json()\n        return f\"{city}: {data['current']['temp_c']}C, {data['current']['condition']['text']}\"\n```\n\n### Database Access\n\n```python\nimport sqlite3\nfrom mcp.server import Server\n\nserver = Server(\"db-server\")\n\n@server.tool()\nasync def query_db(sql: str) -> str:\n    \"\"\"Execute a read-only SQL query.\"\"\"\n    if not sql.strip().upper().startswith(\"SELECT\"):\n        return \"Error: Only SELECT queries allowed\"\n\n    conn = sqlite3.connect(\"data.db\")\n    cursor = conn.execute(sql)\n    rows = cursor.fetchall()\n    conn.close()\n    return str(rows)\n```\n\n### Resources (Read-only Data)\n\n```python\n@server.resource(\"config://settings\")\nasync def get_settings() -> str:\n    \"\"\"Application settings.\"\"\"\n    return open(\"settings.json\").read()\n\n@server.resource(\"file://{path}\")\nasync def read_file(path: str) -> str:\n    \"\"\"Read a file from the workspace.\"\"\"\n    return open(path).read()\n```\n\n## Testing\n\n```bash\n# Test with MCP Inspector\nnpx @anthropics/mcp-inspector python3 my_server.py\n\n# Or send test messages directly\necho '{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"tools/list\"}' | python3 my_server.py\n```\n\n## Best Practices\n\n1. **Clear tool descriptions**: Claude uses these to decide when to call tools\n2. **Input validation**: Always validate and sanitize inputs\n3. **Error handling**: Return meaningful error messages\n4. **Async by default**: Use async/await for I/O operations\n5. **Security**: Never expose sensitive operations without auth\n6. **Idempotency**: Tools should be safe to retry\n\n<!-- File: skills/pdf/SKILL.md (Tokens: ~724 | Category: anthropic-skill) -->\n---\nname: pdf\ndescription: Process PDF files - extract text, create PDFs, merge documents. Use when user asks to read PDF, create PDF, or work with PDF files.\n---\n\n# PDF Processing Skill\n\nYou now have expertise in PDF manipulation. Follow these workflows:\n\n## Reading PDFs\n\n**Option 1: Quick text extraction (preferred)**\n```bash\n# Using pdftotext (poppler-utils)\npdftotext input.pdf -  # Output to stdout\npdftotext input.pdf output.txt  # Output to file\n\n# If pdftotext not available, try:\npython3 -c \"\nimport fitz  # PyMuPDF\ndoc = fitz.open('input.pdf')\nfor page in doc:\n    print(page.get_text())\n\"\n```\n\n**Option 2: Page-by-page with metadata**\n```python\nimport fitz  # pip install pymupdf\n\ndoc = fitz.open(\"input.pdf\")\nprint(f\"Pages: {len(doc)}\")\nprint(f\"Metadata: {doc.metadata}\")\n\nfor i, page in enumerate(doc):\n    text = page.get_text()\n    print(f\"--- Page {i+1} ---\")\n    print(text)\n```\n\n## Creating PDFs\n\n**Option 1: From Markdown (recommended)**\n```bash\n# Using pandoc\npandoc input.md -o output.pdf\n\n# With custom styling\npandoc input.md -o output.pdf --pdf-engine=xelatex -V geometry:margin=1in\n```\n\n**Option 2: Programmatically**\n```python\nfrom reportlab.lib.pagesizes import letter\nfrom reportlab.pdfgen import canvas\n\nc = canvas.Canvas(\"output.pdf\", pagesize=letter)\nc.drawString(100, 750, \"Hello, PDF!\")\nc.save()\n```\n\n**Option 3: From HTML**\n```bash\n# Using wkhtmltopdf\nwkhtmltopdf input.html output.pdf\n\n# Or with Python\npython3 -c \"\nimport pdfkit\npdfkit.from_file('input.html', 'output.pdf')\n\"\n```\n\n## Merging PDFs\n\n```python\nimport fitz\n\nresult = fitz.open()\nfor pdf_path in [\"file1.pdf\", \"file2.pdf\", \"file3.pdf\"]:\n    doc = fitz.open(pdf_path)\n    result.insert_pdf(doc)\nresult.save(\"merged.pdf\")\n```\n\n## Splitting PDFs\n\n```python\nimport fitz\n\ndoc = fitz.open(\"input.pdf\")\nfor i in range(len(doc)):\n    single = fitz.open()\n    single.insert_pdf(doc, from_page=i, to_page=i)\n    single.save(f\"page_{i+1}.pdf\")\n```\n\n## Key Libraries\n\n| Task | Library | Install |\n|------|---------|---------|\n| Read/Write/Merge | PyMuPDF | `pip install pymupdf` |\n| Create from scratch | ReportLab | `pip install reportlab` |\n| HTML to PDF | pdfkit | `pip install pdfkit` + wkhtmltopdf |\n| Text extraction | pdftotext | `brew install poppler` / `apt install poppler-utils` |\n\n## Best Practices\n\n1. **Always check if tools are installed** before using them\n2. **Handle encoding issues** - PDFs may contain various character encodings\n3. **Large PDFs**: Process page by page to avoid memory issues\n4. **OCR for scanned PDFs**: Use `pytesseract` if text extraction returns empty\n</yakaai_skills>"}