ourdigital/our-claude-skills
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

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

Browse Source 
## 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
2026-02-03 16:48:06 +07:00
committed by GitHub
parent 0bc24d00b9
commit b6a478e1df
72 changed files with 4770 additions and 803 deletions
Download Patch File Download Diff File Expand all files Collapse all files

633
custom-skills/00-our-settings-audit/desktop/SKILL.md Normal file
View 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