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>
This commit is contained in:
Andrew Yim
633
custom-skills/00-our-settings-audit/desktop/SKILL.md
Normal file
633
custom-skills/00-our-settings-audit/desktop/SKILL.md
Normal file
@@ -0,0 +1,633 @@
|
||||
---
|
||||
name: our-settings-audit
|
||||
description: |
|
||||
Diagnose all Claude Desktop errors and optimize context usage.
|
||||
Covers 8 error categories: context limits, output interruption,
|
||||
length/file errors, usage limits, server capacity, MCP connection,
|
||||
account issues, and output quality problems.
|
||||
Triggers: settings audit, exceed response limit, MCP error, token error.
|
||||
---
|
||||
|
||||
# Claude Desktop Settings Checker
|
||||
|
||||
Diagnose Claude Desktop errors and optimize 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 | "This conversation reached its maximum length" | Input |
|
||||
| File too large | "Files larger than 10mb" / "X% over the length limit" | File |
|
||||
| Rate limited | "5-hour limit reached" / "X messages left" | Usage |
|
||||
| Server overload | "Due to 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
|
||||
```
|
||||
|
||||
## Understanding Token Limits
|
||||
|
||||
| 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 |
|
||||
|
||||
---
|
||||
|
||||
# CATEGORY 1: Input/Context Errors
|
||||
|
||||
## Error: "Exceed response limit"
|
||||
|
||||
**Causes:**
|
||||
1. Loaded context too large (MCP tools + skills + files)
|
||||
2. Conversation history accumulated
|
||||
3. Multiple large files attached
|
||||
|
||||
## Quick Diagnosis
|
||||
|
||||
When user reports "Exceed response limit":
|
||||
|
||||
### Step 1: Check Loaded Context
|
||||
|
||||
Ask user to share their `claude_desktop_config.json`:
|
||||
- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
|
||||
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
|
||||
|
||||
Analyze:
|
||||
- [ ] Number of MCP servers configured
|
||||
- [ ] Servers with many tools (>20 tools each)
|
||||
- [ ] Missing or poor `serverInstructions`
|
||||
|
||||
### Step 2: Estimate Token Usage
|
||||
|
||||
| Component | Tokens (approx) | Notes |
|
||||
|-----------|-----------------|-------|
|
||||
| Per MCP server | 500-2,000 | Base overhead |
|
||||
| Per tool definition | 100-500 | Depends on schema complexity |
|
||||
| Playwright MCP | ~13,500 | 20+ tools, detailed schemas |
|
||||
| Notion MCP | ~5,000 | Moderate |
|
||||
| GitHub MCP | ~18,000 | Many tools |
|
||||
| Custom SKILL.md | 200-2,000 | Depends on length |
|
||||
| Attached file | Variable | ~4 tokens per word |
|
||||
|
||||
**Red flags:**
|
||||
- More than 5 MCP servers active
|
||||
- Any server without `serverInstructions`
|
||||
- Total MCP tools > 100
|
||||
|
||||
### Step 3: Review Loaded Skills
|
||||
|
||||
Check for:
|
||||
- Skills with long SKILL.md files (>1,000 words)
|
||||
- Multiple skills loaded simultaneously
|
||||
- Skills with embedded reference data
|
||||
|
||||
## Optimization Recommendations
|
||||
|
||||
### MCP Server Optimization
|
||||
|
||||
**Priority 1: Add serverInstructions**
|
||||
|
||||
Every MCP server needs concise instructions:
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"playwright": {
|
||||
"command": "...",
|
||||
"serverInstructions": "Browser automation for web testing. Use for: screenshots, page analysis, form testing. Keywords: browser, DOM, screenshot"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Pattern: `[Purpose]. Use for: [case1], [case2]. Keywords: [kw1], [kw2]`
|
||||
|
||||
**Priority 2: Reduce Active Servers**
|
||||
|
||||
Keep only essential servers active. Disable or remove:
|
||||
- Servers used less than weekly
|
||||
- Servers with overlapping functionality
|
||||
- Servers with 30+ tools (like Zapier)
|
||||
|
||||
### Conversation Management
|
||||
|
||||
**Before complex tasks:**
|
||||
1. Start fresh conversation for unrelated work
|
||||
2. Avoid attaching multiple large files
|
||||
3. Request concise outputs
|
||||
|
||||
**During long sessions:**
|
||||
1. Start new conversation at natural breakpoints
|
||||
2. Summarize important context before continuing
|
||||
3. Remove completed file attachments
|
||||
|
||||
### Project File Optimization
|
||||
|
||||
For project skills and configurations:
|
||||
|
||||
| File Type | Target Length | Max |
|
||||
|-----------|--------------|-----|
|
||||
| SKILL.md | 500 words | 1,000 words |
|
||||
| Project instructions | 200 words | 500 words |
|
||||
| Embedded data | 0 | Move to external |
|
||||
|
||||
**Optimization techniques:**
|
||||
1. Move reference data to separate files (load on demand)
|
||||
2. Use tables instead of prose
|
||||
3. Remove redundant information
|
||||
4. Link to documentation instead of embedding
|
||||
|
||||
## Token Budget Calculator
|
||||
|
||||
Help user calculate their baseline:
|
||||
|
||||
```
|
||||
System overhead: ~10,000 tokens (fixed)
|
||||
MCP servers: [count] × ~3,000 = [estimate]
|
||||
Loaded skills: [count] × ~500 = [estimate]
|
||||
Project instructions: ~[estimate based on length]
|
||||
────────────────────────────────────────────────
|
||||
Baseline total: [sum]
|
||||
Available for work: 200,000 - [sum] = [remaining]
|
||||
Available percentage: [remaining/200,000 × 100]%
|
||||
```
|
||||
|
||||
**Targets:**
|
||||
- Baseline: < 40,000 tokens (20%)
|
||||
- Available: > 160,000 tokens (80%)
|
||||
|
||||
**Warning zone:**
|
||||
- Baseline > 60,000 tokens: Likely to hit limits
|
||||
- Available < 140,000 tokens: Reduce configuration
|
||||
|
||||
## Output Format
|
||||
|
||||
After diagnosis, provide:
|
||||
|
||||
```markdown
|
||||
## Settings Check Report
|
||||
|
||||
### Configuration Summary
|
||||
- MCP Servers: [count] ([tokens estimate])
|
||||
- Active Skills: [count] ([tokens estimate])
|
||||
- Baseline Total: ~[X] tokens ([Y]%)
|
||||
- Available: ~[Z] tokens ([W]%)
|
||||
|
||||
### Issues Found
|
||||
1. [Critical]: [issue description]
|
||||
2. [Warning]: [issue description]
|
||||
|
||||
### Recommended Actions
|
||||
1. [Action with specific steps]
|
||||
2. [Action with specific steps]
|
||||
|
||||
### Quick Wins (immediate impact)
|
||||
- [ ] [Specific change]
|
||||
- [ ] [Specific change]
|
||||
```
|
||||
|
||||
## Common Scenarios
|
||||
|
||||
### Scenario: Too Many MCP Servers
|
||||
|
||||
**Symptoms:** Errors on first message of conversation
|
||||
**Solution:** Disable non-essential servers, add serverInstructions
|
||||
|
||||
### Scenario: Long Conversation History
|
||||
|
||||
**Symptoms:** Errors after many exchanges
|
||||
**Solution:** Start new conversation, summarize context
|
||||
|
||||
### Scenario: Large File Attachments
|
||||
|
||||
**Symptoms:** Errors when attaching files
|
||||
**Solution:** Attach smaller excerpts, use file references
|
||||
|
||||
### Scenario: Complex Skill Loaded
|
||||
|
||||
**Symptoms:** Errors when using specific skill
|
||||
**Solution:** Refactor skill, move data to references
|
||||
|
||||
---
|
||||
|
||||
## Error 2: "Response could not be fully generated"
|
||||
|
||||
This error occurs when **output generation** is interrupted mid-stream.
|
||||
|
||||
### Causes
|
||||
|
||||
| Cause | Description | Frequency |
|
||||
|-------|-------------|-----------|
|
||||
| **Output token limit** | Response exceeded ~4K-8K output limit | Common |
|
||||
| **Safety filter** | Content flagged during generation | Occasional |
|
||||
| **Network interruption** | Connection dropped mid-stream | Occasional |
|
||||
| **Server timeout** | Generation took too long | Rare |
|
||||
| **Rate limiting** | Too many requests in short time | Rare |
|
||||
|
||||
### Common Triggers
|
||||
|
||||
**1. Requesting too much output:**
|
||||
```
|
||||
❌ "Write a complete 50-page report on..."
|
||||
❌ "Generate the entire application code"
|
||||
❌ "List all 500 items with full descriptions"
|
||||
|
||||
✅ "Write section 1: introduction and overview"
|
||||
✅ "Generate the authentication module first"
|
||||
✅ "List items 1-50 with descriptions"
|
||||
```
|
||||
|
||||
**2. Vague prompts (produce longer responses):**
|
||||
```
|
||||
❌ "Explain everything about machine learning"
|
||||
✅ "Explain gradient descent in 3 paragraphs"
|
||||
```
|
||||
|
||||
**3. Code generation without scope:**
|
||||
```
|
||||
❌ "Build me a full-stack e-commerce site"
|
||||
✅ "Create the product listing component with pagination"
|
||||
```
|
||||
|
||||
### Solutions
|
||||
|
||||
| Situation | Fix |
|
||||
|-----------|-----|
|
||||
| Long report/document | Request section by section |
|
||||
| Large codebase | Generate module by module |
|
||||
| Comprehensive list | Paginate (1-50, 51-100, etc.) |
|
||||
| Detailed explanation | Ask for "brief" or "concise" version |
|
||||
| Transient failure | Simply retry the request |
|
||||
|
||||
### Prompting Techniques
|
||||
|
||||
**Add output constraints:**
|
||||
- "In under 500 words..."
|
||||
- "Provide a concise summary..."
|
||||
- "List the top 10..."
|
||||
- "Focus only on..."
|
||||
|
||||
**Chunk large tasks:**
|
||||
- "First, outline the structure"
|
||||
- "Now write section 1"
|
||||
- "Continue with section 2"
|
||||
|
||||
**Request format control:**
|
||||
- "Use bullet points, not paragraphs"
|
||||
- "Provide a table summary"
|
||||
- "Give me just the key points"
|
||||
|
||||
### When to Retry vs. Rephrase
|
||||
|
||||
| Scenario | Action |
|
||||
|----------|--------|
|
||||
| Error on first attempt | Retry once |
|
||||
| Error persists after retry | Rephrase with smaller scope |
|
||||
| Error always at same point | Content may be triggering filter |
|
||||
| Error after long generation | Request was too ambitious |
|
||||
|
||||
---
|
||||
|
||||
# CATEGORY 3: Length & File Errors
|
||||
|
||||
## Error: "Your message will exceed the length limit"
|
||||
|
||||
**Full message:** "Your message will exceed the length limit for this chat..."
|
||||
|
||||
**Causes:**
|
||||
- Single message too long (approaching context limit)
|
||||
- Too much text pasted at once
|
||||
|
||||
**Solutions:**
|
||||
1. Break content into smaller chunks
|
||||
2. Summarize key sections before sending
|
||||
3. Ask Claude to identify relevant portions first
|
||||
4. Start a new conversation
|
||||
|
||||
## Error: "This conversation reached its maximum length"
|
||||
|
||||
**Cause:** Accumulated conversation history filled context window
|
||||
|
||||
**Solutions:**
|
||||
1. Start a new conversation
|
||||
2. Copy essential context to new chat
|
||||
3. Use shorter exchanges going forward
|
||||
|
||||
## Error: "Message is X% over the length limit"
|
||||
|
||||
**Full message:** "Message is X% over the length limit. Try replacing the attached file with smaller excerpts."
|
||||
|
||||
**Cause:** Attached file(s) too large for remaining context
|
||||
|
||||
**Solutions:**
|
||||
1. Extract relevant excerpts only
|
||||
2. Summarize large documents before attaching
|
||||
3. Split across multiple messages
|
||||
4. Use file references instead of full content
|
||||
|
||||
## Error: "You may not upload files larger than 10MB"
|
||||
|
||||
**Cause:** Single file exceeds 10MB limit
|
||||
|
||||
**Solutions:**
|
||||
1. Compress file if possible
|
||||
2. Split into smaller files
|
||||
3. Extract text content only
|
||||
4. Use external link and describe content
|
||||
|
||||
---
|
||||
|
||||
# CATEGORY 4: Usage & Rate Limit Errors
|
||||
|
||||
## Error: "5-hour limit reached - resets [time]"
|
||||
|
||||
**Cause:** Hit plan's usage cap within 5-hour window
|
||||
|
||||
**Solutions:**
|
||||
1. Wait until reset time shown
|
||||
2. Upgrade plan for higher limits
|
||||
3. Optimize prompts to use fewer tokens
|
||||
|
||||
## Error: "Approaching 5-hour limit"
|
||||
|
||||
**Cause:** Warning before hitting limit
|
||||
|
||||
**Solutions:**
|
||||
1. Prioritize remaining important tasks
|
||||
2. Use concise prompts
|
||||
3. Avoid exploratory conversations
|
||||
|
||||
## Error: "X messages left until [time]"
|
||||
|
||||
**Cause:** Near message limit (free tier)
|
||||
|
||||
**Solutions:**
|
||||
1. Combine multiple questions into one
|
||||
2. Wait for reset
|
||||
3. Consider paid plan
|
||||
|
||||
## Error: "5-hour limit resets [time] - continuing with extra usage"
|
||||
|
||||
**Note:** This is informational for paid plans with extra usage enabled
|
||||
**Action:** Extra usage automatically continues; monitor costs
|
||||
|
||||
---
|
||||
|
||||
# CATEGORY 5: Server & Capacity Errors
|
||||
|
||||
## Error: "Due to unexpected capacity constraints, Claude is unable to respond"
|
||||
|
||||
**Cause:** High system-wide demand
|
||||
|
||||
**Solutions:**
|
||||
1. Wait 2-5 minutes and retry
|
||||
2. Try during off-peak hours
|
||||
3. Check [status.claude.com](https://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 |
|
||||
|
||||
## Error: "Claude AI Saving Chat Failed"
|
||||
|
||||
**Cause:** Issue saving conversation to servers
|
||||
|
||||
**Solutions:**
|
||||
1. Refresh the page
|
||||
2. Check internet connection
|
||||
3. Copy important content locally
|
||||
4. Try again later
|
||||
|
||||
---
|
||||
|
||||
# CATEGORY 6: MCP Connection Errors
|
||||
|
||||
## Error: "There was an error connecting to [ServerName]"
|
||||
|
||||
**Causes:**
|
||||
1. Server not running
|
||||
2. Incorrect configuration
|
||||
3. Transport type mismatch (stdio vs HTTP)
|
||||
4. Authentication failure
|
||||
|
||||
### Diagnosis Steps
|
||||
|
||||
**Step 1: Check server logs**
|
||||
- macOS: `~/Library/Logs/Claude/mcp-server-SERVERNAME.log`
|
||||
- Windows: `%APPDATA%\Claude\logs\mcp-server-SERVERNAME.log`
|
||||
|
||||
**Step 2: Verify configuration**
|
||||
```bash
|
||||
# macOS
|
||||
cat ~/Library/Application\ Support/Claude/claude_desktop_config.json
|
||||
|
||||
# Windows PowerShell
|
||||
Get-Content "$env:APPDATA\Claude\claude_desktop_config.json"
|
||||
```
|
||||
|
||||
**Step 3: Test server independently**
|
||||
```bash
|
||||
# Test if server starts
|
||||
npx @anthropic-ai/mcp-server-name
|
||||
```
|
||||
|
||||
### Common MCP Issues
|
||||
|
||||
| Issue | Symptom | Fix |
|
||||
|-------|---------|-----|
|
||||
| Transport mismatch | HTTP server with stdio config | Add `"transport": "http"` |
|
||||
| Path with spaces | Server fails on Windows | Use escaped paths or `%APPDATA%` |
|
||||
| Missing env vars | Auth failures | Add to `"env"` in config |
|
||||
| Server not installed | "command not found" | Run `npm install -g` first |
|
||||
| Port conflict | Server won't start | Change port or kill existing |
|
||||
|
||||
### After Config Changes
|
||||
|
||||
**Critical:** Completely quit and restart Claude Desktop after any config changes.
|
||||
|
||||
## Error: "Required parameter" validation errors
|
||||
|
||||
**Cause:** MCP tool schema mismatch (regression bug)
|
||||
|
||||
**Solutions:**
|
||||
1. Update Claude Desktop to latest version
|
||||
2. Check MCP server for updates
|
||||
3. Temporarily disable problematic server
|
||||
|
||||
---
|
||||
|
||||
# CATEGORY 7: Account Errors
|
||||
|
||||
## Error: "Your account has been disabled"
|
||||
|
||||
**Full message:** "Your account has been disabled after an automatic review of your recent activities."
|
||||
|
||||
**Cause:** Automated system flagged account
|
||||
|
||||
**Solutions:**
|
||||
1. Contact Anthropic support
|
||||
2. Review Terms of Service
|
||||
3. Do not create new accounts (may worsen situation)
|
||||
|
||||
## Error: "This organization has been disabled"
|
||||
|
||||
**Cause:** Organization-level suspension
|
||||
|
||||
**Solution:** Organization admin must contact Anthropic
|
||||
|
||||
## Error: "There was an error logging you in"
|
||||
|
||||
**Causes:**
|
||||
- VPN interference
|
||||
- Browser extensions blocking
|
||||
- Cached credentials issue
|
||||
|
||||
**Solutions:**
|
||||
1. Disable VPN
|
||||
2. Disable browser extensions temporarily
|
||||
3. Clear browser cache and cookies
|
||||
4. Try incognito/private window
|
||||
5. Check [status.claude.com](https://status.claude.com)
|
||||
|
||||
## Error: "Error Sending Codes - Check Your Phone Number"
|
||||
|
||||
**Cause:** Phone verification failed during signup
|
||||
|
||||
**Solutions:**
|
||||
1. Verify correct country code
|
||||
2. Check all digits entered correctly
|
||||
3. Try different phone number
|
||||
4. Wait and retry later
|
||||
|
||||
---
|
||||
|
||||
# CATEGORY 8: Output Quality Issues
|
||||
|
||||
## Issue: Output Suddenly Stops (Cutoff)
|
||||
|
||||
**Symptoms:** Response ends mid-sentence or mid-code
|
||||
|
||||
**Causes:**
|
||||
1. Hit output token limit (~4K-8K)
|
||||
2. Safety filter triggered
|
||||
3. Server timeout
|
||||
|
||||
**Solutions:**
|
||||
1. Ask "Please continue from where you stopped"
|
||||
2. Request smaller chunks upfront
|
||||
3. Be more specific in scope
|
||||
|
||||
## Issue: Gibberish or Nonsensical Output
|
||||
|
||||
**Symptoms:** Incoherent text, random characters
|
||||
|
||||
**Causes:**
|
||||
1. Model confusion from complex prompt
|
||||
2. Conflicting instructions
|
||||
3. Edge case in training
|
||||
|
||||
**Solutions:**
|
||||
1. Simplify prompt
|
||||
2. Start new conversation
|
||||
3. Rephrase request differently
|
||||
|
||||
## Issue: Mixed Languages or Character Issues
|
||||
|
||||
**Symptoms:** Unexpected language switches, formatting problems
|
||||
|
||||
**Causes:**
|
||||
1. Ambiguous language context
|
||||
2. Copy-pasted special characters
|
||||
|
||||
**Solutions:**
|
||||
1. Explicitly state desired language
|
||||
2. Clean input text of special characters
|
||||
3. Add "Please respond in [language]"
|
||||
|
||||
## Issue: Claude Refuses to Respond
|
||||
|
||||
**Symptoms:** Declines request citing policy
|
||||
|
||||
**Causes:**
|
||||
1. Request triggered safety guidelines
|
||||
2. Ambiguous phrasing interpreted as harmful
|
||||
|
||||
**Solutions:**
|
||||
1. Rephrase more clearly
|
||||
2. Explain legitimate use case
|
||||
3. Break into smaller, clearer requests
|
||||
|
||||
---
|
||||
|
||||
## Prevention Checklist
|
||||
|
||||
### Context/Input Errors
|
||||
|
||||
- [ ] Maximum 5 MCP servers active
|
||||
- [ ] All servers have serverInstructions
|
||||
- [ ] Skills under 1,000 words
|
||||
- [ ] Start fresh conversations for new topics
|
||||
- [ ] Avoid attaching files over 50KB (prefer excerpts)
|
||||
- [ ] Individual files under 10MB
|
||||
|
||||
### Output Errors
|
||||
|
||||
- [ ] Break large requests into chunks
|
||||
- [ ] Use specific scope in prompts
|
||||
- [ ] Request concise/brief outputs when possible
|
||||
- [ ] Paginate lists and tables (50 items max)
|
||||
- [ ] Generate code module by module
|
||||
- [ ] Retry once before rephrasing
|
||||
|
||||
### Usage Limits
|
||||
|
||||
- [ ] Monitor "messages left" warnings
|
||||
- [ ] Combine related questions into single prompts
|
||||
- [ ] Use concise prompts to conserve tokens
|
||||
- [ ] Know your plan's reset schedule
|
||||
|
||||
### MCP Stability
|
||||
|
||||
- [ ] Test MCP servers independently before adding
|
||||
- [ ] Keep server logs accessible for debugging
|
||||
- [ ] Restart Claude Desktop after config changes
|
||||
- [ ] Update MCP servers regularly
|
||||
- [ ] Document working configurations
|
||||
|
||||
### General Best Practices
|
||||
|
||||
- [ ] Check [status.claude.com](https://status.claude.com) when experiencing issues
|
||||
- [ ] Keep Claude Desktop updated
|
||||
- [ ] Clear browser cache periodically (web version)
|
||||
- [ ] Disable VPN if experiencing login issues
|
||||
- [ ] Back up important conversations locally
|
||||
@@ -0,0 +1,76 @@
|
||||
# Sample Settings Check Report
|
||||
|
||||
## Configuration Summary
|
||||
|
||||
| Component | Count | Tokens (est.) | Status |
|
||||
|-----------|-------|---------------|--------|
|
||||
| MCP Servers | 6 | ~45,000 | ⚠️ High |
|
||||
| Active Skills | 3 | ~1,500 | ✓ OK |
|
||||
| Project Files | 2 | ~2,000 | ✓ OK |
|
||||
| **Baseline Total** | — | ~48,500 | ⚠️ Warning |
|
||||
| **Available** | — | ~151,500 (76%) | Marginal |
|
||||
|
||||
## Issues Found
|
||||
|
||||
### Critical
|
||||
1. **GitHub MCP server loading all tools** (~18,000 tokens)
|
||||
- 25+ tools loaded but only 3-4 commonly used
|
||||
- Missing `serverInstructions`
|
||||
|
||||
### Warnings
|
||||
1. **Zapier MCP enabled** (~25,000 tokens)
|
||||
- 50+ tools, rarely used
|
||||
- Consider disabling
|
||||
|
||||
2. **Playwright missing serverInstructions**
|
||||
- Tool discovery inefficient
|
||||
- Add: `"serverInstructions": "Browser automation..."`
|
||||
|
||||
3. **Custom skill SKILL.md is 1,500 words**
|
||||
- Exceeds 1,000 word recommendation
|
||||
- Move reference data to separate file
|
||||
|
||||
## Recommended Actions
|
||||
|
||||
### Immediate (save ~35,000 tokens)
|
||||
|
||||
1. **Disable Zapier MCP** (saves ~25,000)
|
||||
```json
|
||||
// Remove or comment out in claude_desktop_config.json
|
||||
// "zapier": { ... }
|
||||
```
|
||||
|
||||
2. **Add serverInstructions to all servers** (saves ~5,000)
|
||||
```json
|
||||
"github": {
|
||||
"command": "...",
|
||||
"serverInstructions": "GitHub operations. Use for: repos, issues, PRs. Keywords: github, repo, issue, pull request"
|
||||
}
|
||||
```
|
||||
|
||||
3. **Refactor long skill** (saves ~1,000)
|
||||
- Move data tables to `references/` directory
|
||||
- Keep SKILL.md under 500 words
|
||||
|
||||
### Secondary
|
||||
|
||||
4. Consider starting fresh conversations for unrelated tasks
|
||||
5. Review GitHub usage - if only for viewing, use web instead
|
||||
|
||||
## After Optimization
|
||||
|
||||
| Component | Tokens (est.) | Status |
|
||||
|-----------|---------------|--------|
|
||||
| MCP Servers | ~15,000 | ✓ Good |
|
||||
| Skills + Files | ~2,500 | ✓ Good |
|
||||
| **Baseline Total** | ~17,500 | ✓ Good |
|
||||
| **Available** | ~182,500 (91%) | ✓ Excellent |
|
||||
|
||||
## Quick Wins Checklist
|
||||
|
||||
- [x] Disable Zapier MCP
|
||||
- [x] Add serverInstructions to Playwright
|
||||
- [x] Add serverInstructions to GitHub
|
||||
- [x] Add serverInstructions to Notion
|
||||
- [ ] Refactor jamie-brand skill (move procedures data)
|
||||
- [ ] Review PostgreSQL usage frequency
|
||||
@@ -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
|
||||
```
|
||||
@@ -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
|
||||
@@ -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*
|
||||
39
custom-skills/00-our-settings-audit/desktop/skill.yaml
Normal file
39
custom-skills/00-our-settings-audit/desktop/skill.yaml
Normal file
@@ -0,0 +1,39 @@
|
||||
# OurDigital Settings Audit
|
||||
# Comprehensive error diagnosis and context optimization
|
||||
|
||||
name: our-settings-audit
|
||||
|
||||
description: |
|
||||
Diagnose all Claude Desktop errors and optimize context usage.
|
||||
Covers 8 error categories: context limits, output interruption,
|
||||
length/file errors, usage limits, server capacity, MCP connection,
|
||||
account issues, and output quality problems.
|
||||
|
||||
allowed-tools:
|
||||
- Read
|
||||
- Glob
|
||||
- Grep
|
||||
|
||||
license: Internal-use Only
|
||||
|
||||
triggers:
|
||||
- settings audit
|
||||
- settings check
|
||||
- audit settings
|
||||
- exceed response limit
|
||||
- response could not be generated
|
||||
- length limit
|
||||
- file too large
|
||||
- conversation limit
|
||||
- 5-hour limit
|
||||
- messages left
|
||||
- rate limit
|
||||
- capacity constraints
|
||||
- server error
|
||||
- MCP error
|
||||
- server connection failed
|
||||
- account disabled
|
||||
- login error
|
||||
- output cutoff
|
||||
- token error
|
||||
- gibberish output
|
||||
Reference in New Issue
Block a user