feat: Add installation tool, Claude.ai export, and skill standardization (#1)

## Summary - Add portable installation tool (`install.sh`) for cross-machine setup - Add Claude.ai export files with proper YAML frontmatter - Add multi-agent-guide v2.0 with consolidated framework template - Rename `00-claude-code-setting` → `00-our-settings-audit` (avoid reserved word) - Add YAML frontmatter to 25+ SKILL.md files for Claude Desktop compatibility ## Commits Included - `93f604a` feat: Add portable installation tool for cross-machine setup - `9b84104` feat: Add Claude.ai export for portable skill installation - `f7ab973` fix: Add YAML frontmatter to Claude.ai export files - `3fed49a` feat(multi-agent-guide): Add v2.0 with consolidated framework - `3be26ef` refactor: Rename settings-audit skill and add YAML frontmatter Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2026-02-03 16:48:06 +07:00
parent 0bc24d00b9
commit b6a478e1df
72 changed files with 4770 additions and 803 deletions
--- a/custom-skills/00-our-settings-audit/desktop/references/config-locations.md
+++ b/custom-skills/00-our-settings-audit/desktop/references/config-locations.md
@@ -0,0 +1,77 @@
+# Claude Desktop Configuration Locations
+
+## Primary Config File
+
+### macOS
+```
+~/Library/Application Support/Claude/claude_desktop_config.json
+```
+
+### Windows
+```
+%APPDATA%\Claude\claude_desktop_config.json
+```
+
+### Linux
+```
+~/.config/Claude/claude_desktop_config.json
+```
+
+## MCP Server Configuration Example
+
+```json
+{
+  "mcpServers": {
+    "playwright": {
+      "command": "npx",
+      "args": ["-y", "@anthropic-ai/mcp-playwright"],
+      "serverInstructions": "Browser automation. Use for: screenshots, page testing, DOM inspection. Keywords: browser, page, screenshot, navigate"
+    },
+    "notion": {
+      "command": "npx",
+      "args": ["-y", "@anthropic-ai/mcp-notion", "--token", "YOUR_TOKEN"],
+      "serverInstructions": "Notion workspace access. Use for: search pages, create content, update databases. Keywords: notion, page, database, workspace"
+    }
+  }
+}
+```
+
+## Key Fields
+
+| Field | Purpose | Token Impact |
+|-------|---------|--------------|
+| `command` | Executable path | Minimal |
+| `args` | Arguments | Minimal |
+| `serverInstructions` | Usage hints | Reduces discovery overhead |
+| `env` | Environment vars | None |
+
+## serverInstructions Best Practices
+
+**Good:**
+```json
+"serverInstructions": "File system access. Use for: read/write files, directory listing. Keywords: file, read, write, directory"
+```
+
+**Bad (too vague):**
+```json
+"serverInstructions": "Various file operations"
+```
+
+**Bad (too long):**
+```json
+"serverInstructions": "This MCP server provides comprehensive file system access capabilities including reading files, writing files, creating directories, listing directory contents, and more. It can be used for any operation that requires..."
+```
+
+## Viewing Current Configuration
+
+Ask user to run:
+
+**macOS/Linux:**
+```bash
+cat ~/Library/Application\ Support/Claude/claude_desktop_config.json | python3 -m json.tool
+```
+
+**Windows (PowerShell):**
+```powershell
+Get-Content "$env:APPDATA\Claude\claude_desktop_config.json" | ConvertFrom-Json | ConvertTo-Json -Depth 10
+```
--- a/custom-skills/00-our-settings-audit/desktop/references/mcp-token-estimates.md
+++ b/custom-skills/00-our-settings-audit/desktop/references/mcp-token-estimates.md
@@ -0,0 +1,88 @@
+# MCP Server Token Estimates
+
+Approximate token usage for common MCP servers when loaded.
+
+## Official Anthropic Servers
+
+| Server | Tools | Tokens (est.) | Recommendation |
+|--------|-------|---------------|----------------|
+| Playwright | 20+ | 13,500 | Keep if testing |
+| Filesystem | 8 | 4,000 | Essential |
+| Memory | 5 | 3,000 | Optional |
+| Brave Search | 2 | 1,500 | Alternative to web |
+| Fetch | 2 | 1,200 | Keep for web access |
+
+## Third-Party Servers
+
+| Server | Tools | Tokens (est.) | Recommendation |
+|--------|-------|---------------|----------------|
+| Notion | 10 | 5,000 | Keep if using Notion |
+| GitHub | 25+ | 18,000 | Lazy load only |
+| PostgreSQL | 15 | 8,000 | Lazy load only |
+| Slack | 12 | 6,000 | Lazy load only |
+| Figma | 15 | 10,000 | Lazy load only |
+| Zapier | 50+ | 25,000+ | **Avoid** |
+| Firecrawl | 5 | 3,500 | Useful for SEO |
+| Perplexity | 2 | 1,500 | Alternative to web |
+
+## Token Budget Guidelines
+
+### Conservative Setup (High Available Context)
+```
+2-3 essential MCP servers
+Total: ~10,000-15,000 tokens
+Available: 185,000+ tokens (92%+)
+```
+
+### Standard Setup
+```
+4-5 MCP servers
+Total: ~20,000-30,000 tokens
+Available: 170,000+ tokens (85%+)
+```
+
+### Heavy Setup (Risk Zone)
+```
+6+ MCP servers
+Total: 40,000+ tokens
+Available: <160,000 tokens (<80%)
+⚠️ Higher chance of "Exceed response limit"
+```
+
+## Reduction Strategies
+
+### If using GitHub MCP heavily:
+- Start conversation specifically for GitHub work
+- Don't load other heavy servers simultaneously
+
+### If using multiple API servers:
+- Choose ONE per category:
+  - Web search: Brave OR Perplexity (not both)
+  - Automation: Zapier OR n8n (not both)
+  - Database: PostgreSQL OR MySQL (not both)
+
+### If testing/development:
+- Playwright OR Puppeteer (not both)
+- Load only when actively testing
+
+## Impact of serverInstructions
+
+**Without serverInstructions:**
+- Full tool schemas loaded (~500 tokens per tool)
+- Discovery overhead on each interaction
+
+**With serverInstructions:**
+- Reduced discovery queries
+- More efficient tool selection
+- Saves ~30-50% on tool-related tokens
+
+## Quick Reference
+
+**Token estimation formula:**
+```
+Server tokens ≈ (number of tools × 400) + 500 base
+```
+
+**Example:**
+- 10 tools = (10 × 400) + 500 = 4,500 tokens
+- 25 tools = (25 × 400) + 500 = 10,500 tokens
--- a/custom-skills/00-our-settings-audit/desktop/references/our-settings-audit.md
+++ b/custom-skills/00-our-settings-audit/desktop/references/our-settings-audit.md
@@ -0,0 +1,349 @@
+# Claude Settings Audit Guide
+
+> **Purpose**: Condensed reference for Claude.ai Projects
+> **Source**: 00-claude-settings-audit skill
+> **Version**: 1.0
+
+Comprehensive reference for diagnosing Claude Desktop errors and optimizing context usage.
+
+## Error Quick Reference
+
+| Error Type | Message Pattern | Category |
+|------------|-----------------|----------|
+| Context too large | "Exceed response limit" | Input |
+| Output interrupted | "Response could not be fully generated" | Output |
+| Length exceeded | "Message will exceed the length limit" | Input |
+| Conversation limit | "Conversation reached maximum length" | Input |
+| File too large | "Files larger than 10mb" | File |
+| Rate limited | "5-hour limit reached" | Usage |
+| Server overload | "Unexpected capacity constraints" | Server |
+| MCP failure | "Error connecting to [ServerName]" | MCP |
+| Account issue | "Account has been disabled" | Account |
+
+## Quick Diagnosis Tree
+
+```
+Error occurred?
+│
+├─ BEFORE response started?
+│   ├─ "Exceed response limit" → Reduce input context
+│   ├─ "Length limit" → Break into smaller messages
+│   ├─ "File too large" → Reduce file size or excerpt
+│   ├─ "Capacity constraints" → Wait and retry
+│   └─ "MCP error" → Check MCP configuration
+│
+├─ DURING response?
+│   ├─ "Could not be fully generated" → Request smaller output
+│   └─ Output suddenly stopped → Retry or chunk request
+│
+└─ BEFORE even sending?
+    ├─ "5-hour limit reached" → Wait for reset
+    ├─ "Messages left" → Near usage limit
+    └─ "Account disabled" → Contact support
+```
+
+---
+
+## Token Limits by Model
+
+| Model | Context Window | Output Limit | Practical Available |
+|-------|---------------|--------------|---------------------|
+| Claude 3.5 Sonnet | 200K tokens | ~8K tokens | ~150K after system |
+| Claude 3 Opus | 200K tokens | ~4K tokens | ~150K after system |
+| Claude 3 Haiku | 200K tokens | ~4K tokens | ~160K after system |
+
+---
+
+# ERROR CATEGORIES
+
+## 1. Input/Context Errors
+
+### "Exceed response limit"
+
+**Causes:**
+- Loaded context too large (MCP tools + skills + files)
+- Conversation history accumulated
+- Multiple large files attached
+
+**Solutions:**
+1. Reduce MCP servers (max 5 recommended)
+2. Add `serverInstructions` to all MCP servers
+3. Start fresh conversation
+4. Attach file excerpts instead of full files
+
+### "Message will exceed the length limit"
+
+**Solutions:**
+1. Break content into smaller chunks
+2. Summarize key sections before sending
+3. Start a new conversation
+
+### "Conversation reached maximum length"
+
+**Solutions:**
+1. Start a new conversation
+2. Copy essential context to new chat
+
+---
+
+## 2. Output Errors
+
+### "Response could not be fully generated"
+
+**Causes:**
+- Output exceeded ~4K-8K token limit
+- Safety filter triggered
+- Network interruption
+- Server timeout
+
+**Solutions:**
+1. Request smaller chunks of output
+2. Add constraints: "In under 500 words..."
+3. Be more specific in scope
+4. Retry once before rephrasing
+
+**Prompting techniques:**
+- "Provide a concise summary..."
+- "List the top 10..."
+- "First, outline the structure"
+- "Use bullet points, not paragraphs"
+
+---
+
+## 3. File Errors
+
+### "Files larger than 10MB"
+
+**Solutions:**
+1. Compress file if possible
+2. Split into smaller files
+3. Extract text content only
+
+### "Message is X% over the length limit"
+
+**Solutions:**
+1. Extract relevant excerpts only
+2. Summarize large documents
+3. Split across multiple messages
+
+---
+
+## 4. Usage Limit Errors
+
+### "5-hour limit reached"
+
+**Solutions:**
+1. Wait until reset time shown
+2. Upgrade plan for higher limits
+3. Optimize prompts to use fewer tokens
+
+### "X messages left until [time]"
+
+**Solutions:**
+1. Combine multiple questions into one
+2. Wait for reset
+3. Consider paid plan
+
+---
+
+## 5. Server/Capacity Errors
+
+### "Unexpected capacity constraints"
+
+**Solutions:**
+1. Wait 2-5 minutes and retry
+2. Try during off-peak hours
+3. Check status.claude.com for incidents
+
+### HTTP Error Codes
+
+| Code | Meaning | Solution |
+|------|---------|----------|
+| 500 | Internal Server Error | Wait and retry |
+| 429 | Too Many Requests | Slow down, wait |
+| 403 | Forbidden | Check account status |
+| 400 | Bad Request | Check input format |
+
+---
+
+## 6. MCP Connection Errors
+
+### "Error connecting to [ServerName]"
+
+**Causes:**
+1. Server not running
+2. Incorrect configuration
+3. Transport type mismatch (stdio vs HTTP)
+4. Authentication failure
+
+**Diagnosis steps:**
+1. Check server logs:
+   - macOS: `~/Library/Logs/Claude/mcp-server-SERVERNAME.log`
+   - Windows: `%APPDATA%\Claude\logs\mcp-server-SERVERNAME.log`
+
+2. Verify configuration in `claude_desktop_config.json`
+
+3. Test server independently
+
+**Common fixes:**
+
+| Issue | Fix |
+|-------|-----|
+| Transport mismatch | Add `"transport": "http"` to config |
+| Path with spaces | Use escaped paths |
+| Missing env vars | Add to `"env"` in config |
+| Server not installed | Run `npm install -g` first |
+
+**Critical:** Restart Claude Desktop after config changes.
+
+---
+
+## 7. Account Errors
+
+### "Account has been disabled"
+
+**Solutions:**
+1. Contact Anthropic support
+2. Review Terms of Service
+3. Do not create new accounts
+
+### "Error logging you in"
+
+**Solutions:**
+1. Disable VPN
+2. Clear browser cache and cookies
+3. Try incognito window
+4. Check status.claude.com
+
+---
+
+## 8. Output Quality Issues
+
+### Output Suddenly Stops
+
+**Solutions:**
+1. Ask "Please continue from where you stopped"
+2. Request smaller chunks upfront
+3. Be more specific in scope
+
+### Gibberish Output
+
+**Solutions:**
+1. Simplify prompt
+2. Start new conversation
+3. Rephrase request differently
+
+### Claude Refuses to Respond
+
+**Solutions:**
+1. Rephrase more clearly
+2. Explain legitimate use case
+3. Break into smaller requests
+
+---
+
+# TOKEN BUDGET GUIDELINES
+
+## MCP Server Token Estimates
+
+| Server | Tokens (approx) |
+|--------|-----------------|
+| Playwright | ~13,500 |
+| Notion | ~5,000 |
+| GitHub | ~18,000 |
+| Filesystem | ~4,000 |
+| Zapier | ~25,000+ (avoid) |
+
+## serverInstructions Pattern
+
+Every MCP server should have:
+
+```json
+"serverInstructions": "[Purpose]. Use for: [case1], [case2]. Keywords: [kw1], [kw2]"
+```
+
+Example:
+```json
+"serverInstructions": "Browser automation. Use for: screenshots, page testing. Keywords: browser, DOM, screenshot"
+```
+
+## Budget Calculator
+
+```
+System overhead:        ~10,000 tokens (fixed)
+MCP servers:            [count] × ~3,000 = [estimate]
+Loaded skills:          [count] × ~500 = [estimate]
+Project instructions:   ~[estimate]
+────────────────────────────────────────────
+Baseline total:         [sum]
+Available for work:     200,000 - [sum] = [remaining]
+```
+
+**Targets:**
+- Baseline: < 40,000 tokens (20%)
+- Available: > 160,000 tokens (80%)
+
+---
+
+# PREVENTION CHECKLIST
+
+## Context/Input
+- [ ] Maximum 5 MCP servers active
+- [ ] All servers have serverInstructions
+- [ ] Skills under 1,000 words
+- [ ] Start fresh conversations for new topics
+- [ ] Files under 10MB, prefer excerpts
+
+## Output
+- [ ] Break large requests into chunks
+- [ ] Use specific scope in prompts
+- [ ] Paginate lists (50 items max)
+- [ ] Retry once before rephrasing
+
+## Usage Limits
+- [ ] Monitor "messages left" warnings
+- [ ] Combine related questions
+- [ ] Use concise prompts
+
+## MCP Stability
+- [ ] Test servers before adding
+- [ ] Restart app after config changes
+- [ ] Keep servers updated
+
+## General
+- [ ] Check status.claude.com when issues occur
+- [ ] Keep Claude Desktop updated
+- [ ] Back up important conversations
+
+---
+
+# CONFIGURATION LOCATIONS
+
+## Config Files
+
+**macOS:**
+```
+~/Library/Application Support/Claude/claude_desktop_config.json
+```
+
+**Windows:**
+```
+%APPDATA%\Claude\claude_desktop_config.json
+```
+
+## Log Files
+
+**macOS:**
+```
+~/Library/Logs/Claude/mcp-server-SERVERNAME.log
+```
+
+**Windows:**
+```
+%APPDATA%\Claude\logs\mcp-server-SERVERNAME.log
+```
+
+---
+
+*Reference: Claude Settings Audit Skill v1.0*
+*Last updated: 2025-02*