From b6a478e1df6d1c2bdc9895310f7c97cfe74a796a Mon Sep 17 00:00:00 2001 From: Andrew Yim <6537554+ourdigital@users.noreply.github.com> Date: Tue, 3 Feb 2026 16:48:06 +0700 Subject: [PATCH] feat: Add installation tool, Claude.ai export, and skill standardization (#1) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## 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 --- CLAUDE.md | 6 +- .../00-claude-code-setting/README.md | 79 --- custom-skills/00-our-settings-audit/README.md | 125 ++++ .../code/CLAUDE.md | 0 .../code/commands/settings-audit.md | 0 .../code/install.sh | 0 .../code/references/token-optimization.md | 0 .../code/scripts/analyze_extensions.py | 0 .../code/scripts/analyze_tokens.py | 0 .../code/scripts/auto_fix.py | 0 .../code/scripts/requirements.txt | 0 .../code/scripts/run_audit.py | 0 .../code/settings-audit-report.json | 0 .../code/settings-audit-report.md | 0 .../00-our-settings-audit/desktop/SKILL.md | 633 ++++++++++++++++++ .../desktop/examples/sample-audit-report.md | 76 +++ .../desktop/references/config-locations.md | 77 +++ .../desktop/references/mcp-token-estimates.md | 88 +++ .../desktop/references/our-settings-audit.md | 349 ++++++++++ .../00-our-settings-audit/desktop/skill.yaml | 39 ++ .../11-seo-on-page-audit/desktop/SKILL.md | 7 + .../12-seo-local-audit/desktop/SKILL.md | 7 + .../13-seo-schema-validator/desktop/SKILL.md | 7 + .../14-seo-schema-generator/desktop/SKILL.md | 7 + .../15-seo-core-web-vitals/desktop/SKILL.md | 7 + .../16-seo-search-console/desktop/SKILL.md | 7 + .../17-seo-gateway-architect/desktop/SKILL.md | 7 + .../18-seo-gateway-builder/desktop/SKILL.md | 7 + .../19-seo-technical-audit/desktop/SKILL.md | 7 + custom-skills/20-gtm-audit/desktop/SKILL.md | 7 + .../22-gtm-guardian/desktop/SKILL.md | 7 + .../31-notion-organizer/desktop/SKILL.md | 7 + .../32-notion-writer/desktop/SKILL.md | 7 + .../40-jamie-brand-editor/desktop/SKILL.md | 7 + .../41-jamie-brand-audit/desktop/SKILL.md | 7 + .../43-jamie-youtube-manager/desktop/SKILL.md | 7 + .../desktop/SKILL.md | 7 + .../desktop/SKILL.md | 7 + .../01-reference-discovery/desktop/SKILL.md | 7 + .../desktop/SKILL.md | 7 + .../03-content-repository/desktop/SKILL.md | 7 + .../04-content-distiller/desktop/SKILL.md | 7 + .../05-quality-reviewer/desktop/SKILL.md | 7 + .../06-markdown-exporter/desktop/SKILL.md | 7 + .../07-pipeline-orchestrator/desktop/SKILL.md | 7 + .../.claude-plugin/plugin.json | 22 +- custom-skills/91-multi-agent-guide/README.md | 20 +- .../commands/quick-setup.md | 95 +++ .../skills/multi-agent-guide/SKILL.md | 34 +- .../templates/multi-agent-framework.md | 256 +++++++ .../{ => 99_archive/doc}/AUDIT_REPORT.md | 0 .../99_archive/{ => doc}/REFACTORING_PLAN.md | 0 custom-skills/OUR_SKILL_PROJECT_PLAN_v1.1.md | 571 ---------------- custom-skills/_ourdigital-shared/README.md | 232 ++++--- .../claude-ai-export/INSTALL-CLAUDE-AI.md | 53 ++ .../individual/01-brand-guide.md | 137 ++++ .../claude-ai-export/individual/02-blog.md | 137 ++++ .../claude-ai-export/individual/03-journal.md | 137 ++++ .../individual/04-research.md | 137 ++++ .../individual/05-document.md | 137 ++++ .../individual/06-designer.md | 137 ++++ .../individual/07-ad-manager.md | 137 ++++ .../claude-ai-export/individual/08-trainer.md | 137 ++++ .../individual/09-backoffice.md | 137 ++++ .../individual/10-skill-creator.md | 137 ++++ .../ourdigital-skills-bundle.md | 336 ++++++++++ custom-skills/_ourdigital-shared/install.sh | 415 ++++++++++++ .../scripts/export_for_claude_ai.py | 158 +++++ .../scripts/validate_install.py | 284 ++++++++ .../settings-audit-report.json | 0 .../settings-audit-report.md | 0 reference/SKILL-FORMAT-REQUIREMENTS.md | 80 ++- 72 files changed, 4770 insertions(+), 803 deletions(-) delete mode 100644 custom-skills/00-claude-code-setting/README.md create mode 100644 custom-skills/00-our-settings-audit/README.md rename custom-skills/{00-claude-code-setting => 00-our-settings-audit}/code/CLAUDE.md (100%) rename custom-skills/{00-claude-code-setting => 00-our-settings-audit}/code/commands/settings-audit.md (100%) rename custom-skills/{00-claude-code-setting => 00-our-settings-audit}/code/install.sh (100%) rename custom-skills/{00-claude-code-setting => 00-our-settings-audit}/code/references/token-optimization.md (100%) rename custom-skills/{00-claude-code-setting => 00-our-settings-audit}/code/scripts/analyze_extensions.py (100%) rename custom-skills/{00-claude-code-setting => 00-our-settings-audit}/code/scripts/analyze_tokens.py (100%) rename custom-skills/{00-claude-code-setting => 00-our-settings-audit}/code/scripts/auto_fix.py (100%) rename custom-skills/{00-claude-code-setting => 00-our-settings-audit}/code/scripts/requirements.txt (100%) rename custom-skills/{00-claude-code-setting => 00-our-settings-audit}/code/scripts/run_audit.py (100%) rename custom-skills/{00-claude-code-setting => 00-our-settings-audit}/code/settings-audit-report.json (100%) rename custom-skills/{00-claude-code-setting => 00-our-settings-audit}/code/settings-audit-report.md (100%) create mode 100644 custom-skills/00-our-settings-audit/desktop/SKILL.md create mode 100644 custom-skills/00-our-settings-audit/desktop/examples/sample-audit-report.md create mode 100644 custom-skills/00-our-settings-audit/desktop/references/config-locations.md create mode 100644 custom-skills/00-our-settings-audit/desktop/references/mcp-token-estimates.md create mode 100644 custom-skills/00-our-settings-audit/desktop/references/our-settings-audit.md create mode 100644 custom-skills/00-our-settings-audit/desktop/skill.yaml create mode 100644 custom-skills/91-multi-agent-guide/commands/quick-setup.md create mode 100644 custom-skills/91-multi-agent-guide/skills/multi-agent-guide/templates/multi-agent-framework.md rename custom-skills/{ => 99_archive/doc}/AUDIT_REPORT.md (100%) rename custom-skills/99_archive/{ => doc}/REFACTORING_PLAN.md (100%) delete mode 100644 custom-skills/OUR_SKILL_PROJECT_PLAN_v1.1.md create mode 100644 custom-skills/_ourdigital-shared/claude-ai-export/INSTALL-CLAUDE-AI.md create mode 100644 custom-skills/_ourdigital-shared/claude-ai-export/individual/01-brand-guide.md create mode 100644 custom-skills/_ourdigital-shared/claude-ai-export/individual/02-blog.md create mode 100644 custom-skills/_ourdigital-shared/claude-ai-export/individual/03-journal.md create mode 100644 custom-skills/_ourdigital-shared/claude-ai-export/individual/04-research.md create mode 100644 custom-skills/_ourdigital-shared/claude-ai-export/individual/05-document.md create mode 100644 custom-skills/_ourdigital-shared/claude-ai-export/individual/06-designer.md create mode 100644 custom-skills/_ourdigital-shared/claude-ai-export/individual/07-ad-manager.md create mode 100644 custom-skills/_ourdigital-shared/claude-ai-export/individual/08-trainer.md create mode 100644 custom-skills/_ourdigital-shared/claude-ai-export/individual/09-backoffice.md create mode 100644 custom-skills/_ourdigital-shared/claude-ai-export/individual/10-skill-creator.md create mode 100644 custom-skills/_ourdigital-shared/claude-ai-export/ourdigital-skills-bundle.md create mode 100755 custom-skills/_ourdigital-shared/install.sh create mode 100755 custom-skills/_ourdigital-shared/scripts/export_for_claude_ai.py create mode 100755 custom-skills/_ourdigital-shared/scripts/validate_install.py rename settings-audit-report.json => docs/settings-audit-report.json (100%) rename settings-audit-report.md => docs/settings-audit-report.md (100%) diff --git a/CLAUDE.md b/CLAUDE.md index a8c5acc..4248fa4 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -14,11 +14,11 @@ This is a Claude Skills collection repository containing: ## Custom Skills Summary -### Claude Code Settings (00) +### Claude Settings Audit (00) | # | Skill | Purpose | Trigger | |---|-------|---------|---------| -| 00 | claude-code-setting | Settings optimization & token audit | "audit settings", "optimize Claude Code" | +| 00 | our-settings-audit | Error diagnosis & token optimization (8 categories) | "settings audit", "exceed response limit", "MCP error" | ### OurDigital Core Workflows (01-09) @@ -170,7 +170,7 @@ triggers: [] # Explicit trigger keywords ``` our-claude-skills/ ├── custom-skills/ -│ ├── 00-claude-code-setting/ +│ ├── 00-our-settings-audit/ │ │ │ ├── 01-ourdigital-research/ │ ├── 02-ourdigital-designer/ diff --git a/custom-skills/00-claude-code-setting/README.md b/custom-skills/00-claude-code-setting/README.md deleted file mode 100644 index 17a0631..0000000 --- a/custom-skills/00-claude-code-setting/README.md +++ /dev/null @@ -1,79 +0,0 @@ -# Claude Code Settings Optimizer - -Self-audit and optimize Claude Code configuration for maximum token efficiency. - -## Purpose - -- Analyze token usage across MCP servers, CLAUDE.md, and extensions -- Identify optimization opportunities -- Auto-fix common issues with backup safety -- Keep working context at 70%+ of 200K limit - -## Quick Start - -```bash -# Install -cd custom-skills/00-claude-code-setting/code -chmod +x install.sh -./install.sh - -# Run audit -python3 scripts/run_audit.py - -# Apply fixes -python3 scripts/auto_fix.py --apply -``` - -## What Gets Analyzed - -| Component | Checks | -|-----------|--------| -| **MCP Servers** | serverInstructions presence, token estimates, load strategy | -| **CLAUDE.md** | Line count, token estimate, structure quality | -| **Commands** | Frontmatter, description, size limits | -| **Skills** | SKILL.md presence, size limits | -| **Agents** | Tool restrictions | - -## Target Metrics - -| Metric | Target | Max | -|--------|--------|-----| -| CLAUDE.md tokens | 2,000 | 3,000 | -| MCP tokens (with Tool Search) | 5,000 | 10,000 | -| Baseline total | <30% | <40% | -| Available for work | >70% | — | - -## Files - -``` -00-claude-code-setting/ -├── README.md -└── code/ - ├── CLAUDE.md # Skill directive - ├── install.sh # Installation script - ├── commands/ - │ └── settings-audit.md # /settings-audit command - ├── scripts/ - │ ├── run_audit.py # Main orchestrator - │ ├── analyze_tokens.py # Token analysis - │ ├── analyze_extensions.py - │ └── auto_fix.py # Auto-fix with backup - └── references/ - └── token-optimization.md -``` - -## Auto-Fix Capabilities - -**Safe (automatic with backup):** -- Add serverInstructions to MCP servers -- Add frontmatter to commands - -**Manual review required:** -- Disabling MCP servers -- Restructuring CLAUDE.md -- Removing extensions - -## Requirements - -- Python 3.8+ -- PyYAML (optional, for better frontmatter parsing) diff --git a/custom-skills/00-our-settings-audit/README.md b/custom-skills/00-our-settings-audit/README.md new file mode 100644 index 0000000..446f34f --- /dev/null +++ b/custom-skills/00-our-settings-audit/README.md @@ -0,0 +1,125 @@ +# Claude Settings Optimizer + +Self-audit and optimize Claude configuration for maximum token efficiency. + +**Supports both Claude Code (CLI) and Claude Desktop (App).** + +## Purpose + +- **Diagnose all Claude errors** (8 categories covered) +- Analyze token usage across MCP servers, CLAUDE.md, and extensions +- Troubleshoot MCP connection issues +- Identify optimization opportunities +- Auto-fix common issues with backup safety (Code version) +- Keep working context at 70%+ of 200K limit + +## Platform Versions + +| Version | Path | Use Case | +|---------|------|----------| +| **Claude Code** | `code/` | CLI with automated scripts | +| **Claude Desktop** | `desktop/` | App-based manual guidance | + +## Claude Code Quick Start + +```bash +# Install +cd custom-skills/00-our-settings-audit/code +chmod +x install.sh +./install.sh + +# Run audit +python3 scripts/run_audit.py + +# Apply fixes +python3 scripts/auto_fix.py --apply +``` + +## Claude Desktop Quick Start + +Covers **8 error categories**: + +| Category | Example Errors | +|----------|----------------| +| Context/Input | "Exceed response limit" | +| Output | "Response could not be fully generated" | +| Length/File | "Message will exceed length limit", "Files larger than 10mb" | +| Usage Limits | "5-hour limit reached", "X messages left" | +| Server/Capacity | "Unexpected capacity constraints" | +| MCP Connection | "Error connecting to [ServerName]" | +| Account | "Account has been disabled", login errors | +| Output Quality | Output cutoff, gibberish, mixed languages | + +**When encountering any error:** + +1. Use the Quick Diagnosis Tree in `desktop/SKILL.md` +2. Follow category-specific troubleshooting steps +3. Apply prevention checklist recommendations + +**For MCP issues**, share your config file: +- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json` +- Windows: `%APPDATA%\Claude\claude_desktop_config.json` + +## What Gets Analyzed + +| Component | Checks | +|-----------|--------| +| **MCP Servers** | serverInstructions presence, token estimates, load strategy | +| **CLAUDE.md** | Line count, token estimate, structure quality | +| **Commands** | Frontmatter, description, size limits | +| **Skills** | SKILL.md presence, size limits | +| **Agents** | Tool restrictions | + +## Target Metrics + +| Metric | Target | Max | +|--------|--------|-----| +| CLAUDE.md tokens | 2,000 | 3,000 | +| MCP tokens (with Tool Search) | 5,000 | 10,000 | +| Baseline total | <30% | <40% | +| Available for work | >70% | — | + +## Files + +``` +00-our-settings-audit/ +├── README.md +├── code/ # Claude Code (CLI) +│ ├── CLAUDE.md # Skill directive +│ ├── install.sh # Installation script +│ ├── commands/ +│ │ └── settings-audit.md # /settings-audit command +│ ├── scripts/ +│ │ ├── run_audit.py # Main orchestrator +│ │ ├── analyze_tokens.py # Token analysis +│ │ ├── analyze_extensions.py +│ │ └── auto_fix.py # Auto-fix with backup +│ └── references/ +│ └── token-optimization.md +│ +└── desktop/ # Claude Desktop (App) + ├── skill.yaml # Skill metadata + ├── SKILL.md # Diagnosis workflow (8 error categories) + ├── references/ + │ ├── config-locations.md # Config file paths + │ ├── mcp-token-estimates.md # Token budget guide + │ └── our-settings-audit.md # Claude.ai project reference + └── examples/ + └── sample-audit-report.md # Example output +``` + +## Auto-Fix Capabilities + +**Safe (automatic with backup):** +- Add serverInstructions to MCP servers +- Add frontmatter to commands + +**Manual review required:** +- Disabling MCP servers +- Restructuring CLAUDE.md +- Removing extensions + +## Requirements + +- Python 3.8+ +- PyYAML (optional, for better frontmatter parsing) diff --git a/custom-skills/00-claude-code-setting/code/CLAUDE.md b/custom-skills/00-our-settings-audit/code/CLAUDE.md similarity index 100% rename from custom-skills/00-claude-code-setting/code/CLAUDE.md rename to custom-skills/00-our-settings-audit/code/CLAUDE.md diff --git a/custom-skills/00-claude-code-setting/code/commands/settings-audit.md b/custom-skills/00-our-settings-audit/code/commands/settings-audit.md similarity index 100% rename from custom-skills/00-claude-code-setting/code/commands/settings-audit.md rename to custom-skills/00-our-settings-audit/code/commands/settings-audit.md diff --git a/custom-skills/00-claude-code-setting/code/install.sh b/custom-skills/00-our-settings-audit/code/install.sh similarity index 100% rename from custom-skills/00-claude-code-setting/code/install.sh rename to custom-skills/00-our-settings-audit/code/install.sh diff --git a/custom-skills/00-claude-code-setting/code/references/token-optimization.md b/custom-skills/00-our-settings-audit/code/references/token-optimization.md similarity index 100% rename from custom-skills/00-claude-code-setting/code/references/token-optimization.md rename to custom-skills/00-our-settings-audit/code/references/token-optimization.md diff --git a/custom-skills/00-claude-code-setting/code/scripts/analyze_extensions.py b/custom-skills/00-our-settings-audit/code/scripts/analyze_extensions.py similarity index 100% rename from custom-skills/00-claude-code-setting/code/scripts/analyze_extensions.py rename to custom-skills/00-our-settings-audit/code/scripts/analyze_extensions.py diff --git a/custom-skills/00-claude-code-setting/code/scripts/analyze_tokens.py b/custom-skills/00-our-settings-audit/code/scripts/analyze_tokens.py similarity index 100% rename from custom-skills/00-claude-code-setting/code/scripts/analyze_tokens.py rename to custom-skills/00-our-settings-audit/code/scripts/analyze_tokens.py diff --git a/custom-skills/00-claude-code-setting/code/scripts/auto_fix.py b/custom-skills/00-our-settings-audit/code/scripts/auto_fix.py similarity index 100% rename from custom-skills/00-claude-code-setting/code/scripts/auto_fix.py rename to custom-skills/00-our-settings-audit/code/scripts/auto_fix.py diff --git a/custom-skills/00-claude-code-setting/code/scripts/requirements.txt b/custom-skills/00-our-settings-audit/code/scripts/requirements.txt similarity index 100% rename from custom-skills/00-claude-code-setting/code/scripts/requirements.txt rename to custom-skills/00-our-settings-audit/code/scripts/requirements.txt diff --git a/custom-skills/00-claude-code-setting/code/scripts/run_audit.py b/custom-skills/00-our-settings-audit/code/scripts/run_audit.py similarity index 100% rename from custom-skills/00-claude-code-setting/code/scripts/run_audit.py rename to custom-skills/00-our-settings-audit/code/scripts/run_audit.py diff --git a/custom-skills/00-claude-code-setting/code/settings-audit-report.json b/custom-skills/00-our-settings-audit/code/settings-audit-report.json similarity index 100% rename from custom-skills/00-claude-code-setting/code/settings-audit-report.json rename to custom-skills/00-our-settings-audit/code/settings-audit-report.json diff --git a/custom-skills/00-claude-code-setting/code/settings-audit-report.md b/custom-skills/00-our-settings-audit/code/settings-audit-report.md similarity index 100% rename from custom-skills/00-claude-code-setting/code/settings-audit-report.md rename to custom-skills/00-our-settings-audit/code/settings-audit-report.md diff --git a/custom-skills/00-our-settings-audit/desktop/SKILL.md b/custom-skills/00-our-settings-audit/desktop/SKILL.md new file mode 100644 index 0000000..cd8e3e3 --- /dev/null +++ b/custom-skills/00-our-settings-audit/desktop/SKILL.md @@ -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 diff --git a/custom-skills/00-our-settings-audit/desktop/examples/sample-audit-report.md b/custom-skills/00-our-settings-audit/desktop/examples/sample-audit-report.md new file mode 100644 index 0000000..a5e59fe --- /dev/null +++ b/custom-skills/00-our-settings-audit/desktop/examples/sample-audit-report.md @@ -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 diff --git a/custom-skills/00-our-settings-audit/desktop/references/config-locations.md b/custom-skills/00-our-settings-audit/desktop/references/config-locations.md new file mode 100644 index 0000000..47d3933 --- /dev/null +++ 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 +``` diff --git 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 new file mode 100644 index 0000000..859d822 --- /dev/null +++ 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 diff --git 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 new file mode 100644 index 0000000..5eb7193 --- /dev/null +++ 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* diff --git a/custom-skills/00-our-settings-audit/desktop/skill.yaml b/custom-skills/00-our-settings-audit/desktop/skill.yaml new file mode 100644 index 0000000..1c11d85 --- /dev/null +++ b/custom-skills/00-our-settings-audit/desktop/skill.yaml @@ -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 diff --git a/custom-skills/11-seo-on-page-audit/desktop/SKILL.md b/custom-skills/11-seo-on-page-audit/desktop/SKILL.md index 6c5b0c0..44c5f2e 100644 --- a/custom-skills/11-seo-on-page-audit/desktop/SKILL.md +++ b/custom-skills/11-seo-on-page-audit/desktop/SKILL.md @@ -1,3 +1,10 @@ +--- +name: seo-on-page-audit +description: | + On-page SEO analyzer for meta tags, headings, links, images, and Open Graph. + Triggers: on-page SEO, meta tags, title tag, heading structure, alt text. +--- + # SEO On-Page Audit ## Purpose diff --git a/custom-skills/12-seo-local-audit/desktop/SKILL.md b/custom-skills/12-seo-local-audit/desktop/SKILL.md index ad5fb7d..8b8efd0 100644 --- a/custom-skills/12-seo-local-audit/desktop/SKILL.md +++ b/custom-skills/12-seo-local-audit/desktop/SKILL.md @@ -1,3 +1,10 @@ +--- +name: seo-local-audit +description: | + Local business SEO auditor for NAP consistency, Google Business Profile, and citations. + Triggers: local SEO, NAP audit, Google Business Profile, GBP optimization, local citations. +--- + # SEO Local Audit ## Purpose diff --git a/custom-skills/13-seo-schema-validator/desktop/SKILL.md b/custom-skills/13-seo-schema-validator/desktop/SKILL.md index b98b1c1..51cd538 100644 --- a/custom-skills/13-seo-schema-validator/desktop/SKILL.md +++ b/custom-skills/13-seo-schema-validator/desktop/SKILL.md @@ -1,3 +1,10 @@ +--- +name: seo-schema-validator +description: | + Structured data validator for JSON-LD, Microdata, and RDFa against schema.org. + Triggers: validate schema, JSON-LD check, structured data, rich results eligibility. +--- + # SEO Schema Validator ## Purpose diff --git a/custom-skills/14-seo-schema-generator/desktop/SKILL.md b/custom-skills/14-seo-schema-generator/desktop/SKILL.md index 055a4d3..20b4619 100644 --- a/custom-skills/14-seo-schema-generator/desktop/SKILL.md +++ b/custom-skills/14-seo-schema-generator/desktop/SKILL.md @@ -1,3 +1,10 @@ +--- +name: seo-schema-generator +description: | + JSON-LD structured data generator from templates for various content types. + Triggers: generate schema, create JSON-LD, schema markup, structured data generator. +--- + # SEO Schema Generator ## Purpose diff --git a/custom-skills/15-seo-core-web-vitals/desktop/SKILL.md b/custom-skills/15-seo-core-web-vitals/desktop/SKILL.md index 46bfa78..fc5729b 100644 --- a/custom-skills/15-seo-core-web-vitals/desktop/SKILL.md +++ b/custom-skills/15-seo-core-web-vitals/desktop/SKILL.md @@ -1,3 +1,10 @@ +--- +name: seo-core-web-vitals +description: | + Core Web Vitals analyzer for LCP, FID, CLS, and INP optimization recommendations. + Triggers: Core Web Vitals, page speed, LCP optimization, CLS fix, INP analysis. +--- + # SEO Core Web Vitals ## Purpose diff --git a/custom-skills/16-seo-search-console/desktop/SKILL.md b/custom-skills/16-seo-search-console/desktop/SKILL.md index e7e69f4..216bf69 100644 --- a/custom-skills/16-seo-search-console/desktop/SKILL.md +++ b/custom-skills/16-seo-search-console/desktop/SKILL.md @@ -1,3 +1,10 @@ +--- +name: seo-search-console +description: | + Google Search Console data analyzer for performance, queries, and index coverage. + Triggers: Search Console, GSC analysis, search performance, rankings, CTR optimization. +--- + # SEO Search Console ## Purpose diff --git a/custom-skills/17-seo-gateway-architect/desktop/SKILL.md b/custom-skills/17-seo-gateway-architect/desktop/SKILL.md index ab1f2b0..2962f1d 100644 --- a/custom-skills/17-seo-gateway-architect/desktop/SKILL.md +++ b/custom-skills/17-seo-gateway-architect/desktop/SKILL.md @@ -1,3 +1,10 @@ +--- +name: seo-gateway-architect +description: | + Gateway page strategy planner for keyword research, content architecture, and SEO KPIs. + Triggers: SEO strategy, gateway pages, keyword research, content architecture. +--- + # SEO Gateway Page Strategist This skill helps you create comprehensive SEO-focused gateway page strategies for Korean medical/service websites, optimized for both Naver and Google. diff --git a/custom-skills/18-seo-gateway-builder/desktop/SKILL.md b/custom-skills/18-seo-gateway-builder/desktop/SKILL.md index 03bd13a..c7930c5 100644 --- a/custom-skills/18-seo-gateway-builder/desktop/SKILL.md +++ b/custom-skills/18-seo-gateway-builder/desktop/SKILL.md @@ -1,3 +1,10 @@ +--- +name: seo-gateway-builder +description: | + Gateway page content builder with templates, schema markup, and local SEO optimization. + Triggers: build gateway page, create landing page, local service page, location pages. +--- + # Gateway Page Content Builder A comprehensive skill for building high-quality, SEO-optimized gateway page content for local services, medical practices, and business locations. diff --git a/custom-skills/19-seo-technical-audit/desktop/SKILL.md b/custom-skills/19-seo-technical-audit/desktop/SKILL.md index 86faf33..e8aa1e3 100644 --- a/custom-skills/19-seo-technical-audit/desktop/SKILL.md +++ b/custom-skills/19-seo-technical-audit/desktop/SKILL.md @@ -1,3 +1,10 @@ +--- +name: seo-technical-audit +description: | + Technical SEO analyzer for robots.txt, sitemap, and crawlability fundamentals. + Triggers: technical SEO, robots.txt, sitemap validation, crawlability, URL accessibility. +--- + # SEO Technical Audit ## Purpose diff --git a/custom-skills/20-gtm-audit/desktop/SKILL.md b/custom-skills/20-gtm-audit/desktop/SKILL.md index d86a054..500e93f 100644 --- a/custom-skills/20-gtm-audit/desktop/SKILL.md +++ b/custom-skills/20-gtm-audit/desktop/SKILL.md @@ -1,3 +1,10 @@ +--- +name: gtm-audit +description: | + GTM container audit using Chrome DevTools and DTM Agent for tag verification. + Triggers: audit GTM, GTM analysis, tag debugging, dataLayer inspection. +--- + # GTM Audit Skill Automated audit workflow for GTM containers using **Chrome DevTools MCP** for browser inspection and **DTM Agent MCP** for GTM API operations. diff --git a/custom-skills/22-gtm-guardian/desktop/SKILL.md b/custom-skills/22-gtm-guardian/desktop/SKILL.md index 4597ec2..ba2e667 100644 --- a/custom-skills/22-gtm-guardian/desktop/SKILL.md +++ b/custom-skills/22-gtm-guardian/desktop/SKILL.md @@ -1,3 +1,10 @@ +--- +name: gtm-guardian +description: | + GTM tagging lifecycle manager: analysis, planning, taxonomy, implementation guide. + Triggers: GTM strategy, tagging plan, event taxonomy, implementation guide. +--- + # GTM Guardian (Desktop) GTM(Google Tag Manager) 태깅 전략 수립부터 구현까지의 전체 라이프사이클을 지원하는 7단계 워크플로우 스킬. diff --git a/custom-skills/31-notion-organizer/desktop/SKILL.md b/custom-skills/31-notion-organizer/desktop/SKILL.md index 6d208c1..9ebd0ea 100644 --- a/custom-skills/31-notion-organizer/desktop/SKILL.md +++ b/custom-skills/31-notion-organizer/desktop/SKILL.md @@ -1,3 +1,10 @@ +--- +name: notion-organizer +description: | + Notion workspace manager for database optimization, property cleanup, and bulk operations. + Triggers: organize Notion, workspace cleanup, database schema, property standardization. +--- + # Notion Organizer Skill ## Purpose diff --git a/custom-skills/32-notion-writer/desktop/SKILL.md b/custom-skills/32-notion-writer/desktop/SKILL.md index d276144..566f3d9 100644 --- a/custom-skills/32-notion-writer/desktop/SKILL.md +++ b/custom-skills/32-notion-writer/desktop/SKILL.md @@ -1,3 +1,10 @@ +--- +name: notion-writer +description: | + Markdown to Notion page writer with database row creation support. + Triggers: write to Notion, export to Notion, push content, create Notion page. +--- + # Notion Writer Skill Push markdown content to Notion pages or databases via Claude Code. diff --git a/custom-skills/40-jamie-brand-editor/desktop/SKILL.md b/custom-skills/40-jamie-brand-editor/desktop/SKILL.md index 73d87d2..f37eba9 100644 --- a/custom-skills/40-jamie-brand-editor/desktop/SKILL.md +++ b/custom-skills/40-jamie-brand-editor/desktop/SKILL.md @@ -1,3 +1,10 @@ +--- +name: jamie-brand-editor +description: | + Jamie Plastic Surgery branded content generator for blog posts and marketing. + Triggers: write Jamie blog, Jamie content, brand copywriting, 제이미 콘텐츠. +--- + # Jamie Brand Editor Skill > **Purpose**: Generate branded content for Jamie Plastic Surgery Clinic diff --git a/custom-skills/41-jamie-brand-audit/desktop/SKILL.md b/custom-skills/41-jamie-brand-audit/desktop/SKILL.md index b18f990..df0498f 100644 --- a/custom-skills/41-jamie-brand-audit/desktop/SKILL.md +++ b/custom-skills/41-jamie-brand-audit/desktop/SKILL.md @@ -1,3 +1,10 @@ +--- +name: jamie-brand-audit +description: | + Jamie Plastic Surgery brand compliance reviewer and content evaluator. + Triggers: review content, brand audit, 제이미 브랜드 검토, tone and manner check. +--- + # Jamie Clinic Brand Guardian Skill > **브랜드**: 제이미성형외과 (Jamie Plastic Surgery Clinic) diff --git a/custom-skills/43-jamie-youtube-manager/desktop/SKILL.md b/custom-skills/43-jamie-youtube-manager/desktop/SKILL.md index f03148b..b6e3af3 100644 --- a/custom-skills/43-jamie-youtube-manager/desktop/SKILL.md +++ b/custom-skills/43-jamie-youtube-manager/desktop/SKILL.md @@ -1,3 +1,10 @@ +--- +name: jamie-youtube-manager +description: | + Jamie Clinic YouTube channel SEO auditor and content manager. + Triggers: YouTube SEO, video audit, 제이미 유튜브, channel optimization. +--- + # Jamie YouTube Manager Skill > **Purpose**: YouTube Channel SEO Auditor & Content Manager for Jamie Plastic Surgery Clinic diff --git a/custom-skills/44-jamie-youtube-subtitle-checker/desktop/SKILL.md b/custom-skills/44-jamie-youtube-subtitle-checker/desktop/SKILL.md index 4b7ded2..7521026 100644 --- a/custom-skills/44-jamie-youtube-subtitle-checker/desktop/SKILL.md +++ b/custom-skills/44-jamie-youtube-subtitle-checker/desktop/SKILL.md @@ -1,3 +1,10 @@ +--- +name: jamie-youtube-subtitle-checker +description: | + SBV subtitle file typo corrector and YouTube metadata generator for Jamie Clinic. + Triggers: check subtitles, subtitle QA, SBV correction, 자막 교정. +--- + # Jamie YouTube Subtitle Editor Skill > **Purpose**: SBV 자막 파일 오타 교정 및 YouTube 메타데이터 생성 diff --git a/custom-skills/45-jamie-instagram-manager/desktop/SKILL.md b/custom-skills/45-jamie-instagram-manager/desktop/SKILL.md index 345e0c8..4aa02cf 100644 --- a/custom-skills/45-jamie-instagram-manager/desktop/SKILL.md +++ b/custom-skills/45-jamie-instagram-manager/desktop/SKILL.md @@ -1,3 +1,10 @@ +--- +name: jamie-instagram-manager +description: | + Jamie Clinic Instagram account manager for engagement, content planning, and boost strategy. + Triggers: Instagram management, 제이미 인스타그램, IG strategy, social media. +--- + # Jamie Instagram Manager Skill > **Purpose**: Dedicated Instagram Account Manager for Jamie Plastic Surgery Clinic diff --git a/custom-skills/90-reference-curator/01-reference-discovery/desktop/SKILL.md b/custom-skills/90-reference-curator/01-reference-discovery/desktop/SKILL.md index f23563f..ca05238 100644 --- a/custom-skills/90-reference-curator/01-reference-discovery/desktop/SKILL.md +++ b/custom-skills/90-reference-curator/01-reference-discovery/desktop/SKILL.md @@ -1,3 +1,10 @@ +--- +name: reference-discovery +description: | + Search and discover authoritative reference sources with credibility validation. + Triggers: find sources, search documentation, discover references, source validation. +--- + # Reference Discovery Searches for authoritative sources, validates credibility, and produces curated URL lists for crawling. diff --git a/custom-skills/90-reference-curator/02-web-crawler-orchestrator/desktop/SKILL.md b/custom-skills/90-reference-curator/02-web-crawler-orchestrator/desktop/SKILL.md index be0a22d..1e875fb 100644 --- a/custom-skills/90-reference-curator/02-web-crawler-orchestrator/desktop/SKILL.md +++ b/custom-skills/90-reference-curator/02-web-crawler-orchestrator/desktop/SKILL.md @@ -1,3 +1,10 @@ +--- +name: web-crawler-orchestrator +description: | + Multi-backend web crawler with Firecrawl MCP, rate limiting, and format handling. + Triggers: crawl URLs, fetch pages, scrape content, web crawler. +--- + # Web Crawler Orchestrator Manages crawling operations using Firecrawl MCP with rate limiting and format handling. diff --git a/custom-skills/90-reference-curator/03-content-repository/desktop/SKILL.md b/custom-skills/90-reference-curator/03-content-repository/desktop/SKILL.md index 92fd46c..732037f 100644 --- a/custom-skills/90-reference-curator/03-content-repository/desktop/SKILL.md +++ b/custom-skills/90-reference-curator/03-content-repository/desktop/SKILL.md @@ -1,3 +1,10 @@ +--- +name: content-repository +description: | + MySQL storage manager for reference library with versioning and deduplication. + Triggers: store content, manage repository, document database, content storage. +--- + # Content Repository Manages MySQL storage for the reference library system. Handles document storage, version control, deduplication, and retrieval. diff --git a/custom-skills/90-reference-curator/04-content-distiller/desktop/SKILL.md b/custom-skills/90-reference-curator/04-content-distiller/desktop/SKILL.md index 0fde1e0..a840129 100644 --- a/custom-skills/90-reference-curator/04-content-distiller/desktop/SKILL.md +++ b/custom-skills/90-reference-curator/04-content-distiller/desktop/SKILL.md @@ -1,3 +1,10 @@ +--- +name: content-distiller +description: | + Raw content summarizer extracting key concepts, code snippets, and structured output. + Triggers: distill content, summarize document, extract key concepts, compress content. +--- + # Content Distiller Transforms raw crawled content into structured, high-quality reference materials. diff --git a/custom-skills/90-reference-curator/05-quality-reviewer/desktop/SKILL.md b/custom-skills/90-reference-curator/05-quality-reviewer/desktop/SKILL.md index 42818df..f2cba9a 100644 --- a/custom-skills/90-reference-curator/05-quality-reviewer/desktop/SKILL.md +++ b/custom-skills/90-reference-curator/05-quality-reviewer/desktop/SKILL.md @@ -1,3 +1,10 @@ +--- +name: quality-reviewer +description: | + Content quality evaluator with multi-criteria scoring and decision routing. + Triggers: review quality, score content, QA review, approve refactor reject. +--- + # Quality Reviewer Evaluates distilled content for quality, routes decisions, and triggers refactoring or additional research when needed. diff --git a/custom-skills/90-reference-curator/06-markdown-exporter/desktop/SKILL.md b/custom-skills/90-reference-curator/06-markdown-exporter/desktop/SKILL.md index 2133ddb..4b08cd8 100644 --- a/custom-skills/90-reference-curator/06-markdown-exporter/desktop/SKILL.md +++ b/custom-skills/90-reference-curator/06-markdown-exporter/desktop/SKILL.md @@ -1,3 +1,10 @@ +--- +name: markdown-exporter +description: | + Export approved content to markdown files or JSONL for fine-tuning. + Triggers: export markdown, generate files, create JSONL, export content. +--- + # Markdown Exporter Exports approved content as structured markdown files for Claude Projects or fine-tuning. diff --git a/custom-skills/90-reference-curator/07-pipeline-orchestrator/desktop/SKILL.md b/custom-skills/90-reference-curator/07-pipeline-orchestrator/desktop/SKILL.md index db2bf04..8850cbb 100644 --- a/custom-skills/90-reference-curator/07-pipeline-orchestrator/desktop/SKILL.md +++ b/custom-skills/90-reference-curator/07-pipeline-orchestrator/desktop/SKILL.md @@ -1,3 +1,10 @@ +--- +name: pipeline-orchestrator +description: | + Full reference curation pipeline coordinator with QA loop and state management. + Triggers: run pipeline, orchestrate workflow, full curation, pipeline start. +--- + # Pipeline Orchestrator Coordinates the full reference curation workflow, handling QA loops and state management. diff --git a/custom-skills/91-multi-agent-guide/.claude-plugin/plugin.json b/custom-skills/91-multi-agent-guide/.claude-plugin/plugin.json index f1f5dc9..eb92727 100644 --- a/custom-skills/91-multi-agent-guide/.claude-plugin/plugin.json +++ b/custom-skills/91-multi-agent-guide/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "multi-agent-guide", - "version": "1.0.0", - "description": "Multi-agent collaboration framework for complex projects. Sets up agent hierarchies, ownership rules, guardrails, handoff protocols, and CI/CD integration for Claude, Gemini, Codex, and Human agents working together.", + "version": "2.0.0", + "description": "Multi-agent collaboration framework for complex projects. Sets up agent hierarchies, ownership rules, guardrails, handoff protocols, and CI/CD integration for Claude, Gemini, Codex, and Human agents working together. v2.0 includes consolidated MULTI_AGENT_FRAMEWORK.md template and quick-setup command.", "author": { "name": "OurDigital", "email": "ourdigital@example.com" @@ -12,7 +12,21 @@ "guardrails", "ownership", "ci-cd", - "project-management" + "project-management", + "framework", + "claude", + "gemini", + "codex" ], - "license": "MIT" + "license": "MIT", + "commands": [ + { + "name": "multi-agent-setup", + "description": "Quick setup for multi-agent collaboration" + }, + { + "name": "setup-agents", + "description": "Full interactive multi-agent setup" + } + ] } diff --git a/custom-skills/91-multi-agent-guide/README.md b/custom-skills/91-multi-agent-guide/README.md index fd87475..05f0815 100644 --- a/custom-skills/91-multi-agent-guide/README.md +++ b/custom-skills/91-multi-agent-guide/README.md @@ -1,7 +1,13 @@ -# Multi-Agent Guide Plugin +# Multi-Agent Guide Plugin v2.0 A Claude Code plugin for setting up multi-agent collaboration frameworks in complex software projects. +## What's New in v2.0 + +- **Consolidated Framework**: Single `MULTI_AGENT_FRAMEWORK.md` (~250 lines vs ~2,400) +- **Quick Setup**: `/multi-agent-setup` command for rapid deployment +- **Production-Tested**: Based on dintel-data-agent and our-seo-agent + ## Overview This plugin helps you establish a structured collaboration framework for projects where multiple AI agents (Claude Code, Gemini, Codex, and Human) work together. It provides: @@ -46,15 +52,19 @@ The skill activates automatically when you mention: - "multi-agent guide" - "agent coordination" -### Explicit Command +### Explicit Commands -Use the slash command: +**Quick Setup (Recommended):** +``` +/multi-agent-setup +``` +Rapid deployment with minimal questions. Creates consolidated framework. +**Full Setup:** ``` /setup-agents ``` - -This will guide you through the complete setup process interactively. +Interactive setup with full customization options. ## What Gets Created diff --git a/custom-skills/91-multi-agent-guide/commands/quick-setup.md b/custom-skills/91-multi-agent-guide/commands/quick-setup.md new file mode 100644 index 0000000..52efc10 --- /dev/null +++ b/custom-skills/91-multi-agent-guide/commands/quick-setup.md @@ -0,0 +1,95 @@ +--- +name: multi-agent-setup +description: Quick setup for multi-agent collaboration using the consolidated framework +--- + +# Quick Multi-Agent Setup + +You are setting up multi-agent collaboration using the consolidated MULTI_AGENT_FRAMEWORK.md template. + +## Your Task + +Perform a rapid setup with minimal questions: + +### Step 1: Quick Assessment + +Check the project structure: +```bash +ls -la +ls src/ 2>/dev/null || ls lib/ 2>/dev/null || echo "No src directory" +``` + +### Step 2: Ask ONE Question + +Use AskUserQuestion to ask: + +``` +Which agents will participate in this project? +- Claude + Gemini + Codex (Full team) +- Claude + Codex (Dev focused) +- Claude + Gemini (Research focused) +- Claude only (Solo with guidelines) +``` + +### Step 3: Create Files + +Based on the answer, create these files: + +**Always create:** +``` +.agent-state/tasks.yaml +.agent-state/locks.yaml +MULTI_AGENT_FRAMEWORK.md ← Use template from skill +tools/check-ownership.py +``` + +**If Gemini included:** +``` +GEMINI.md +``` + +**If Codex included:** +``` +CODEX.md +``` + +### Step 4: Customize Framework + +In MULTI_AGENT_FRAMEWORK.md: +1. Replace `{{PROJECT_NAME}}` with actual project name +2. Replace `{{DATE}}` with current date +3. Adjust ownership matrix based on project structure + +### Step 5: Summary + +Output a concise summary: + +```markdown +## Multi-Agent Framework Installed + +**Files Created:** +- `.agent-state/tasks.yaml` +- `.agent-state/locks.yaml` +- `MULTI_AGENT_FRAMEWORK.md` +- `tools/check-ownership.py` +- [Additional agent files if created] + +**Next Steps:** +1. Set agent identity: `export AGENT_AUTHOR=claude` +2. Review ownership matrix in `MULTI_AGENT_FRAMEWORK.md` +3. Start using `[Agent] type(scope): message` commit format + +**Commands:** +- Check ownership: `python tools/check-ownership.py ` +- View tasks: `cat .agent-state/tasks.yaml` +- View locks: `cat .agent-state/locks.yaml` +``` + +## Template Location + +Use the consolidated framework template from: +`${SKILL_DIR}/templates/multi-agent-framework.md` + +## Key Principle + +**Speed over completeness** - Get the framework running quickly. Users can customize later. diff --git a/custom-skills/91-multi-agent-guide/skills/multi-agent-guide/SKILL.md b/custom-skills/91-multi-agent-guide/skills/multi-agent-guide/SKILL.md index 690bbdf..c6ec293 100644 --- a/custom-skills/91-multi-agent-guide/skills/multi-agent-guide/SKILL.md +++ b/custom-skills/91-multi-agent-guide/skills/multi-agent-guide/SKILL.md @@ -1,7 +1,7 @@ --- name: multi-agent-guide description: Use when user asks to "set up multi-agent collaboration", "initialize multi-agent project", "create agent guardrails", "set up team AI collaboration", "configure agent ownership rules", "create agent handoff protocols", mentions "multi-agent guide", "multi-agent setup", "agent coordination", "AI agent collaboration", or wants to configure a project for multiple AI agents (Claude, Gemini, Codex) working together with proper ownership rules, task management, and CI/CD integration. -version: 1.0.0 +version: 2.0.0 allowed-tools: Read, Glob, Grep, Write, Edit, Bash, AskUserQuestion --- @@ -9,6 +9,24 @@ allowed-tools: Read, Glob, Grep, Write, Edit, Bash, AskUserQuestion This skill helps you set up a comprehensive multi-agent collaboration framework for complex software projects where multiple AI agents (Claude Code, Gemini, Codex, and Human) work together. +## What's New in v2.0 + +| Feature | Description | +|---------|-------------| +| **Consolidated Framework** | Single `MULTI_AGENT_FRAMEWORK.md` (~250 lines vs ~2,400 in separate files) | +| **Quick Setup Command** | `/multi-agent-setup` for rapid deployment | +| **Simplified Templates** | One unified template instead of 5 separate files | +| **Production-Tested** | Based on dintel-data-agent and our-seo-agent implementations | + +## Quick Start + +For rapid setup, use: +``` +/multi-agent-setup +``` + +This creates the essential files in under 2 minutes. + ## Overview The multi-agent setup creates: @@ -371,8 +389,9 @@ Supporting files in this skill: | File | Purpose | |------|---------| -| `templates/agents-md.md` | AGENTS.md template | -| `templates/guardrails-md.md` | GUARDRAILS.md template | +| `templates/multi-agent-framework.md` | **Consolidated framework (RECOMMENDED)** | +| `templates/agents-md.md` | AGENTS.md template (legacy) | +| `templates/guardrails-md.md` | GUARDRAILS.md template (legacy) | | `templates/claude-md.md` | CLAUDE.md template | | `templates/gemini-md.md` | GEMINI.md template | | `templates/codex-md.md` | CODEX.md template | @@ -383,6 +402,15 @@ Supporting files in this skill: | `examples/minimal-setup/` | Minimal 2-agent setup example | | `examples/full-setup/` | Full 3-agent setup example | +### Template Selection Guide + +| Use Case | Template | +|----------|----------| +| New projects | `multi-agent-framework.md` (consolidated) | +| Existing projects with separate files | Keep existing AGENTS.md + GUARDRAILS.md | +| Quick setup | `/multi-agent-setup` command | +| Full customization | Individual templates (agents-md, guardrails-md, etc.) | + --- ## Commands diff --git a/custom-skills/91-multi-agent-guide/skills/multi-agent-guide/templates/multi-agent-framework.md b/custom-skills/91-multi-agent-guide/skills/multi-agent-guide/templates/multi-agent-framework.md new file mode 100644 index 0000000..5268f67 --- /dev/null +++ b/custom-skills/91-multi-agent-guide/skills/multi-agent-guide/templates/multi-agent-framework.md @@ -0,0 +1,256 @@ +# Multi-Agent Development Framework + +**Version:** 1.0 +**Applies to:** {{PROJECT_NAME}} +**Last Updated:** {{DATE}} + +--- + +## 1. Agent Hierarchy + +``` + Human (Final Authority) + │ + ▼ + ┌─────────────┐ + │ Claude Code │ ← Lead Agent + │ Orchestrator│ + └──────┬──────┘ + │ + ┌─────────────────┼─────────────────┐ + ▼ ▼ ▼ + ┌─────────┐ ┌─────────┐ ┌─────────┐ + │ Gemini │ │ Codex │ │ Human │ + │Research │ │ Speed │ │ Approve │ + └─────────┘ └─────────┘ └─────────┘ +``` + +| Agent | Role | Scope | +|-------|------|-------| +| **Claude** | Lead / Orchestrator | Architecture, core logic, integration, git, final review | +| **Gemini** | Sub-agent | Google APIs, documentation, research, visualization | +| **Codex** | Sub-agent | Tests, boilerplate, models, docstrings, utilities | +| **Human** | Authority | Business decisions, priorities, release approval | + +--- + +## 2. File Ownership + +### 2.1 Standard Ownership Matrix + +| Pattern | Owner | Examples | +|---------|-------|----------| +| `src/*/core/`, `src/*/services/` | Claude | Business logic, orchestration | +| `src/*/api/`, `src/*/mcp/` | Claude | API clients, MCP servers | +| `src/*/connectors/` | Claude | Data source integrations | +| `src/*/visualization/`, `src/*/app/` | Gemini | Dashboards, charts | +| `docs/*.md` | Gemini | User documentation | +| `tests/` | Codex | All test files | +| `src/*/utils/`, `src/*/models.py` | Codex | Utilities, Pydantic models | + +### 2.2 Shared Files (Require Claude Approval) + +| Files | Rule | +|-------|------| +| `pyproject.toml`, `requirements*.txt` | Claude approves dependency changes | +| `.github/workflows/` | Claude approves CI/CD changes | +| `CLAUDE.md`, `AGENTS.md`, `GUARDRAILS.md` | Claude only | +| `PROJECT_PLAN.md` | Human approves roadmap changes | + +### 2.3 Unrestricted Files + +Any agent can modify: `.agent-state/*`, `.gitignore`, `README.md` + +--- + +## 3. State Management + +All state tracked in `.agent-state/` directory: + +``` +.agent-state/ +├── tasks.yaml # Task registry +└── locks.yaml # File locks +``` + +### 3.1 Task Entry + +```yaml +tasks: + - id: "TASK-001" + agent: "codex" + status: "in_progress" # pending | in_progress | completed | abandoned | blocked + description: "Add unit tests for crawler" + files: ["tests/test_crawler.py"] + claimed_at: "{{DATE}}T10:00:00Z" + expires_at: "{{DATE}}T22:00:00Z" +``` + +### 3.2 Lock Entry + +```yaml +locks: + - path: "src/crawler.py" + agent: "claude" + task_id: "TASK-001" + lock_type: "exclusive" # exclusive | shared | override + expires_at: "{{DATE}}T22:00:00Z" +``` + +### 3.3 Expiration Rules + +| Scenario | Duration | +|----------|----------| +| Standard task | 12 hours | +| Complex refactoring | 24 hours | +| Emergency fix | 4 hours | +| Override (Claude) | 4 hours | + +--- + +## 4. Workflow + +### 4.1 Task Claiming + +```bash +# 1. Set identity +export AGENT_AUTHOR=codex + +# 2. Check state +cat .agent-state/tasks.yaml +cat .agent-state/locks.yaml + +# 3. Claim task (add to tasks.yaml) +git commit -m "[Codex] chore: claim TASK-001" + +# 4. Do work, then commit +git commit -m "[Codex] test(crawler): add unit tests" + +# 5. Complete (update status, remove locks) +git commit -m "[Codex] chore: complete TASK-001" +``` + +### 4.2 Conflict Resolution + +``` +1. Ownership Matrix → Owner has priority + ↓ +2. Active Locks → Lock holder has priority + ↓ +3. Task Assignment → Assigned agent has priority + ↓ +4. Escalate to Claude → Final decision +``` + +--- + +## 5. Handoff Protocols + +### 5.1 Claude → Sub-agent + +```markdown +## Task for [Gemini/Codex] + +**Type:** [API | Docs | Tests | Models] +**Priority:** [High | Medium | Low] + +### Objective +[What needs to be done] + +### Deliverables +- [ ] Implementation +- [ ] Tests (if applicable) +- [ ] Documentation update +``` + +### 5.2 Sub-agent → Claude (Escalation) + +```markdown +## Escalation to Claude + +**Reason:** [Architecture | Integration | Security | Complexity] + +### Completed +[What was finished] + +### Blocking Issue +[What needs Claude's decision] +``` + +--- + +## 6. Commit Standards + +### 6.1 Format + +``` +[Agent] type(scope): description + +Co-Authored-By: Claude Opus 4.5 +``` + +### 6.2 Types & Tags + +| Type | Purpose | Agent Tags | +|------|---------|------------| +| `feat` | New feature | `[Claude]` | +| `fix` | Bug fix | `[Gemini]` | +| `docs` | Documentation | `[Codex]` | +| `test` | Tests | `[Human]` | +| `refactor` | Refactoring | `[CI]` | +| `chore` | Maintenance | | + +--- + +## 7. Quality Gates + +### 7.1 Pre-merge Checklist + +- [ ] Tests pass (`pytest`) +- [ ] Code quality passes (`black`, `isort`, `flake8`, `mypy`) +- [ ] Ownership check passes +- [ ] No hardcoded secrets +- [ ] Documentation updated +- [ ] Agent attribution in commits + +### 7.2 Coverage Targets + +| Scope | Minimum | Target | +|-------|---------|--------| +| Overall | 70% | 80% | +| Core modules | 80% | 90% | +| New code | 80% | 100% | + +--- + +## 8. Quick Reference + +### Environment Setup + +```bash +export AGENT_AUTHOR=claude # claude | gemini | codex | human +pip install -e ".[dev]" +pre-commit install +``` + +### Ownership Lookup + +``` +Core logic, APIs, services → Claude +Visualization, dashboards → Gemini +Documentation → Gemini +Tests, fixtures → Codex +Utilities, models → Codex +Dependencies, CI/CD → Shared (Claude approves) +``` + +### Escalation Triggers + +- Architectural decisions needed +- Multi-file integration required +- Security concerns +- Performance optimization + +--- + +*Generated by Multi-Agent Guide Skill v2.0* diff --git a/custom-skills/AUDIT_REPORT.md b/custom-skills/99_archive/doc/AUDIT_REPORT.md similarity index 100% rename from custom-skills/AUDIT_REPORT.md rename to custom-skills/99_archive/doc/AUDIT_REPORT.md diff --git a/custom-skills/99_archive/REFACTORING_PLAN.md b/custom-skills/99_archive/doc/REFACTORING_PLAN.md similarity index 100% rename from custom-skills/99_archive/REFACTORING_PLAN.md rename to custom-skills/99_archive/doc/REFACTORING_PLAN.md diff --git a/custom-skills/OUR_SKILL_PROJECT_PLAN_v1.1.md b/custom-skills/OUR_SKILL_PROJECT_PLAN_v1.1.md deleted file mode 100644 index fca6544..0000000 --- a/custom-skills/OUR_SKILL_PROJECT_PLAN_v1.1.md +++ /dev/null @@ -1,571 +0,0 @@ -# OurDigital Custom Claude Skill Project Plan - -> **Version**: 1.1 -> **Created**: 2026-01-31 -> **Updated**: 2026-01-31 -> **Author**: OurDigital (Andrew Yim) -> **Purpose**: Claude Desktop & Claude Code 기반 맞춤 Claude Skill 패키지 구현 가이드 - ---- - -## 1. Background - -### 1.1 OurDigital 프로필 - -**OurDigital**은 D.intelligence의 Entrepreneur **Andrew Yim**의 개인 활동 프로필이다. - -| 구분 | 내용 | -|------|------| -| **사업 영역** | Data Analysis, Data Analytics, Google Tag Manager, Data Intelligence Service | -| **컨설팅 서비스** | SMB 영역 종합 컨설팅, 코칭 서비스 (OurDigital Lab 운영) | -| **블로그 채널** | blog.ourdigital.org (Korean), journal.ourdigital.org (English), ourstory.day (Personal Essays) | - -### 1.2 활동 영역 - -- **SEO Specialist**: Technical SEO, On-page SEO, AEO/GEO, Brand Visibility Audit -- **Brand Marketing Consultant**: 브랜드 마케팅, 콘텐츠 마케팅, 디지털 마케팅, 로컬 마케팅 -- **Data Analyst**: 데이터 분석, 마케팅 자동화, GTM 관리 -- **AI/Data Literacy Evangelist**: AI 리터러시, 데이터 리터러시 교육 및 전파 - -### 1.3 프로젝트 목적 - -OurDigital의 전문화된 맞춤 목적 도구를 **Claude Skill 패키지**로 구현하여: - -1. 반복적인 워크플로우의 효율화 -2. 일관된 브랜드 보이스와 품질 유지 -3. 외부 AI 도구(Perplexity, Gemini, DALL-E 등)와의 효과적인 협업 -4. 도메인 특화 지식의 체계적 관리 -5. Claude Desktop과 Claude Code 환경 모두에서 일관된 운용 - ---- - -## 2. Requirements - -### 2.1 Claude Skill 적합성 기준 - -Anthropic의 Agent Skills 가이드 및 skill-creator 프레임워크에 따른 적합성 기준: - -| 기준 | 설명 | -|------|------| -| **명확한 트리거** | "언제 이 스킬을 사용할지"가 분명해야 함 | -| **집중된 범위** | Unix 철학: 1-3가지 핵심 기능에 집중 (800-1,200 words) | -| **재사용 가능한 리소스** | scripts/, references/, assets/로 번들할 가치 | -| **Claude가 모르는 지식** | 절차적 지식, 도메인 특화 정보, 조직 고유 맥락 | -| **명확한 경계** | 다른 스킬과 중복 없이 독립적 작동 | - -### 2.2 OurDigital 스킬 트리거 규칙 ⭐ NEW - -**중요**: 다른 범용 스킬과의 충돌 방지를 위해, ourdigital 스킬은 반드시 `ourdigital` 키워드가 포함된 경우에만 트리거된다. - -| 트리거 패턴 | 예시 | -|------------|------| -| **명시적 호출** | "ourdigital 블로그 작성해줘", "ourdigital research 프롬프트" | -| **스킬명 직접 호출** | "ourdigital-blog로 초안 작성", "ourdigital-designer 사용" | -| **OurDigital 컨텍스트** | "OurDigital 브랜드 가이드 확인", "ourdigital 스킬 만들어줘" | - -**트리거되지 않는 경우**: "블로그 써줘", "리서치 해줘" (일반 요청은 범용 스킬 또는 Claude 기본 기능 사용) - -### 2.3 Progressive Disclosure 설계 원칙 - -``` -Level 1: Metadata (name + description) - 항상 컨텍스트에 로드 (~100 words) -Level 2: SKILL.md body - 스킬 트리거 시 로드 (<5k words, 권장 <2k words) -Level 3: Bundled resources - 필요 시 Claude가 로드 (Unlimited) -``` - -### 2.4 YAML Frontmatter 규약 ⭐ NEW - -Anthropic Claude Skill 권장 규약에 따른 메타데이터 표준: - -```yaml ---- -name: ourdigital-skill-name -description: | - [트리거 조건 명시] ourdigital 키워드와 함께 사용 시 활성화. - [핵심 기능 1줄 요약] - - Triggers: - - "ourdigital [keyword1]", "ourdigital [keyword2]" - - "ourdigital-skill-name [action]" - - Features: - - 기능 1 - - 기능 2 -version: "1.0" -author: OurDigital -environment: Desktop | Code | Both -dependencies: - python: ">=3.11" - packages: ["package1", "package2"] ---- -``` - -### 2.5 스킬 디렉토리 표준 구조 ⭐ UPDATED - -``` -ourdigital-skill-name/ -├── Desktop/ # Claude Desktop 버전 -│ ├── SKILL.md # Desktop용 스킬 정의 -│ ├── scripts/ # Desktop 환경용 스크립트 -│ ├── references/ # 참조 문서 -│ └── assets/ # 템플릿, 이미지 등 -│ -├── Code/ # Claude Code 버전 -│ ├── SKILL.md # Code용 스킬 정의 -│ ├── scripts/ # Code 환경용 스크립트 -│ ├── references/ # 참조 문서 -│ └── assets/ # 템플릿, 이미지 등 -│ -├── shared/ # 공통 리소스 -│ ├── references/ # 공통 참조 문서 -│ ├── assets/ # 공통 에셋 -│ └── templates/ # 공통 템플릿 -│ -├── docs/ # 문서화 ⭐ NEW -│ ├── CHANGELOG.md # 변경 이력 -│ ├── SETUP.md # 설치/설정 가이드 -│ └── logs/ # 업데이트 로그 파일 -│ -└── README.md # 스킬 개요 -``` - ---- - -## 3. Package Environment Standards ⭐ NEW - -### 3.1 공통 환경 요건 - -OurDigital 스킬 패키지는 일관된 환경에서 운용되도록 다음 표준을 따른다: - -| 항목 | 표준 | 비고 | -|------|------|------| -| **Python 버전** | >= 3.11 | pyenv 또는 conda로 관리 | -| **가상 환경** | `.venv-ourdigital/` | 프로젝트 루트에 위치 | -| **환경 변수 파일** | `.env.ourdigital` | 민감 정보 포함, .gitignore 등록 | -| **설정 파일** | `config/ourdigital.yaml` | 스킬 공통 설정 | - -### 3.2 인증 및 자격증명 관리 - -``` -~/.ourdigital/ -├── credentials/ -│ ├── notion.json # Notion API 토큰 -│ ├── ghost.json # Ghost Admin API 키 -│ ├── google.json # Google API 자격증명 -│ └── figma.json # Figma API 토큰 -├── config.yaml # 전역 설정 -└── .env # 환경 변수 (심볼릭 링크) -``` - -### 3.3 환경 변수 표준 - -```bash -# .env.ourdigital -OURDIGITAL_ENV=development|production -OURDIGITAL_CONFIG_PATH=~/.ourdigital/config.yaml -OURDIGITAL_CREDENTIALS_PATH=~/.ourdigital/credentials/ - -# Notion -NOTION_API_TOKEN=secret_xxxxx -NOTION_WORKING_WITH_AI_DB=f8f19ede-32bd-43ac-9f60-0651f6f40afe - -# Ghost CMS -GHOST_BLOG_URL=https://blog.ourdigital.org -GHOST_BLOG_ADMIN_KEY=xxxxx -GHOST_JOURNAL_URL=https://journal.ourdigital.org -GHOST_JOURNAL_ADMIN_KEY=xxxxx -``` - -### 3.4 패키지 의존성 관리 - -``` -ourdigital-skills/ -├── pyproject.toml # 전체 패키지 의존성 -├── requirements/ -│ ├── base.txt # 공통 의존성 -│ ├── desktop.txt # Desktop 전용 -│ └── code.txt # Code 전용 -└── setup.py # 패키지 설치 스크립트 -``` - ---- - -## 4. Skill Architecture - -### 4.1 전체 스킬 구성 (10개) - -``` -┌─────────────────────────────────────────────────────────────────┐ -│ META LAYER (기반 스킬) │ -│ ┌─────────────────────────┐ ┌─────────────────────────────┐ │ -│ │ ourdigital-skill-creator│ │ ourdigital-brand-guide │ │ -│ │ (스킬 생성/관리) │ │ (브랜드 기준/스타일 가이드) │ │ -│ └─────────────────────────┘ └─────────────────────────────┘ │ -└─────────────────────────────────────────────────────────────────┘ - │ - ▼ -┌─────────────────────────────────────────────────────────────────┐ -│ CONTENT LAYER (콘텐츠 제작) │ -│ ┌──────────────────┐ ┌──────────────────┐ ┌─────────────────┐ │ -│ │ ourdigital-blog │ │ourdigital-journal│ │ourdigital- │ │ -│ │ (한국어 블로그) │ │(영문 에세이) │ │research │ │ -│ └──────────────────┘ └──────────────────┘ │(리서치 프롬프트) │ │ -│ └─────────────────┘ │ -└─────────────────────────────────────────────────────────────────┘ - │ - ▼ -┌─────────────────────────────────────────────────────────────────┐ -│ PRODUCTION LAYER (제작 지원) │ -│ ┌──────────────────┐ ┌──────────────────┐ ┌─────────────────┐ │ -│ │ourdigital-document│ │ourdigital-designer│ │ourdigital- │ │ -│ │(문서/프레젠테이션)│ │(비주얼 프롬프트) │ │ad-manager │ │ -│ └──────────────────┘ └──────────────────┘ │(광고 카피) │ │ -│ └─────────────────┘ │ -└─────────────────────────────────────────────────────────────────┘ - │ - ▼ -┌─────────────────────────────────────────────────────────────────┐ -│ SUPPORT LAYER (업무 지원) │ -│ ┌─────────────────────────┐ ┌─────────────────────────────┐ │ -│ │ ourdigital-trainer │ │ ourdigital-backoffice │ │ -│ │ (교육자료/평가) │ │ (견적/계약/비용분석) │ │ -│ └─────────────────────────┘ └─────────────────────────────┘ │ -└─────────────────────────────────────────────────────────────────┘ -``` - -### 4.2 개별 스킬 정의 - -#### 4.2.1 ourdigital-skill-creator (메타 스킬) - -| 항목 | 내용 | -|------|------| -| **역할** | 스킬 적합성 평가, 인터랙티브 요구사항 분석, 스킬 제작, 이력 관리 | -| **트리거** | "ourdigital 스킬 만들기", "ourdigital skill 적합성", "ourdigital 스킬 제작" | -| **핵심 기능** | 1) 니즈의 Claude Skill 적합성 평가 2) **인터랙티브 질의-응답 기반 요구사항 정의** 3) 최적화된 스킬 생성 4) **Notion DB 이력 관리** | -| **특수 기능** | 수정 이력 관리, 학습 포인트 축적, Notion 연동 | - -**인터랙티브 워크플로우** ⭐ NEW: -``` -1. [니즈 파악] 사용자의 초기 요청 수신 - ↓ -2. [적합성 검토] Claude Skill 적합성 평가 질문 - ↓ -3. [요구사항 정의] 단계별 질의-응답 (최소 3~5개 질문) - - 스킬 목적과 핵심 기능 - - 트리거 조건과 사용 시나리오 - - 필요한 외부 도구/리소스 - - 기대 출력 형식 - - Desktop/Code 환경 요구사항 - ↓ -4. [스킬 생성] 요구사항 기반 스킬 초안 생성 - ↓ -5. [검증] 사용자 확인 및 피드백 반영 - ↓ -6. [저장] Notion DB + docs/ 이력 기록 -``` - -**번들 리소스:** -``` -ourdigital-skill-creator/ -├── Desktop/ -│ └── SKILL.md -├── Code/ -│ └── SKILL.md -├── shared/ -│ ├── scripts/ -│ │ ├── init_skill.py -│ │ ├── validate_skill.py -│ │ └── sync_notion.py # Notion 연동 -│ ├── references/ -│ │ ├── suitability-criteria.md -│ │ ├── skill-patterns.md -│ │ └── qa-templates.md # 질의 템플릿 -│ └── templates/ -│ └── skill-template/ -├── docs/ -│ ├── CHANGELOG.md -│ └── logs/ -└── README.md -``` - ---- - -#### 4.2.2 ourdigital-brand-guide (기준 참조 스킬) - -| 항목 | 내용 | -|------|------| -| **역할** | 글쓰기/페르소나/시각 스타일 기준 관리, 브랜드 적합성 판별 | -| **트리거** | "ourdigital 브랜드 가이드", "ourdigital 스타일 체크", "ourdigital 톤앤매너" | -| **핵심 기능** | 1) 글쓰기 스타일 기준 2) 페르소나 특징/스타일 3) 시각 요소 기준 4) 산출물 브랜드 적합성 판별 | - ---- - -#### 4.2.3 ourdigital-blog (콘텐츠 제작) - -| 항목 | 내용 | -|------|------| -| **역할** | 한국어 블로그 초안 작성, SEO 최적화 편집 | -| **트리거** | "ourdigital 블로그", "ourdigital blog 초안", "ourdigital 한국어 포스트" | -| **핵심 기능** | 1) 블로그 초안 작성 2) SEO 메타데이터 생성 3) Ghost CMS 포맷 | -| **출력 채널** | blog.ourdigital.org (Ghost CMS) | - ---- - -#### 4.2.4 ourdigital-journal (콘텐츠 제작) - -| 항목 | 내용 | -|------|------| -| **역할** | 영문 에세이/리서치 작성 및 포스팅 | -| **트리거** | "ourdigital journal", "ourdigital 영문 에세이", "ourdigital English article" | -| **핵심 기능** | 1) 영문 에세이 작성 2) 리서치 기반 아티클 3) 학술적 글쓰기 스타일 | -| **출력 채널** | journal.ourdigital.org (Ghost CMS) | - ---- - -#### 4.2.5 ourdigital-research (프롬프트 엔지니어링) - -| 항목 | 내용 | -|------|------| -| **역할** | Deep Research용 구조화된 프롬프트 생성 | -| **트리거** | "ourdigital research 프롬프트", "ourdigital deep research", "ourdigital 조사 요청" | -| **핵심 기능** | 1) 조사 목적/용도 확인 대화 2) 구조화된 리서치 프롬프트 생성 3) 외부 도구 최적화 | - ---- - -#### 4.2.6 ourdigital-document (문서 제작) - -| 항목 | 내용 | -|------|------| -| **역할** | 문서 구성/초안 작성, 프레젠테이션 프롬프트 생성 | -| **트리거** | "ourdigital 문서", "ourdigital 기획서", "ourdigital 프레젠테이션" | -| **핵심 기능** | 1) 문서 구성 및 개요 2) Word/Google Doc/Markdown 초안 3) Gamma/Figma용 프롬프트 | - ---- - -#### 4.2.7 ourdigital-designer (프롬프트 엔지니어링) - -| 항목 | 내용 | -|------|------| -| **역할** | Visual AI용 구조화된 프롬프트 생성, Figma 연동 | -| **트리거** | "ourdigital 디자인", "ourdigital 비주얼", "ourdigital 이미지 생성" | -| **핵심 기능** | 1) 디자인 방향 설정 2) AI 이미지 생성 프롬프트 3) Figma Connector 연동 | - ---- - -#### 4.2.8 ourdigital-ad-manager (마케팅 실행) - -| 항목 | 내용 | -|------|------| -| **역할** | 광고 카피라이팅, 키워드 검색량 조사 | -| **트리거** | "ourdigital 광고 카피", "ourdigital 검색 광고", "ourdigital 키워드" | -| **핵심 기능** | 1) 검색 광고 카피 2) 디스플레이 광고 카피 3) 브랜디드 콘텐츠 4) 키워드 검색량 웹 서치 | - ---- - -#### 4.2.9 ourdigital-trainer (교육 지원) - -| 항목 | 내용 | -|------|------| -| **역할** | 교육자료 구성, 진행 계획, 참여자 평가 | -| **트리거** | "ourdigital 교육", "ourdigital 트레이닝", "ourdigital 워크샵" | -| **핵심 기능** | 1) 주제별 교육자료 구성 2) 교육 진행 계획 3) 참여자 평가 설계 | - ---- - -#### 4.2.10 ourdigital-backoffice (업무 지원) - -| 항목 | 내용 | -|------|------| -| **역할** | 견적서, 서비스 소개서, 계약서, 비용 분석 | -| **트리거** | "ourdigital 견적서", "ourdigital 계약서", "ourdigital 비용 분석" | -| **핵심 기능** | 1) 견적서 작성 2) 서비스 소개서 3) 계약서 초안 (법적 검토 필요 명시) 4) 비용 분석 | - ---- - -## 5. Development History Management ⭐ NEW - -### 5.1 Notion Database 연동 - -**대상 데이터베이스**: [Working with AI](https://www.notion.so/dintelligence/f529bd7b67ce4033bb70ce951d65c9e8) - -| 필드 | 용도 | -|------|------| -| **Name** | 스킬명 + 버전 (예: "ourdigital-blog v1.2") | -| **Type** | "Skill Development" | -| **Category** | "OurDigital Skills" | -| **AI used** | "Claude Opus" 또는 "Claude Code" | -| **Topic** | 해당 스킬 카테고리 | - -**저장 시점**: -- 스킬 신규 생성 시 -- 스킬 수정/업데이트 시 -- 버전 릴리즈 시 - -### 5.2 로컬 문서 관리 - -각 스킬의 `docs/` 디렉토리에 다음 파일 유지: - -```markdown -# docs/CHANGELOG.md - -## [1.1.0] - 2026-01-31 - -### Added -- 새로운 기능 설명 - -### Changed -- 변경된 기능 설명 - -### Fixed -- 수정된 버그 설명 - -### Notion Ref -- https://notion.so/page-id -``` - -```markdown -# docs/logs/2026-01-31-update.md - -## 업데이트 정보 -- **일시**: 2026-01-31 15:30 KST -- **버전**: 1.0 → 1.1 -- **작업자**: Andrew Yim -- **Claude 세션**: [링크] - -## 변경 내용 -... - -## Notion 동기화 -- DB 레코드 ID: xxx -- 동기화 시간: 2026-01-31 15:35 KST -``` - ---- - -## 6. Implementation Plan - -### 6.1 구현 단계 - -``` -Phase 1: 기반 스킬 (Week 1-2) -├── ourdigital-skill-creator (Notion 연동 포함) -└── ourdigital-brand-guide - -Phase 2: 핵심 콘텐츠 스킬 (Week 3-4) -├── ourdigital-blog -├── ourdigital-journal -└── ourdigital-research - -Phase 3: 제작 지원 스킬 (Week 5-6) -├── ourdigital-document -├── ourdigital-designer -└── ourdigital-ad-manager - -Phase 4: 업무 지원 스킬 (Week 7-8) -├── ourdigital-trainer -└── ourdigital-backoffice -``` - -### 6.2 Phase 1 상세 계획 - -#### Task 1.1: ourdigital-skill-creator 구현 - -| 단계 | 작업 | 산출물 | -|------|------|--------| -| 1 | 디렉토리 구조 생성 (Desktop/Code 분리) | `/ourdigital-skill-creator/` | -| 2 | Desktop용 SKILL.md 작성 | `Desktop/SKILL.md` | -| 3 | Code용 SKILL.md 작성 | `Code/SKILL.md` | -| 4 | 인터랙티브 Q&A 템플릿 | `shared/references/qa-templates.md` | -| 5 | Notion 동기화 스크립트 | `shared/scripts/sync_notion.py` | -| 6 | 공통 환경 설정 | `pyproject.toml`, `.env.ourdigital` | -| 7 | 검증 및 테스트 | 실제 스킬 생성 테스트 | - -### 6.3 Claude Code 실행 가이드 - -```bash -# 프로젝트 루트 설정 -cd /path/to/ourdigital-skills - -# 가상 환경 생성 -python -m venv .venv-ourdigital -source .venv-ourdigital/bin/activate - -# 의존성 설치 -pip install -r requirements/base.txt - -# Phase 1 실행 (Claude Code) -claude "OUR_SKILL_PROJECT_PLAN.md를 참조하여 ourdigital-skill-creator 스킬을 구현해줘. Code 버전으로 시작해줘." - -# 스킬 검증 -python shared/scripts/validate_skill.py ourdigital-skill-creator - -# Notion 동기화 -python shared/scripts/sync_notion.py ourdigital-skill-creator --action=create -``` - ---- - -## 7. Quality Checklist - -### 7.1 스킬 완성도 체크리스트 - -각 스킬 구현 완료 시 확인: - -- [ ] Desktop/SKILL.md 완성 (frontmatter 규약 준수) -- [ ] Code/SKILL.md 완성 (frontmatter 규약 준수) -- [ ] description에 `ourdigital` 트리거 키워드 포함 -- [ ] SKILL.md body 800-1,200 words 이내 -- [ ] shared/ 공통 리소스 완성 -- [ ] docs/CHANGELOG.md 초기화 -- [ ] 환경 변수 문서화 (docs/SETUP.md) -- [ ] 실제 사용 시나리오 테스트 -- [ ] Notion DB 레코드 생성 - -### 7.2 스킬 간 의존성 확인 - -``` -ourdigital-skill-creator ──┬── 모든 스킬 생성/관리/이력 관리 - │ -ourdigital-brand-guide ────┼── 모든 산출물 품질 기준 - │ -ourdigital-blog ───────────┼── ourdigital-research (리서치 프롬프트) - │ ourdigital-designer (피처드 이미지) - │ -ourdigital-document ───────┼── ourdigital-brand-guide (브랜드 적합성) - │ ourdigital-designer (프레젠테이션 비주얼) -``` - ---- - -## 8. Appendix - -### 8.1 참조 문서 - -| 문서 | 위치 | 용도 | -|------|------|------| -| Anthropic Agent Skills | `/mnt/project/02-agent-skills.md` | 스킬 설계 원칙 | -| skill-creator | `/mnt/skills/examples/skill-creator/` | 기본 스킬 생성 프레임워크 | -| jamie-journal-editor | `/mnt/skills/user/jamie-journal-editor/` | 참조 패턴 (유사 블로그 에디터) | -| ourdigital-research-publisher | `/mnt/skills/user/ourdigital-research-publisher/` | 기존 리서치 스킬 | - -### 8.2 외부 도구 연동 - -| 도구 | 연동 방식 | 관련 스킬 | -|------|----------|----------| -| Ghost CMS | API / Admin | ourdigital-blog, ourdigital-journal | -| Notion | MCP Connector + API | 전체 (문서 저장, 이력 관리) | -| Perplexity | 프롬프트 생성 → 수동 실행 | ourdigital-research | -| Gamma | 프롬프트 생성 → MCP | ourdigital-document | -| Figma | MCP Connector | ourdigital-designer | -| DALL-E/Midjourney | 프롬프트 생성 → 수동 실행 | ourdigital-designer | - -### 8.3 버전 이력 - -| 버전 | 날짜 | 변경 내용 | -|------|------|----------| -| 1.0 | 2026-01-31 | 초기 프로젝트 계획 수립 | -| 1.1 | 2026-01-31 | 트리거 규칙 추가, Desktop/Code 분리, 환경 표준화, Notion 이력 관리 | - ---- - -**End of Document** diff --git a/custom-skills/_ourdigital-shared/README.md b/custom-skills/_ourdigital-shared/README.md index af7852f..fd5cbca 100644 --- a/custom-skills/_ourdigital-shared/README.md +++ b/custom-skills/_ourdigital-shared/README.md @@ -1,129 +1,155 @@ -# OurDigital Skills - Shared Environment +# OurDigital Shared Environment -Shared configuration, dependencies, and environment setup for all OurDigital Claude Skills. +Shared configuration, dependencies, and installation tools for OurDigital Skills package. -## Quick Setup - -### 1. Create Virtual Environment +## Quick Install ```bash -cd /path/to/our-claude-skills/custom-skills -python -m venv .venv-ourdigital -source .venv-ourdigital/bin/activate # macOS/Linux +# Clone the repository (on new machine) +git clone https://github.com/ourdigital/our-claude-skills.git +cd our-claude-skills/custom-skills/_ourdigital-shared + +# Run installer +./install.sh ``` -### 2. Install Dependencies +## Installation Options ```bash -# For Claude Code environment -pip install -r _ourdigital-shared/requirements/code.txt - -# For Claude Desktop environment -pip install -r _ourdigital-shared/requirements/desktop.txt - -# Or install as package -pip install -e _ourdigital-shared/ +./install.sh # Full interactive install +./install.sh --update # Update existing installation +./install.sh --uninstall # Remove installation +./install.sh --validate # Check installation status +./install.sh --skip-creds # Skip credentials setup +./install.sh --skip-venv # Skip virtual environment +./install.sh --help # Show all options ``` -### 3. Configure Environment Variables +## What Gets Installed -```bash -# Copy template -cp _ourdigital-shared/.env.ourdigital.template ~/.env.ourdigital - -# Edit with your credentials -nano ~/.env.ourdigital -``` - -### 4. Set Up Credentials Directory - -```bash -mkdir -p ~/.ourdigital/credentials -# Add your credential files: -# - ~/.ourdigital/credentials/notion.json -# - ~/.ourdigital/credentials/ghost.json -# - ~/.ourdigital/credentials/google.json -``` +| Component | Location | Description | +|-----------|----------|-------------| +| Environment file | `~/.env.ourdigital` | API keys and secrets | +| Config directory | `~/.ourdigital/` | Configuration and credentials | +| Virtual environment | `.venv-ourdigital/` | Python dependencies | ## Directory Structure ``` -_ourdigital-shared/ -├── pyproject.toml # Package configuration -├── .env.ourdigital.template # Environment variables template -├── requirements/ -│ ├── base.txt # Common dependencies -│ ├── desktop.txt # Desktop-specific -│ └── code.txt # Code-specific -├── config/ -│ └── ourdigital.yaml # Global configuration -└── README.md # This file +~/.ourdigital/ +├── config.yaml # Global configuration +├── credentials/ # Service account JSONs +│ └── *.json +└── logs/ # Installation logs + +~/.env.ourdigital # Environment variables (chmod 600) ``` -## Configuration +## Manual Setup -### Environment Variables +If you prefer manual setup: -Key variables in `.env.ourdigital`: - -| Variable | Description | -|----------|-------------| -| `OURDIGITAL_ENV` | Environment (development/production) | -| `NOTION_API_TOKEN` | Notion integration token | -| `NOTION_WORKING_WITH_AI_DB` | Primary Notion database ID | -| `GHOST_BLOG_ADMIN_KEY` | Ghost CMS admin API key | - -### Config File - -`config/ourdigital.yaml` contains: -- Brand settings (name, tagline, values) -- Channel configurations -- Color palette -- Typography settings -- Skill numbering conventions -- Export paths - -## Usage in Skills - -### Loading Configuration - -```python -import yaml -from pathlib import Path - -def load_config(): - config_path = Path(__file__).parent.parent / "_ourdigital-shared/config/ourdigital.yaml" - with open(config_path) as f: - return yaml.safe_load(f) - -config = load_config() -print(config['brand']['tagline']) +### 1. Create directories +```bash +mkdir -p ~/.ourdigital/credentials +chmod 700 ~/.ourdigital ~/.ourdigital/credentials ``` -### Loading Environment - -```python -from dotenv import load_dotenv -import os - -load_dotenv(os.path.expanduser("~/.env.ourdigital")) - -notion_token = os.getenv("NOTION_API_TOKEN") +### 2. Copy environment template +```bash +cp .env.ourdigital.template ~/.env.ourdigital +chmod 600 ~/.env.ourdigital ``` -## Skill Numbering +### 3. Edit credentials +```bash +nano ~/.env.ourdigital +# Add your API keys +``` -| Range | Category | -|-------|----------| -| 01-09 | OurDigital Core (brand, blog, journal, research, etc.) | -| 10 | Meta (skill-creator) | -| 11-19 | SEO Tools | -| 20-29 | GTM/Analytics Tools | -| 31-39 | Notion Tools | -| 40-49 | Jamie Clinic Tools | +### 4. Create virtual environment +```bash +python3 -m venv .venv-ourdigital +source .venv-ourdigital/bin/activate +pip install -r requirements/base.txt +``` -## Version +## Credentials Required -- Package Version: 1.0.0 -- Python Requirement: >= 3.11 -- Author: OurDigital (Andrew Yim) +| Service | Variable | How to Get | +|---------|----------|------------| +| Notion | `NOTION_API_TOKEN` | [Notion Integrations](https://www.notion.so/my-integrations) | +| Ghost Blog | `GHOST_BLOG_ADMIN_KEY` | Ghost Admin → Integrations | +| Ghost Journal | `GHOST_JOURNAL_ADMIN_KEY` | Ghost Admin → Integrations | +| Figma | `FIGMA_ACCESS_TOKEN` | [Figma Settings](https://www.figma.com/developers/api#access-tokens) | + +### Using 1Password CLI + +If you have 1Password CLI (`op`) installed: +```bash +# Sign in +eval $(op signin) + +# Installer will auto-fetch credentials +./install.sh +``` + +## Validation + +Check your installation status: + +```bash +# Quick check +./install.sh --validate + +# Detailed check +python scripts/validate_install.py --verbose +``` + +## Cross-Machine Sync + +To sync skills to another machine: + +```bash +# On new machine +git clone https://github.com/ourdigital/our-claude-skills.git +cd our-claude-skills/custom-skills/_ourdigital-shared +./install.sh + +# Credentials need to be set up separately (security) +# Either use 1Password CLI or manually copy ~/.env.ourdigital +``` + +## Troubleshooting + +### Permission denied +```bash +chmod +x install.sh +``` + +### Python version +```bash +# Check version (need 3.11+) +python3 --version + +# Use pyenv if needed +pyenv install 3.11 +pyenv local 3.11 +``` + +### Missing credentials +```bash +# Check what's missing +python scripts/validate_install.py --verbose +``` + +## File Reference + +| File | Purpose | +|------|---------| +| `install.sh` | Main installer script | +| `.env.ourdigital.template` | Environment template | +| `config/ourdigital.yaml` | Default configuration | +| `requirements/base.txt` | Common dependencies | +| `requirements/code.txt` | Claude Code dependencies | +| `scripts/validate_install.py` | Installation validator | diff --git a/custom-skills/_ourdigital-shared/claude-ai-export/INSTALL-CLAUDE-AI.md b/custom-skills/_ourdigital-shared/claude-ai-export/INSTALL-CLAUDE-AI.md new file mode 100644 index 0000000..ae2186b --- /dev/null +++ b/custom-skills/_ourdigital-shared/claude-ai-export/INSTALL-CLAUDE-AI.md @@ -0,0 +1,53 @@ +# Installing OurDigital Skills in Claude.ai + +## Option 1: Upload Bundle (Recommended) + +1. Go to [claude.ai](https://claude.ai) +2. Create a new **Project** (e.g., "OurDigital Workspace") +3. Click **Project Knowledge** → **Add Content** +4. Upload `ourdigital-skills-bundle.md` +5. Done! Use "our" or "ourdigital" prefix to trigger skills + +## Option 2: Add as Custom Instructions + +1. Go to Claude.ai → **Settings** → **Custom Instructions** +2. Copy the content from `ourdigital-skills-bundle.md` +3. Paste into Custom Instructions +4. Save + +## Option 3: Individual Skills + +Upload only the skills you need from the `individual/` folder: +- `01-brand-guide.md` +- `02-blog.md` +- `03-journal.md` +- etc. + +## Testing After Install + +Try these prompts: +``` +our brand guide +our blog "AI 마케팅의 미래" +our research SEO trends 2026 +our 견적서 GTM 구축 +``` + +## Files in This Export + +``` +claude-ai-export/ +├── INSTALL-CLAUDE-AI.md # This file +├── ourdigital-skills-bundle.md # All 10 skills combined +└── individual/ # Individual skill files + ├── 01-brand-guide.md + ├── 02-blog.md + └── ... +``` + +## Updating Skills + +When skills are updated: +1. Pull latest from GitHub +2. Re-upload the bundle file +3. Or regenerate with: `python scripts/export_for_claude_ai.py` diff --git a/custom-skills/_ourdigital-shared/claude-ai-export/individual/01-brand-guide.md b/custom-skills/_ourdigital-shared/claude-ai-export/individual/01-brand-guide.md new file mode 100644 index 0000000..1350237 --- /dev/null +++ b/custom-skills/_ourdigital-shared/claude-ai-export/individual/01-brand-guide.md @@ -0,0 +1,137 @@ +--- +name: ourdigital-brand-guide +description: | + OurDigital brand standards and style guide. + Triggers (ourdigital or our prefix): + - "our brand guide", "our 브랜드 가이드", "our 톤앤매너" +--- + +# OurDigital Brand Guide + +**Purpose**: Brand standards and style +**Triggers**: Use "our" or "ourdigital" prefix + +--- + +# OurDigital Brand Guide + +Reference skill for OurDigital brand standards, writing style, and visual identity. + +## Activation + +Activate with "ourdigital" or "our" prefix: +- "ourdigital 브랜드 가이드" / "our 브랜드 가이드" +- "ourdigital 톤앤매너 체크" / "our 톤앤매너" +- "our brand guide", "our style check" + +## Brand Foundation + +### Core Identity + +| Element | Content | +|---------|---------| +| **Brand Name** | OurDigital Clinic | +| **Tagline** | 우리 디지털 클리닉 \| Your Digital Health Partner | +| **Mission** | 디지털 마케팅 클리닉 for SMBs, 자영업자, 프리랜서, 비영리단체 | +| **Promise** | 진단-처방-측정 가능한 성장 | + +### Core Values + +| 가치 | English | 클리닉 메타포 | +|------|---------|--------------| +| 데이터 중심 | Data-driven | 정밀 검사 | +| 실행 지향 | In-Action | 실행 가능한 처방 | +| 마케팅 과학 | Marketing Science | 근거 중심 의학 | + +### Brand Philosophy + +**"Precision + Empathy + Evidence"** + +## Channel Tone Matrix + +| Channel | Domain | Personality | Tone | +|---------|--------|-------------|------| +| Main Hub | ourdigital.org | Professional & Confident | Data-driven, Solution-oriented | +| Blog | blog.ourdigital.org | Analytical & Personal | Educational, Thought-provoking | +| Journal | journal.ourdigital.org | Conversational & Poetic | Reflective, Cultural Observer | +| OurStory | ourstory.day | Intimate & Reflective | Authentic, Personal Journey | + +## Writing Style Characteristics + +### Korean (한국어) + +1. **철학-기술 융합체**: 기술 분석과 실존적 질문을 자연스럽게 결합 +2. **역설 활용**: 긴장과 모순 구조로 논증 전개 +3. **수사적 질문**: 선언적 권위보다 질문을 통한 참여 +4. **우울한 낙관주의**: 불안과 상실을 인정하되 절망하지 않음 + +### English + +1. **Philosophical-Technical Hybridization**: Technical content with human implications +2. **Paradox as Device**: Structure arguments around tensions +3. **Rhetorical Questions**: Interrogative engagement over authority +4. **Melancholic Optimism**: Acknowledge anxiety without despair + +### Do's and Don'ts + +**Do's:** +- Use paradox to structure arguments +- Ask rhetorical questions to engage readers +- Connect technical content to human implications +- Blend Korean and English naturally for technical terms +- Reference historical context and generational shifts + +**Don'ts:** +- Avoid purely declarative, authoritative tone +- Don't separate technical analysis from cultural impact +- Avoid simplistic or overly optimistic narratives +- Don't provide prescriptive conclusions without exploration + +## Visual Identity + +### Primary Colors + +| Token | Color | HEX | Usage | +|-------|-------|-----|-------| +| --d-black | D.Black | #221814 | Footer, dark backgrounds | +| --d-olive | D.Olive | #cedc00 | Primary accent, CTA buttons | +| --d-green | D.Green | #287379 | Links hover, secondary accent | +| --d-blue | D.Blue | #0075c0 | Links | +| --d-beige | D.Beige | #f2f2de | Light text on dark | +| --d-gray | D.Gray | #ebebeb | Alt backgrounds | + +### Typography + +- **Korean**: Noto Sans KR +- **English**: Noto Sans, Inter +- **Grid**: 12-column responsive layout + +## Brand Compliance Check + +When reviewing content, verify: + +1. **Tone Match**: Does it match the channel's personality? +2. **Value Alignment**: Reflects Data-driven, In-Action, Marketing Science? +3. **Philosophy Check**: Precision + Empathy + Evidence present? +4. **Language Style**: Appropriate blend of Korean/English terms? +5. **Visual Consistency**: Uses approved color palette? + +## Quick Reference + +### Key Messages + +| Use | Message | +|-----|---------| +| Tagline | 우리 디지털 클리닉 \| Your Digital Health Partner | +| Value Prop | 데이터로 진단하고, 실행으로 처방합니다 | +| Process | 진단 → 처방 → 측정 | +| Differentiator | 25년 경험의 마케팅 사이언티스트 | + +### CTA Patterns + +| Context | CTA | +|---------|-----| +| General | 무료 상담 신청하기 | +| SEO | SEO 진단 신청하기 | + +[... see full documentation for more ...] \ No newline at end of file diff --git a/custom-skills/_ourdigital-shared/claude-ai-export/individual/02-blog.md b/custom-skills/_ourdigital-shared/claude-ai-export/individual/02-blog.md new file mode 100644 index 0000000..355a28f --- /dev/null +++ b/custom-skills/_ourdigital-shared/claude-ai-export/individual/02-blog.md @@ -0,0 +1,137 @@ +--- +name: ourdigital-blog +description: | + Korean blog draft creation for blog.ourdigital.org. + Triggers (ourdigital or our prefix): + - "our blog", "our 블로그", "our 한국어 포스트" +--- + +# OurDigital Blog + +**Purpose**: Korean blog drafts +**Triggers**: Use "our" or "ourdigital" prefix + +--- + +# OurDigital Blog + +Korean blog draft creation skill for blog.ourdigital.org. + +## Activation + +Activate with "ourdigital" or "our" prefix: +- "ourdigital 블로그 써줘" / "our 블로그 써줘" +- "ourdigital blog draft" / "our blog draft" +- "our 한국어 포스트 [주제]" + +## Channel Profile + +| Field | Value | +|-------|-------| +| **URL** | blog.ourdigital.org | +| **Language** | Korean (전문용어 영문 병기) | +| **Tone** | Analytical & Personal, Educational | +| **Platform** | Ghost CMS | +| **Frequency** | 주 1-2회 | +| **Length** | 1,500-3,000자 | + +## Workflow + +### Phase 1: Topic Clarification + +Ask clarifying questions (max 3): + +1. **주제 확인**: 정확한 토픽이 무엇인가요? +2. **대상 독자**: 타겟 오디언스는? (마케터/개발자/경영진/일반) +3. **깊이 수준**: 개요 / 심층분석 / 실무가이드 중 어느 수준? + +### Phase 2: Research (Optional) + +If topic requires current information: +- Use `web_search` for latest trends/data +- Use `Notion:notion-search` for past research +- Reference internal documents if available + +### Phase 3: Draft Generation + +Generate blog draft following brand style: + +**Structure:** +``` +1. 도입부 (Hook + Context) +2. 본론 (3-5 핵심 포인트) + - 각 포인트: 주장 → 근거 → 함의 +3. 결론 (Summary + 열린 질문) +``` + +**Writing Style:** +- 철학-기술 융합: 기술 분석 + 인간적 함의 +- 역설 활용: 긴장/모순으로 논증 구조화 +- 수사적 질문: 독자 참여 유도 +- 우울한 낙관주의: 불안 인정, 절망 거부 + +**Language Rules:** +- 한글 기본, 전문용어는 영문 병기 + - 예: "검색엔진최적화(SEO)" +- 문장: 복합문 허용, 상호연결된 개념 반영 +- 단락: 관찰 → 분석 → 철학적 함의 + +### Phase 4: SEO Metadata + +Generate metadata: + +```yaml +title: [60자 이내, 키워드 포함] +meta_description: [155자 이내] +slug: [영문 URL slug] +tags: [3-5개 태그] +featured_image_prompt: [DALL-E/Midjourney 프롬프트] +``` + +### Phase 5: Output Format + +**Markdown Output:** +```markdown +--- +title: "포스트 제목" +meta_description: "메타 설명" +slug: "url-slug" +tags: ["tag1", "tag2"] +--- + +# 포스트 제목 + +[본문 내용] + +--- +*Originally drafted with Claude for OurDigital Blog* +``` + +## Ghost CMS Integration + +Export options: +1. **Markdown file** → Ulysses → Ghost +2. **Direct API** → Ghost Admin API (if configured) + +API endpoint: `GHOST_BLOG_URL` from environment + +## Brand Compliance + +Before finalizing, verify: +- [ ] 분석적 + 개인적 톤 유지 +- [ ] 기술 내용에 인간적 함의 포함 +- [ ] 수사적 질문으로 독자 참여 +- [ ] 전문용어 영문 병기 +- [ ] 1,500-3,000자 범위 + +## Quick Commands + +| Command | Action | +|---------|--------| +| "ourdigital 블로그 [주제]" | Full workflow | +| "ourdigital blog SEO" | SEO metadata only | +| "ourdigital blog 편집" | Edit existing draft | + +## References + +[... see full documentation for more ...] \ No newline at end of file diff --git a/custom-skills/_ourdigital-shared/claude-ai-export/individual/03-journal.md b/custom-skills/_ourdigital-shared/claude-ai-export/individual/03-journal.md new file mode 100644 index 0000000..ff9853f --- /dev/null +++ b/custom-skills/_ourdigital-shared/claude-ai-export/individual/03-journal.md @@ -0,0 +1,137 @@ +--- +name: ourdigital-journal +description: | + English essay creation for journal.ourdigital.org. + Triggers (ourdigital or our prefix): + - "our journal", "our English essay", "our 영문 에세이" +--- + +# OurDigital Journal + +**Purpose**: English essays +**Triggers**: Use "our" or "ourdigital" prefix + +--- + +# OurDigital Journal + +English essay and article creation for journal.ourdigital.org. + +## Activation + +Activate with "ourdigital" or "our" prefix: +- "ourdigital journal" / "our journal" +- "ourdigital English essay" / "our English essay" +- "our 영문 에세이 [topic]" +- "ourdigital 영문 에세이 [주제]" + +## Channel Profile + +| Field | Value | +|-------|-------| +| **URL** | journal.ourdigital.org | +| **Language** | English | +| **Tone** | Conversational & Poetic, Reflective | +| **Platform** | Ghost CMS | +| **Frequency** | 월 2-4회 | +| **Length** | 1,000-2,000 words | + +## Workflow + +### Phase 1: Topic Exploration + +Ask clarifying questions: + +1. **Topic**: What specific angle interests you? +2. **Audience**: Tech professionals / General readers / Academic? +3. **Depth**: Personal reflection / Industry analysis / Cultural observation? + +### Phase 2: Research (Optional) + +If topic requires current context: +- Use `web_search` for recent developments +- Reference scholarly perspectives if applicable +- Draw from historical or cultural parallels + +### Phase 3: Essay Generation + +Generate essay following the reflective style: + +**Structure:** +``` +1. Opening (Evocative scene or question) +2. Exploration (3-4 interconnected observations) +3. Synthesis (Weaving threads together) +4. Closing (Open-ended reflection) +``` + +**Writing Style:** +- Philosophical-Technical Hybridization +- Paradox as primary rhetorical device +- Rhetorical questions for engagement +- Melancholic optimism in tone + +**Distinctive Qualities:** +- Temporal awareness (historical context) +- Epistemic humility (acknowledging limits) +- Cultural bridging (Korean-global perspectives) + +### Phase 4: SEO Metadata + +Generate metadata: + +```yaml +title: [Evocative, under 70 characters] +meta_description: [Compelling summary, 155 characters] +slug: [english-url-slug] +tags: [3-5 relevant tags] +``` + +### Phase 5: Output Format + +**Markdown Output:** +```markdown +--- +title: "Essay Title" +meta_description: "Description" +slug: "url-slug" +tags: ["tag1", "tag2"] +--- + +# Essay Title + +[Essay content with paragraphs that flow naturally] + +--- +*Published in [OurDigital Journal](https://journal.ourdigital.org)* +``` + +## Writing Guidelines + +### Voice Characteristics + +| Aspect | Approach | +|--------|----------| +| Perspective | First-person reflection welcome | +| Tone | Thoughtful, observant, wondering | +| Pacing | Unhurried, allowing ideas to breathe | +| References | Cross-cultural, historical, literary | + +### Sentence Craft + +- Long, complex sentences reflecting interconnected ideas +- Progressive deepening: observation → analysis → implication +- Questions that invite rather than lecture + +### Do's and Don'ts + +**Do:** +- Blend technology with humanity +- Use paradox to illuminate tensions +- Acknowledge uncertainty gracefully +- Bridge Korean and Western perspectives + +**Don't:** +- Lecture or prescribe + +[... see full documentation for more ...] \ No newline at end of file diff --git a/custom-skills/_ourdigital-shared/claude-ai-export/individual/04-research.md b/custom-skills/_ourdigital-shared/claude-ai-export/individual/04-research.md new file mode 100644 index 0000000..5218fd6 --- /dev/null +++ b/custom-skills/_ourdigital-shared/claude-ai-export/individual/04-research.md @@ -0,0 +1,137 @@ +--- +name: ourdigital-research +description: | + Research workflow with paper and blog output. + Triggers (ourdigital or our prefix): + - "our research", "our 리서치", "our deep research" +--- + +# OurDigital Research + +**Purpose**: Research prompts +**Triggers**: Use "our" or "ourdigital" prefix + +--- + +# OurDigital Research + +Transform questions into comprehensive research papers and polished blog posts for OurDigital channels. + +## Activation + +Activate with "ourdigital" or "our" prefix: +- "ourdigital research [topic]" / "our research [topic]" +- "our 리서치", "our deep research" +- "ourdigital 리서치 해줘" +- "ourdigital deep research on [topic]" + +## Workflow Overview + +``` +Phase 1: Discovery → Phase 2: Research Planning → Phase 3: Deep Research + ↓ +Phase 4: Research Paper → Phase 5: Notion Save → Phase 6: Blog Draft + ↓ +Phase 7: Ulysses Export → Phase 8: Publishing Guidance +``` + +## Phase 1: Discovery + +**Goal**: Understand user's question and refine scope. + +1. Acknowledge the topic/question +2. Ask clarifying questions (max 3 per turn): + - Target audience? (전문가/일반인/마케터) + - Depth level? (개요/심층분석/실무가이드) + - Specific angles or concerns? +3. Confirm research scope before proceeding + +**Output**: Clear research objective statement + +## Phase 2: Research Planning + +**Goal**: Create structured research instruction. + +Generate research plan with: +- Primary research questions (3-5) +- Secondary questions for depth +- Suggested tools/sources: + - Web search for current info + - Google Drive for internal docs + - Notion for past research + - Amplitude for analytics data (if relevant) +- Expected deliverables + +**Output**: Numbered research instruction list + +## Phase 3: Deep Research + +**Goal**: Execute comprehensive multi-source research. + +Tools to leverage: +- `web_search` / `web_fetch`: Current information, statistics, trends +- `google_drive_search`: Internal documents, past reports +- `Notion:notion-search`: Previous research, related notes +- `conversation_search`: Past chat context + +Research execution pattern: +1. Start broad (overview searches) +2. Deep dive into key subtopics +3. Find supporting data/statistics +4. Identify expert opinions and case studies +5. Cross-reference and validate + +**Output**: Organized research findings with citations + +## Phase 4: Research Paper (Artifact) + +**Goal**: Synthesize findings into comprehensive document. + +Create HTML artifact with: +``` +Structure: +├── Executive Summary (핵심 요약) +├── Background & Context (배경) +├── Key Findings (주요 발견) +│ ├── Finding 1 with evidence +│ ├── Finding 2 with evidence +│ └── Finding 3 with evidence +├── Analysis & Implications (분석 및 시사점) +├── Recommendations (제언) +├── References & Sources (참고자료) +└── Appendix (부록) - if needed +``` + +Style: Professional, data-driven, bilingual key terms + +## Phase 5: Notion Save + +**Goal**: Archive research to Working with AI database. + +Auto-save to Notion with: +- **Database**: Working with AI (data_source_id: f8f19ede-32bd-43ac-9f60-0651f6f40afe) +- **Properties**: + - Name: [Research topic] + - Status: "Done" + - AI used: "Claude Desktop" + - AI summary: 2-3 sentence summary + +## Phase 6: Blog Draft + +**Goal**: Transform research into engaging blog post. + +Prompt user for channel selection: +1. blog.ourdigital.org (Korean) +2. journal.ourdigital.org (English) +3. ourstory.day (Korean, personal) + +Generate draft using appropriate style guide: +- Korean channels: See `02-ourdigital-blog` +- English channels: See `03-ourdigital-journal` + +## Phase 7: Ulysses Export + +**Goal**: Deliver MD file for Ulysses editing. + + +[... see full documentation for more ...] \ No newline at end of file diff --git a/custom-skills/_ourdigital-shared/claude-ai-export/individual/05-document.md b/custom-skills/_ourdigital-shared/claude-ai-export/individual/05-document.md new file mode 100644 index 0000000..9ef0201 --- /dev/null +++ b/custom-skills/_ourdigital-shared/claude-ai-export/individual/05-document.md @@ -0,0 +1,137 @@ +--- +name: ourdigital-document +description: | + Notion-to-presentation workflow. + Triggers (ourdigital or our prefix): + - "our document", "our 발표자료", "our presentation" +--- + +# OurDigital Document + +**Purpose**: Presentations +**Triggers**: Use "our" or "ourdigital" prefix + +--- + +# OurDigital Document + +Transform Notion research into branded presentations for OurDigital workflows. + +## Activation + +Activate with "ourdigital" or "our" prefix: +- "ourdigital document" / "our document" +- "ourdigital 발표자료" / "our 발표자료" +- "our presentation [topic]" +- "ourdigital presentation on [topic]" + +## Workflow Overview + +``` +Phase 1: Research Collection → Phase 2: Content Synthesis → Phase 3: Presentation Planning + ↓ +Phase 4: Slide Generation → Phase 5: Brand Application → Phase 6: Export +``` + +## Phase 1: Research Collection + +**Goal**: Extract research content from Notion. + +Input sources: +- **Notion Page**: `notion://page/[ID]` - Single research document +- **Notion Database**: `notion://database/[ID]` - Collection query +- **Multiple Sources**: Comma-separated URLs for synthesis + +Tools to use: +- `Notion:notion-search` - Find related content +- `Notion:notion-fetch` - Extract page content + +**Output**: Structured research.json with findings + +## Phase 2: Content Synthesis + +**Goal**: Analyze and structure extracted content. + +Processing: +1. Identify key topics and themes +2. Extract supporting data/statistics +3. Prioritize by relevance and impact +4. Generate executive summary + +**Output**: synthesis.json with: +- Executive summary +- Key topics (ranked) +- Agenda items +- Supporting data points + +## Phase 3: Presentation Planning + +**Goal**: Create slide-by-slide structure. + +Presentation types: +| Type | Slides | Focus | +|------|--------|-------| +| Executive Summary | 3-5 | High-level findings, KPIs | +| Research Report | 10-20 | Detailed methodology, data viz | +| Meeting Prep | 5-10 | Agenda-driven, decision points | + +**Output**: Slide plan with: +- Title + subtitle per slide +- Content outline +- Speaker notes +- Visual suggestions + +## Phase 4: Slide Generation + +**Goal**: Generate presentation content. + +Slide structure: +``` +├── Title Slide (project name, date, author) +├── Agenda (numbered topics) +├── Content Slides (1-3 per topic) +│ ├── Key finding header +│ ├── Supporting points (3-5 bullets) +│ └── Data visualization placeholder +├── Summary Slide (key takeaways) +└── Next Steps / Q&A +``` + +## Phase 5: Brand Application + +**Goal**: Apply OurDigital corporate styling. + +Brand elements: +- **Colors**: OurDigital palette from `01-ourdigital-brand-guide` +- **Fonts**: Poppins (headings), Lora (body) +- **Logo**: Positioned per brand guidelines +- **Spacing**: Consistent margins and padding + +Configuration: `shared/references/brand-config.json` + +## Phase 6: Export + +**Goal**: Generate final deliverable. + +Output formats: +- **PowerPoint (.pptx)**: Full presentation with animations +- **Figma Slides**: Web-based collaborative format +- **HTML Preview**: Quick review before final export + +Export paths: +- Desktop: `~/Downloads/presentations/` +- Figma: Via Figma API + +## Quick Commands + +| Command | Action | +|---------|--------| +| "ourdigital document [Notion URL]" | Full pipeline | +| "ourdigital 발표자료 만들어줘" | Korean trigger | +| "ourdigital presentation → pptx" | PowerPoint output | +| "ourdigital presentation → figma" | Figma output | + +## Presentation Templates + + +[... see full documentation for more ...] \ No newline at end of file diff --git a/custom-skills/_ourdigital-shared/claude-ai-export/individual/06-designer.md b/custom-skills/_ourdigital-shared/claude-ai-export/individual/06-designer.md new file mode 100644 index 0000000..fb88ce9 --- /dev/null +++ b/custom-skills/_ourdigital-shared/claude-ai-export/individual/06-designer.md @@ -0,0 +1,137 @@ +--- +name: ourdigital-designer +description: | + Visual storytelling and image prompt generation. + Triggers (ourdigital or our prefix): + - "our design", "our 썸네일", "our image prompt" +--- + +# OurDigital Designer + +**Purpose**: Image prompts +**Triggers**: Use "our" or "ourdigital" prefix + +--- + +# OurDigital Designer + +Transform philosophical essays into sophisticated visual narratives through minimalist, conceptually rich featured images. + +## Activation + +Activate with "ourdigital" or "our" prefix: +- "ourdigital design" / "our design" +- "ourdigital 썸네일" / "our 썸네일" +- "our image prompt for [topic]" + +## Core Philosophy + +OurDigital images are visual philosophy—not illustrations but parallel texts that invite contemplation. Each image captures the essay's philosophical core through: + +- **Abstract metaphors** over literal representations +- **Contemplative minimalism** with 20%+ negative space +- **Cultural fusion** of Korean-Western aesthetics +- **Emotional resonance** through color psychology + +## Workflow + +### Phase 1: Extract Essay Essence + +Analyze the content for: +- **Core insight**: What philosophical truth? +- **Emotional tone**: What feeling to evoke? +- **Key metaphor**: What visual symbol? + +### Phase 2: Select Visual Approach + +| Essay Type | Visual Strategy | Color Mood | +|-----------|-----------------|------------| +| Technology | Organic-digital hybrids | Cool blues → warm accents | +| Social | Network patterns, human fragments | Desaturated → hope spots | +| Philosophy | Zen space, symbolic objects | Monochrome + single accent | +| Cultural | Layered traditions, fusion forms | Earth tones → modern hues | + +### Phase 3: Generate Prompt + +Build structured prompt with: +``` +[Style] + [Subject] + [Composition] + [Color] + [Technical specs] +``` + +### Phase 4: Quality Check + +✅ **Must have:** +- Captures philosophical insight +- Works at 200px thumbnail +- Timeless (2-3 year relevance) +- Cross-cultural readability + +❌ **Must avoid:** +- Tech clichés (circuits, binary) +- Stock photo aesthetics +- Literal interpretations +- Trendy effects + +## Quick Templates + +### AI & Humanity +``` +"Translucent human silhouette dissolving into crystalline data structures. +Monochrome with teal accent. Boundary dissolution between organic/digital. +1200x630px, minimalist vector style." +``` + +### Social Commentary +``` +"Overlapping circles forming maze pattern, tiny humans in separate chambers. +Blue-gray palette, warm light leaks for hope. Subtle Korean patterns. +High negative space. 1200x630px." +``` + +### Digital Transformation +``` +"Traditional forms metamorphosing into particle streams. Paper texture → digital grain. +Earth tones shifting to cool blues. Sacred geometry underlying. +1200x630px, contemplative mood." +``` + +## Visual Metaphor Shortcuts + +| Concept | Visual Metaphor | +|---------|-----------------| +| Algorithm | Constellation patterns | +| Identity | Layered masks, fingerprints | +| Network | Root systems, neural paths | +| Time | Spirals, sediment layers | +| Knowledge | Light sources, growing trees | + +## Color Psychology + +| Mood | Palette | +|------|---------| +| Critical | Deep blue-gray + red accent | +| Hopeful | Warm amber + sky blue | +| Philosophical | Near black + off white + gold | +| Anxious | Charcoal + grey-blue + digital green | + +## Technical Specs + +- **Dimensions**: 1200x630px (OG standard) +- **Style**: Vector illustration + subtle textures +- **Colors**: 60-30-10 rule (dominant-secondary-accent) +- **Format**: WebP primary, JPG fallback + +## Quick Commands + +| Command | Action | +|---------|--------| +| "ourdigital design [topic]" | Generate image prompt | +| "ourdigital 썸네일 [주제]" | Korean trigger | +| "ourdigital visual → midjourney" | MidJourney optimized | +| "ourdigital visual → dalle" | DALL-E optimized | + +## References + +- `shared/references/visual-metaphors.md` - Concept dictionary + +[... see full documentation for more ...] \ No newline at end of file diff --git a/custom-skills/_ourdigital-shared/claude-ai-export/individual/07-ad-manager.md b/custom-skills/_ourdigital-shared/claude-ai-export/individual/07-ad-manager.md new file mode 100644 index 0000000..81461f2 --- /dev/null +++ b/custom-skills/_ourdigital-shared/claude-ai-export/individual/07-ad-manager.md @@ -0,0 +1,137 @@ +--- +name: ourdigital-ad-manager +description: | + Ad copywriting and keyword research. + Triggers (ourdigital or our prefix): + - "our ad copy", "our 광고 카피", "our keyword" +--- + +# OurDigital Ad Manager + +**Purpose**: Ad copywriting +**Triggers**: Use "our" or "ourdigital" prefix + +--- + +# OurDigital Ad Manager + +Create compelling ad copy and research keywords for OurDigital marketing campaigns. + +## Activation + +Activate with "ourdigital" or "our" prefix: +- "ourdigital ad copy" / "our ad copy" +- "ourdigital 광고 카피" / "our 광고 카피" +- "our keyword research [topic]" + +## Workflow + +### Phase 1: Campaign Brief + +Gather information: +- **Product/Service**: What are we advertising? +- **Target audience**: Who are we reaching? +- **Campaign goal**: Awareness, consideration, or conversion? +- **Platform**: Google, Naver, Meta, Display? +- **Budget tier**: Affects keyword competitiveness + +### Phase 2: Keyword Research + +For search campaigns: +1. **Seed keywords**: Core terms from brief +2. **Volume research**: Web search for search volume data +3. **Intent mapping**: Informational → Transactional +4. **Competitor analysis**: Top-ranking ad copy patterns + +Tools to use: +- `web_search`: Search volume and trends +- `web_fetch`: Competitor ad copy analysis + +### Phase 3: Ad Copy Creation + +Generate platform-specific copy following character limits and best practices. + +## Search Ad Copy + +### Google Ads Format + +``` +Headline 1: [30 chars] - Primary keyword + value prop +Headline 2: [30 chars] - Benefit or CTA +Headline 3: [30 chars] - Differentiator +Description 1: [90 chars] - Expand on value +Description 2: [90 chars] - CTA + urgency +``` + +**Best Practices:** +- Include keyword in Headline 1 +- Numbers and specifics increase CTR +- Test emotional vs. rational appeals +- Include pricing if competitive + +### Naver Search Ad Format + +``` +제목: [25자] - 핵심 키워드 + 가치 +설명: [45자] - 혜택 + 행동 유도 +``` + +**Korean Ad Copy Tips:** +- 존댓말 일관성 유지 +- 숫자와 구체적 혜택 강조 +- 신뢰 요소 포함 (경력, 인증) + +## Display Ad Copy + +### Headlines by Format + +| Format | Max Length | Focus | +|--------|------------|-------| +| Leaderboard | 25 chars | Brand + single benefit | +| Medium Rectangle | 30 chars | Offer + CTA | +| Responsive | 30 chars | Multiple variations | + +### Copy Formula + +``` +[Problem Recognition] + [Solution Hint] + [CTA] +"여전히 [문제]? [해결책]으로 [결과]" +``` + +## Branded Content + +For native advertising and sponsored content: + +### OurDigital Tone + +- **Authority without arrogance**: Share expertise, invite questions +- **Data-backed claims**: Statistics increase credibility +- **Subtle CTAs**: Education first, promotion second + +### Content Types + +| Type | Length | CTA Style | +|------|--------|-----------| +| Sponsored Article | 800-1,200 words | Soft (learn more) | +| Native Ad | 100-200 words | Medium (discover) | +| Social Sponsored | 50-100 words | Direct (get started) | + +## Keyword Research Output + +### Research Report Structure + +``` +## Keyword Analysis: [Topic] + +### Primary Keywords +| Keyword | Volume | Difficulty | Intent | +|---------|--------|------------|--------| +| [kw1] | 10K | Medium | Trans | + +### Long-tail Opportunities +- [keyword phrase 1]: Low competition, high intent +- [keyword phrase 2]: Rising trend + +### Negative Keywords + +[... see full documentation for more ...] \ No newline at end of file diff --git a/custom-skills/_ourdigital-shared/claude-ai-export/individual/08-trainer.md b/custom-skills/_ourdigital-shared/claude-ai-export/individual/08-trainer.md new file mode 100644 index 0000000..9d33dc0 --- /dev/null +++ b/custom-skills/_ourdigital-shared/claude-ai-export/individual/08-trainer.md @@ -0,0 +1,137 @@ +--- +name: ourdigital-trainer +description: | + Training materials and workshop planning. + Triggers (ourdigital or our prefix): + - "our training", "our 워크샵", "our 교육" +--- + +# OurDigital Trainer + +**Purpose**: Training materials +**Triggers**: Use "our" or "ourdigital" prefix + +--- + +# OurDigital Trainer + +Design training materials, plan workshops, and create evaluation frameworks for OurDigital education programs. + +## Activation + +Activate with "ourdigital" or "our" prefix: +- "ourdigital training" / "our training" +- "ourdigital 워크샵" / "our 워크샵" +- "our curriculum [subject]" + +## Core Domains + +OurDigital training expertise: + +| Domain | Topics | +|--------|--------| +| **Data Literacy** | 데이터 리터러시, 분석 기초, 시각화 | +| **AI Literacy** | AI 활용, 프롬프트 엔지니어링, AI 윤리 | +| **Digital Marketing** | SEO, GTM, 마케팅 자동화 | +| **Brand Marketing** | 브랜드 전략, 콘텐츠 마케팅 | + +## Workflow + +### Phase 1: Training Needs Analysis + +Gather requirements: +- **Target audience**: 직급, 경험 수준, 사전 지식 +- **Learning objectives**: 교육 후 달성할 역량 +- **Duration**: 시간 제약 (2시간/반일/전일/다회차) +- **Format**: 온라인/오프라인/하이브리드 +- **Group size**: 참여 인원 + +### Phase 2: Curriculum Design + +Structure the learning journey: + +``` +Module Structure: +├── 도입 (10-15%) +│ ├── Ice-breaker +│ ├── 학습 목표 공유 +│ └── 사전 지식 확인 +├── 핵심 학습 (60-70%) +│ ├── 개념 설명 +│ ├── 사례 분석 +│ ├── 실습 활동 +│ └── 토론/질의응답 +├── 심화/응용 (15-20%) +│ ├── 응용 과제 +│ └── 그룹 활동 +└── 마무리 (5-10%) + ├── 핵심 정리 + ├── 평가 + └── 후속 학습 안내 +``` + +### Phase 3: Material Development + +Create supporting materials: + +| Material Type | Purpose | +|---------------|---------| +| 슬라이드 | 핵심 개념 전달 | +| 핸드아웃 | 참조 자료, 체크리스트 | +| 워크시트 | 실습 활동용 | +| 사례 연구 | 토론 및 분석용 | +| 퀴즈/평가지 | 학습 확인용 | + +### Phase 4: Activity Design + +Engagement techniques: + +| Activity Type | Duration | Purpose | +|---------------|----------|---------| +| Think-Pair-Share | 5-10분 | 개별 사고 → 협력 | +| Case Study | 20-30분 | 실제 적용력 | +| Role Play | 15-20분 | 경험적 학습 | +| Gallery Walk | 15분 | 아이디어 공유 | +| Fishbowl | 20-30분 | 심층 토론 | + +### Phase 5: Evaluation Design + +Assessment framework: + +| Level | What to Measure | Method | +|-------|-----------------|--------| +| 반응 | 만족도, 참여도 | 설문조사 | +| 학습 | 지식 습득 | 퀴즈, 테스트 | +| 행동 | 현업 적용 | 관찰, 피드백 | +| 결과 | 성과 개선 | KPI 측정 | + +## Training Templates + +### 2-Hour Workshop + +``` +00:00-00:10 도입 및 Ice-breaker +00:10-00:20 학습 목표 및 아젠다 +00:20-00:50 핵심 개념 1 +00:50-01:00 휴식 +01:00-01:30 핵심 개념 2 + 실습 +01:30-01:50 그룹 활동/토론 +01:50-02:00 정리 및 Q&A +``` + +### Half-Day (4 Hours) + +``` +09:00-09:20 도입 및 네트워킹 +09:20-10:20 모듈 1: 기초 개념 +10:20-10:30 휴식 +10:30-11:30 모듈 2: 심화 학습 +11:30-12:00 실습 세션 +12:00-12:30 사례 연구 +12:30-13:00 정리, 평가, Q&A +``` + +### Full-Day (8 Hours) + + +[... see full documentation for more ...] \ No newline at end of file diff --git a/custom-skills/_ourdigital-shared/claude-ai-export/individual/09-backoffice.md b/custom-skills/_ourdigital-shared/claude-ai-export/individual/09-backoffice.md new file mode 100644 index 0000000..8dd510c --- /dev/null +++ b/custom-skills/_ourdigital-shared/claude-ai-export/individual/09-backoffice.md @@ -0,0 +1,137 @@ +--- +name: ourdigital-backoffice +description: | + Business documents for consulting services. + Triggers (ourdigital or our prefix): + - "our 견적서", "our proposal", "our quote" +--- + +# OurDigital Backoffice + +**Purpose**: Business documents +**Triggers**: Use "our" or "ourdigital" prefix + +--- + +# OurDigital Backoffice + +Create business documents for OurDigital consulting services. + +## Activation + +Activate with "ourdigital" or "our" prefix: +- "ourdigital 견적서" / "our 견적서" +- "ourdigital proposal" / "our proposal" +- "our cost analysis [project]" + +## Important Notice + +⚠️ **Legal Disclaimer**: Contract drafts require professional legal review before use. This skill provides templates and structure only. + +## Document Types + +### 1. Quote/Estimate (견적서) + +**Purpose**: Service pricing and scope summary + +**Structure:** +``` +견적서 번호: OD-YYYY-NNN +발행일: YYYY-MM-DD +유효기간: 30일 + +1. 고객 정보 + - 회사명, 담당자, 연락처 + +2. 서비스 개요 + - 프로젝트명 + - 서비스 범위 요약 + +3. 세부 항목 + | 항목 | 상세 | 수량 | 단가 | 금액 | + |------|------|------|------|------| + +4. 합계 + - 소계, VAT, 총액 + +5. 결제 조건 + - 선금/잔금 비율 + - 결제 방법 + +6. 특이사항 + - 포함/미포함 사항 +``` + +### 2. Service Proposal (서비스 제안서) + +**Purpose**: Detailed service offering and value proposition + +**Structure:** +``` +1. Executive Summary + - 핵심 제안 1-2문단 + +2. 고객 상황 이해 + - 현재 과제 + - 니즈 분석 + +3. 제안 서비스 + - 서비스 범위 + - 접근 방법 + - 예상 산출물 + +4. 프로젝트 계획 + - 일정표 + - 마일스톤 + - 체크포인트 + +5. 투입 리소스 + - 담당자 프로필 + - 역할 분담 + +6. 비용 및 조건 + - 비용 구조 + - 결제 조건 + +7. 기대 효과 + - 예상 성과 + - ROI 추정 + +8. 왜 OurDigital인가 + - 차별점 + - 관련 경험 +``` + +### 3. Contract Draft (계약서 초안) + +**Purpose**: Service agreement framework + +⚠️ **반드시 법률 전문가 검토 필요** + +**Structure:** +``` +제1조 (목적) +제2조 (용어의 정의) +제3조 (계약 기간) +제4조 (서비스 범위) +제5조 (대금 및 지급 조건) +제6조 (권리와 의무) +제7조 (비밀유지) +제8조 (지적재산권) +제9조 (계약의 해지) +제10조 (손해배상) +제11조 (분쟁 해결) +제12조 (일반 조항) +``` + +### 4. Cost-Benefit Analysis (비용 분석) + +**Purpose**: ROI and investment justification + +**Structure:** +``` +1. 프로젝트 개요 + - 목적 및 범위 + + +[... see full documentation for more ...] \ No newline at end of file diff --git a/custom-skills/_ourdigital-shared/claude-ai-export/individual/10-skill-creator.md b/custom-skills/_ourdigital-shared/claude-ai-export/individual/10-skill-creator.md new file mode 100644 index 0000000..fe6932a --- /dev/null +++ b/custom-skills/_ourdigital-shared/claude-ai-export/individual/10-skill-creator.md @@ -0,0 +1,137 @@ +--- +name: ourdigital-skill-creator +description: | + Meta skill for creating and managing new skills. + Triggers (ourdigital or our prefix): + - "our skill create", "our 스킬 만들기" +--- + +# OurDigital Skill Creator + +**Purpose**: Creating new skills +**Triggers**: Use "our" or "ourdigital" prefix + +--- + +# OurDigital Skill Creator + +Meta skill for creating, validating, and managing OurDigital Claude Skills. + +## Activation + +Activate with "ourdigital" or "our" prefix: +- "ourdigital 스킬 만들어줘" / "our 스킬 만들어줘" +- "ourdigital skill creator" / "our skill creator" +- "our skill create [name]" + +Do NOT activate for generic "make a skill" requests (without our/ourdigital prefix). + +## Interactive Workflow + +### Phase 1: Need Assessment + +When user requests a new skill: + +1. **Acknowledge** the initial request +2. **Ask clarifying questions** (max 3 per turn): + - What is the core purpose? + - What triggers this skill? + - What outputs do you expect? + +### Phase 2: Suitability Check + +Evaluate against Claude Skill criteria: + +| Criterion | Question to Ask | +|-----------|-----------------| +| Clear trigger | When exactly should this skill activate? | +| Focused scope | Can you describe 1-3 core functions? | +| Reusable resources | What scripts, templates, or references are needed? | +| Domain knowledge | What specialized knowledge does Claude lack? | +| Clear boundaries | How does this differ from existing skills? | + +**Decision**: If ≥3 criteria pass → proceed. Otherwise, suggest alternatives. + +### Phase 3: Requirements Definition + +Guide user through structured Q&A: + +``` +Q1. 스킬 목적과 핵심 기능은 무엇인가요? + (What is the skill's purpose and core functions?) + +Q2. 어떤 상황에서 이 스킬이 트리거되어야 하나요? + (When should this skill be triggered?) + +Q3. 필요한 외부 도구나 API가 있나요? + (Any external tools or APIs needed?) + +Q4. 기대하는 출력 형식은 무엇인가요? + (What output format do you expect?) + +Q5. Desktop, Code, 또는 Both 환경이 필요한가요? + (Which environment: Desktop, Code, or Both?) +``` + +### Phase 4: Skill Generation + +Generate skill structure following OurDigital standards: + +``` +XX-ourdigital-{skill-name}/ +├── desktop/ +│ └── SKILL.md # Desktop version +├── code/ +│ └── SKILL.md # Code version (CLAUDE.md pattern) +├── shared/ +│ ├── references/ # Common documentation +│ ├── templates/ # Shared templates +│ └── scripts/ # Utility scripts +├── docs/ +│ ├── CHANGELOG.md # Version history +│ └── logs/ # Update logs +└── README.md # Overview +``` + +### Phase 5: Validation + +Before finalizing, verify: + +- [ ] YAML frontmatter includes "ourdigital" trigger keywords +- [ ] Description clearly states activation conditions +- [ ] Body content is 800-1,200 words +- [ ] shared/ resources are properly referenced +- [ ] No overlap with existing ourdigital skills + +### Phase 6: Notion Sync + +Record to Working with AI database: + +- **Database**: f8f19ede-32bd-43ac-9f60-0651f6f40afe +- **Properties**: + - Name: `ourdigital-{skill-name} v{version}` + - Status: In progress → Done + - AI used: Claude Desktop + - AI summary: Brief skill description + +## YAML Frontmatter Template + +```yaml +--- +name: ourdigital-{skill-name} +description: | + [Purpose summary] + Activated when user includes "ourdigital" keyword. + + Triggers: + - "ourdigital {keyword1}", "ourdigital {keyword2}" + + Features: + - Feature 1 + - Feature 2 +version: "1.0" +author: OurDigital +environment: Desktop | Code | Both +--- + +[... see full documentation for more ...] \ No newline at end of file diff --git a/custom-skills/_ourdigital-shared/claude-ai-export/ourdigital-skills-bundle.md b/custom-skills/_ourdigital-shared/claude-ai-export/ourdigital-skills-bundle.md new file mode 100644 index 0000000..e58a8f3 --- /dev/null +++ b/custom-skills/_ourdigital-shared/claude-ai-export/ourdigital-skills-bundle.md @@ -0,0 +1,336 @@ +--- +name: ourdigital-skills-bundle +description: | + Complete OurDigital Skills package with 10 skills for brand, content, production, and business workflows. + Triggers (ourdigital or our prefix): + - "our brand", "our blog", "our journal", "our research" + - "our document", "our design", "our ad copy", "our training" + - "our 견적서", "our skill" +--- + +# OurDigital Skills Bundle for Claude.ai + +This file contains all 10 OurDigital skills for use in Claude.ai Projects. + +**Activation**: Use "ourdigital" or "our" prefix to trigger skills. + +--- + +## 1. OurDigital Brand Guide + +**Triggers**: `our brand guide`, `our 브랜드 가이드`, `our 톤앤매너` + +### Brand Identity +- **Name**: OurDigital Clinic +- **Tagline**: 우리 디지털 클리닉 | Your Digital Health Partner +- **Mission**: 디지털 마케팅 클리닉 for SMBs + +### Core Values +| 가치 | English | 메타포 | +|------|---------|--------| +| 데이터 중심 | Data-driven | 정밀 검사 | +| 실행 지향 | In-Action | 실행 가능한 처방 | +| 지속 성장 | Sustainable Growth | 정기 검진 | + +### Writing Style +- **Korean**: 분석적 + 개인적, 철학-기술 융합 +- **English**: Reflective, poetic, paradox as device +- **Fonts**: Poppins (headings), Lora (body) +- **Colors**: Primary #1a1a2e, Accent #4ecdc4 + +--- + +## 2. OurDigital Blog + +**Triggers**: `our blog`, `our 블로그`, `our 한국어 포스트` + +### Channel +- **URL**: blog.ourdigital.org +- **Language**: Korean (전문용어 영문 병기) +- **Tone**: Analytical & Personal, Educational +- **Length**: 1,500-3,000자 + +### Structure +``` +제목 (SEO 키워드 포함) +├── 도입부 (hook + 핵심 질문) +├── 본문 (3-5 섹션) +│ ├── 소제목 + 본문 +│ └── 데이터/인용 포함 +├── 결론 (인사이트 + 열린 질문) +└── CTA (optional) +``` + +### Style Tips +- 역설(Paradox) 활용: "~하면서 동시에 ~하다" +- 수사적 질문으로 참여 유도 +- 우울한 낙관주의: 불안 인정 + 희망 제시 + +--- + +## 3. OurDigital Journal + +**Triggers**: `our journal`, `our English essay`, `our 영문 에세이` + +### Channel +- **URL**: journal.ourdigital.org +- **Language**: English +- **Tone**: Conversational, Poetic, Reflective +- **Length**: 1,000-2,000 words + +### Writing Characteristics +- **Philosophical-Technical Hybridization**: Tech + human implications +- **Paradox as Device**: Illuminate through tensions +- **Melancholic Optimism**: Clear-eyed hope + +### Structure +``` +Opening (hook with scene/question) +├── Body (weaving narrative + analysis) +│ ├── Personal observation +│ ├── Cultural/technical context +│ └── Philosophical reflection +└── Closing (open question, not conclusion) +``` + +--- + +## 4. OurDigital Research + +**Triggers**: `our research`, `our 리서치`, `our deep research` + +### Workflow +1. **Discovery**: Clarify topic, audience, depth +2. **Planning**: Generate research questions (3-5 primary) +3. **Research**: Multi-source investigation +4. **Synthesis**: Research paper with findings +5. **Archive**: Save to Notion "Working with AI" +6. **Output**: Optional blog draft + +### Research Plan Template +``` +Primary Questions: +1. [Core question about topic] +2. [Supporting question] +3. [Trend/future question] + +Source Strategy: +- Web search: [keywords] +- Notion: [past research] +- Industry reports: [sources] + +Deliverables: +- Research paper +- Notion archive +- Blog draft (optional) +``` + +--- + +## 5. OurDigital Document + +**Triggers**: `our document`, `our 발표자료`, `our presentation` + +### Workflow +1. Extract content from Notion +2. Synthesize key topics +3. Plan slide structure +4. Generate presentation +5. Apply OurDigital branding + +### Presentation Types +| Type | Slides | Focus | +|------|--------|-------| +| Executive | 3-5 | High-level findings | +| Research | 10-20 | Detailed analysis | +| Meeting | 5-10 | Agenda-driven | + +### Slide Structure +``` +Title Slide → Agenda → Content (1-3 per topic) → Summary → Next Steps +``` + +--- + +## 6. OurDigital Designer + +**Triggers**: `our design`, `our 썸네일`, `our image prompt` + +### Philosophy +OurDigital images are visual philosophy—abstract metaphors over literal representations. + +### Visual Approach +| Topic | Strategy | Colors | +|-------|----------|--------| +| Technology | Organic-digital hybrids | Cool blues | +| Social | Network patterns | Desaturated | +| Philosophy | Zen space | Monochrome + accent | + +### Prompt Template +``` +Create [style] featured image, 1200x630px. +Visual concept: [metaphor description]. +Atmosphere: [mood]. +Colors: [palette with accent]. +Composition: Abstract, 20%+ negative space. +Avoid: Stock aesthetics, literal interpretation. +``` + +### Metaphor Shortcuts +- Algorithm → Constellation patterns +- Identity → Layered masks +- Network → Root systems +- Time → Spirals, sediment layers + +--- + +## 7. OurDigital Ad Manager + +**Triggers**: `our ad copy`, `our 광고 카피`, `our keyword` + +### Google Ads Format +``` +Headline 1: [30 chars] - Keyword + value +Headline 2: [30 chars] - Benefit +Headline 3: [30 chars] - Differentiator +Description 1: [90 chars] - Expand value +Description 2: [90 chars] - CTA + urgency +``` + +### Naver Format +``` +제목: [25자] - 키워드 + 가치 +설명: [45자] - 혜택 + 행동 유도 +``` + +### Copy Formulas +- **PAS**: Problem → Agitate → Solution +- **FBP**: Feature → Benefit → Proof +- **QAA**: Question → Answer → Action + +--- + +## 8. OurDigital Trainer + +**Triggers**: `our training`, `our 워크샵`, `our 교육` + +### Domains +- Data Literacy, AI Literacy +- Digital Marketing (SEO, GTM) +- Brand Marketing + +### Workshop Templates + +**2-Hour** +``` +00:00-00:10 Ice-breaker +00:10-00:50 Module 1 +00:50-01:00 Break +01:00-01:30 Module 2 + Practice +01:30-01:50 Activity +01:50-02:00 Wrap-up +``` + +**Half-Day (4 Hours)** +``` +09:00-09:20 Opening +09:20-10:20 Module 1 +10:20-10:30 Break +10:30-11:30 Module 2 +11:30-12:00 Practice +12:00-12:30 Module 3 +12:30-13:00 Closing +``` + +### Evaluation +- Level 1: Reaction (만족도) +- Level 2: Learning (지식 습득) +- Level 3: Behavior (현업 적용) +- Level 4: Results (성과 개선) + +--- + +## 9. OurDigital Backoffice + +**Triggers**: `our 견적서`, `our proposal`, `our quote` + +### Document Types +1. **Quote (견적서)**: Pricing summary +2. **Proposal (제안서)**: Detailed offering +3. **Contract (계약서)**: Agreement framework ⚠️ Legal review required +4. **Cost Analysis**: ROI justification + +### Quote Structure +``` +문서번호: OD-QUOTE-YYYY-NNN +발행일: YYYY-MM-DD + +서비스 항목 (표) +합계 (소계 + VAT) +결제 조건 (50/50) +프로젝트 일정 +포함/미포함 사항 +``` + +### Service Pricing Reference +| Service | Price Range | +|---------|-------------| +| SEO Audit | 300-500만원 | +| GTM Setup | 200-400만원 | +| Monthly SEO | 150-300만원/월 | +| Workshop | 100-200만원 | + +--- + +## 10. OurDigital Skill Creator + +**Triggers**: `our skill create`, `our 스킬 만들기` + +### Suitability Criteria +- Clear trigger conditions +- Focused scope (1-3 functions) +- Reusable resources +- Domain-specific knowledge +- Clear boundaries + +### Skill Structure +``` +XX-ourdigital-skillname/ +├── code/SKILL.md +├── desktop/SKILL.md +├── shared/references/ +├── docs/CHANGELOG.md +└── README.md +``` + +### YAML Frontmatter Template +```yaml +--- +name: ourdigital-skillname +description: | + [Purpose] + Triggers (ourdigital or our prefix): + - "our [keyword]", "ourdigital [keyword]" +version: "1.0" +author: OurDigital +--- +``` + +--- + +## Quick Reference + +| # | Skill | Trigger | Purpose | +|---|-------|---------|---------| +| 01 | brand-guide | `our brand` | Brand standards | +| 02 | blog | `our blog` | Korean posts | +| 03 | journal | `our journal` | English essays | +| 04 | research | `our research` | Research prompts | +| 05 | document | `our document` | Presentations | +| 06 | designer | `our design` | Image prompts | +| 07 | ad-manager | `our ad copy` | Ad copywriting | +| 08 | trainer | `our training` | Workshops | +| 09 | backoffice | `our 견적서` | Business docs | +| 10 | skill-creator | `our skill` | Create skills | + +**Prefix**: Always use "our" or "ourdigital" to activate these skills. diff --git a/custom-skills/_ourdigital-shared/install.sh b/custom-skills/_ourdigital-shared/install.sh new file mode 100755 index 0000000..46f4e24 --- /dev/null +++ b/custom-skills/_ourdigital-shared/install.sh @@ -0,0 +1,415 @@ +#!/bin/bash +# +# OurDigital Skills Installer +# Portable installation tool for OurDigital Claude Skills package +# +# Usage: +# ./install.sh # Interactive install +# ./install.sh --update # Update existing installation +# ./install.sh --uninstall # Remove installation +# ./install.sh --help # Show help +# + +set -e + +# Colors for output +RED='\033[0;31m' +GREEN='\033[0;32m' +YELLOW='\033[1;33m' +BLUE='\033[0;34m' +CYAN='\033[0;36m' +NC='\033[0m' # No Color + +# Configuration +SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" +SKILLS_DIR="$(dirname "$SCRIPT_DIR")" +ENV_FILE="$HOME/.env.ourdigital" +CONFIG_DIR="$HOME/.ourdigital" +VENV_DIR="$SKILLS_DIR/.venv-ourdigital" + +# Print banner +print_banner() { + echo -e "${CYAN}" + echo "╔═══════════════════════════════════════════════════════════╗" + echo "║ ║" + echo "║ OurDigital Skills Installer ║" + echo "║ 사람, 디지털, 그리고 문화 ║" + echo "║ ║" + echo "╚═══════════════════════════════════════════════════════════╝" + echo -e "${NC}" +} + +# Print colored messages +info() { echo -e "${BLUE}[INFO]${NC} $1"; } +success() { echo -e "${GREEN}[OK]${NC} $1"; } +warn() { echo -e "${YELLOW}[WARN]${NC} $1"; } +error() { echo -e "${RED}[ERROR]${NC} $1"; } + +# Check prerequisites +check_prerequisites() { + info "Checking prerequisites..." + + local missing=() + + # Check Python 3.11+ + if command -v python3 &> /dev/null; then + PYTHON_VERSION=$(python3 -c 'import sys; print(f"{sys.version_info.major}.{sys.version_info.minor}")') + if [[ $(echo "$PYTHON_VERSION >= 3.11" | bc -l) -eq 1 ]]; then + success "Python $PYTHON_VERSION" + else + warn "Python $PYTHON_VERSION (3.11+ recommended)" + fi + else + missing+=("python3") + fi + + # Check git + if command -v git &> /dev/null; then + success "Git $(git --version | cut -d' ' -f3)" + else + missing+=("git") + fi + + # Check 1Password CLI (optional) + if command -v op &> /dev/null; then + success "1Password CLI available" + HAS_1PASSWORD=true + else + warn "1Password CLI not found (credentials will need manual entry)" + HAS_1PASSWORD=false + fi + + if [[ ${#missing[@]} -gt 0 ]]; then + error "Missing required tools: ${missing[*]}" + exit 1 + fi + + echo "" +} + +# Create directory structure +setup_directories() { + info "Setting up directories..." + + # Create config directory + mkdir -p "$CONFIG_DIR/credentials" + chmod 700 "$CONFIG_DIR" + chmod 700 "$CONFIG_DIR/credentials" + success "Created $CONFIG_DIR/" + + # Create logs directory + mkdir -p "$CONFIG_DIR/logs" + success "Created $CONFIG_DIR/logs/" + + echo "" +} + +# Setup environment file +setup_environment() { + info "Setting up environment file..." + + if [[ -f "$ENV_FILE" ]]; then + warn "$ENV_FILE already exists" + read -p "Overwrite? (y/N): " -n 1 -r + echo + if [[ ! $REPLY =~ ^[Yy]$ ]]; then + info "Keeping existing environment file" + return + fi + cp "$ENV_FILE" "$ENV_FILE.backup.$(date +%Y%m%d%H%M%S)" + success "Backed up existing file" + fi + + cp "$SCRIPT_DIR/.env.ourdigital.template" "$ENV_FILE" + chmod 600 "$ENV_FILE" + success "Created $ENV_FILE" + + echo "" +} + +# Setup credentials from 1Password or manual +setup_credentials() { + info "Setting up credentials..." + + if [[ "$HAS_1PASSWORD" == true ]]; then + read -p "Fetch credentials from 1Password? (Y/n): " -n 1 -r + echo + if [[ ! $REPLY =~ ^[Nn]$ ]]; then + fetch_from_1password + return + fi + fi + + echo -e "${YELLOW}Manual credential setup required.${NC}" + echo "Edit $ENV_FILE with your API keys:" + echo " - NOTION_API_TOKEN" + echo " - GHOST_BLOG_ADMIN_KEY" + echo " - GHOST_JOURNAL_ADMIN_KEY" + echo " - FIGMA_ACCESS_TOKEN" + echo "" +} + +# Fetch credentials from 1Password +fetch_from_1password() { + info "Fetching credentials from 1Password..." + + # Check if signed in + if ! op account list &> /dev/null; then + warn "Please sign in to 1Password CLI first" + echo "Run: eval \$(op signin)" + return + fi + + # Fetch each credential + local credentials=( + "NOTION_API_TOKEN:OurDigital Notion:api_token" + "GHOST_BLOG_ADMIN_KEY:OurDigital Ghost Blog:api_key" + "GHOST_JOURNAL_ADMIN_KEY:OurDigital Ghost Journal:api_key" + "FIGMA_ACCESS_TOKEN:OurDigital Figma:api_token" + ) + + for cred in "${credentials[@]}"; do + IFS=':' read -r env_var item_name field <<< "$cred" + + if value=$(op item get "$item_name" --fields "$field" 2>/dev/null); then + sed -i '' "s|^$env_var=.*|$env_var=$value|" "$ENV_FILE" 2>/dev/null || \ + sed -i "s|^$env_var=.*|$env_var=$value|" "$ENV_FILE" + success "Fetched $env_var" + else + warn "Could not fetch $env_var from 1Password" + fi + done + + echo "" +} + +# Setup Python virtual environment +setup_python_env() { + info "Setting up Python virtual environment..." + + if [[ -d "$VENV_DIR" ]]; then + warn "Virtual environment already exists" + read -p "Recreate? (y/N): " -n 1 -r + echo + if [[ $REPLY =~ ^[Yy]$ ]]; then + rm -rf "$VENV_DIR" + else + info "Using existing virtual environment" + return + fi + fi + + python3 -m venv "$VENV_DIR" + success "Created virtual environment" + + # Activate and install dependencies + source "$VENV_DIR/bin/activate" + pip install --upgrade pip -q + pip install -r "$SCRIPT_DIR/requirements/base.txt" -q + success "Installed base dependencies" + + # Install code-specific if requested + read -p "Install Claude Code dependencies? (Y/n): " -n 1 -r + echo + if [[ ! $REPLY =~ ^[Nn]$ ]]; then + pip install -r "$SCRIPT_DIR/requirements/code.txt" -q + success "Installed Code dependencies" + fi + + deactivate + echo "" +} + +# Copy config file +setup_config() { + info "Setting up configuration..." + + if [[ ! -f "$CONFIG_DIR/config.yaml" ]]; then + cp "$SCRIPT_DIR/config/ourdigital.yaml" "$CONFIG_DIR/config.yaml" + success "Created $CONFIG_DIR/config.yaml" + else + info "Config file already exists, skipping" + fi + + echo "" +} + +# Validate installation +validate_installation() { + info "Validating installation..." + + local checks_passed=0 + local checks_total=6 + + # Check directories + [[ -d "$CONFIG_DIR" ]] && ((checks_passed++)) && success "Config directory exists" || warn "Config directory missing" + [[ -d "$CONFIG_DIR/credentials" ]] && ((checks_passed++)) && success "Credentials directory exists" || warn "Credentials directory missing" + + # Check files + [[ -f "$ENV_FILE" ]] && ((checks_passed++)) && success "Environment file exists" || warn "Environment file missing" + [[ -f "$CONFIG_DIR/config.yaml" ]] && ((checks_passed++)) && success "Config file exists" || warn "Config file missing" + + # Check virtual environment + [[ -d "$VENV_DIR" ]] && ((checks_passed++)) && success "Virtual environment exists" || warn "Virtual environment missing" + + # Check skills directory + [[ -d "$SKILLS_DIR/01-ourdigital-brand-guide" ]] && ((checks_passed++)) && success "Skills directory valid" || warn "Skills not found" + + echo "" + echo -e "${CYAN}Validation: $checks_passed/$checks_total checks passed${NC}" + echo "" +} + +# Show installed skills +show_skills() { + info "Installed OurDigital Skills:" + echo "" + + for dir in "$SKILLS_DIR"/0{1,2,3,4,5,6,7,8,9}-ourdigital-* "$SKILLS_DIR"/10-ourdigital-*; do + if [[ -d "$dir" ]]; then + name=$(basename "$dir") + desc=$(grep -m1 "^name:" "$dir/desktop/SKILL.md" 2>/dev/null | cut -d':' -f2 | xargs || echo "") + echo -e " ${GREEN}✓${NC} $name" + fi + done + + echo "" +} + +# Print usage instructions +print_usage() { + echo -e "${CYAN}Usage Instructions:${NC}" + echo "" + echo "1. Activate the virtual environment:" + echo " source $VENV_DIR/bin/activate" + echo "" + echo "2. Edit credentials if needed:" + echo " nano $ENV_FILE" + echo "" + echo "3. Use skills with 'our' or 'ourdigital' prefix:" + echo " - our blog [topic]" + echo " - our research [topic]" + echo " - our 견적서" + echo "" + echo "4. Documentation:" + echo " $SKILLS_DIR/OUR_SKILL_PROJECT_PLAN_v1.1.md" + echo "" +} + +# Uninstall +uninstall() { + warn "This will remove OurDigital configuration (not skills)." + read -p "Continue? (y/N): " -n 1 -r + echo + + if [[ ! $REPLY =~ ^[Yy]$ ]]; then + info "Cancelled" + exit 0 + fi + + # Backup before removing + if [[ -f "$ENV_FILE" ]]; then + cp "$ENV_FILE" "$ENV_FILE.uninstall.backup" + rm "$ENV_FILE" + success "Removed $ENV_FILE (backup saved)" + fi + + if [[ -d "$VENV_DIR" ]]; then + rm -rf "$VENV_DIR" + success "Removed virtual environment" + fi + + info "Config directory preserved at $CONFIG_DIR" + info "To fully remove: rm -rf $CONFIG_DIR" + + success "Uninstall complete" +} + +# Show help +show_help() { + echo "OurDigital Skills Installer" + echo "" + echo "Usage: ./install.sh [OPTIONS]" + echo "" + echo "Options:" + echo " --help, -h Show this help message" + echo " --update, -u Update existing installation" + echo " --uninstall Remove installation (preserves skills)" + echo " --validate Only run validation checks" + echo " --skip-creds Skip credentials setup" + echo " --skip-venv Skip virtual environment setup" + echo "" + echo "Examples:" + echo " ./install.sh # Full interactive install" + echo " ./install.sh --update # Update existing setup" + echo " ./install.sh --skip-creds # Install without credentials" + echo "" +} + +# Main installation flow +main_install() { + print_banner + check_prerequisites + setup_directories + setup_environment + + if [[ "$SKIP_CREDS" != true ]]; then + setup_credentials + fi + + if [[ "$SKIP_VENV" != true ]]; then + setup_python_env + fi + + setup_config + validate_installation + show_skills + print_usage + + echo -e "${GREEN}╔═══════════════════════════════════════════════════════════╗${NC}" + echo -e "${GREEN}║ Installation Complete! ║${NC}" + echo -e "${GREEN}╚═══════════════════════════════════════════════════════════╝${NC}" +} + +# Parse arguments +SKIP_CREDS=false +SKIP_VENV=false + +while [[ $# -gt 0 ]]; do + case $1 in + --help|-h) + show_help + exit 0 + ;; + --uninstall) + uninstall + exit 0 + ;; + --validate) + validate_installation + exit 0 + ;; + --update|-u) + info "Updating installation..." + setup_python_env + validate_installation + exit 0 + ;; + --skip-creds) + SKIP_CREDS=true + shift + ;; + --skip-venv) + SKIP_VENV=true + shift + ;; + *) + error "Unknown option: $1" + show_help + exit 1 + ;; + esac +done + +# Run main install +main_install diff --git a/custom-skills/_ourdigital-shared/scripts/export_for_claude_ai.py b/custom-skills/_ourdigital-shared/scripts/export_for_claude_ai.py new file mode 100755 index 0000000..11afde3 --- /dev/null +++ b/custom-skills/_ourdigital-shared/scripts/export_for_claude_ai.py @@ -0,0 +1,158 @@ +#!/usr/bin/env python3 +""" +Export OurDigital Skills for Claude.ai Projects + +Generates simplified skill files suitable for uploading to Claude.ai. + +Usage: + python export_for_claude_ai.py # Export all skills + python export_for_claude_ai.py --bundle # Generate bundle only + python export_for_claude_ai.py --individual # Generate individual files only +""" + +import os +import re +import argparse +from pathlib import Path +from typing import Optional + +SCRIPT_DIR = Path(__file__).parent.parent +SKILLS_DIR = SCRIPT_DIR.parent +EXPORT_DIR = SCRIPT_DIR / "claude-ai-export" +INDIVIDUAL_DIR = EXPORT_DIR / "individual" + +# (dir, name, desc, triggers) +SKILLS = [ + ("01-ourdigital-brand-guide", "Brand Guide", "brand standards and style", + '"our brand guide", "our 브랜드 가이드", "our 톤앤매너"'), + ("02-ourdigital-blog", "Blog", "Korean blog drafts", + '"our blog", "our 블로그", "our 한국어 포스트"'), + ("03-ourdigital-journal", "Journal", "English essays", + '"our journal", "our English essay", "our 영문 에세이"'), + ("04-ourdigital-research", "Research", "research prompts", + '"our research", "our 리서치", "our deep research"'), + ("05-ourdigital-document", "Document", "presentations", + '"our document", "our 발표자료", "our presentation"'), + ("06-ourdigital-designer", "Designer", "image prompts", + '"our design", "our 썸네일", "our image prompt"'), + ("07-ourdigital-ad-manager", "Ad Manager", "ad copywriting", + '"our ad copy", "our 광고 카피", "our keyword"'), + ("08-ourdigital-trainer", "Trainer", "training materials", + '"our training", "our 워크샵", "our 교육"'), + ("09-ourdigital-backoffice", "Backoffice", "business documents", + '"our 견적서", "our proposal", "our quote"'), + ("10-ourdigital-skill-creator", "Skill Creator", "creating new skills", + '"our skill create", "our 스킬 만들기"'), +] + + +def extract_skill_content(skill_dir: str) -> Optional[str]: + """Extract and simplify content from a skill's SKILL.md.""" + desktop_path = SKILLS_DIR / skill_dir / "desktop" / "SKILL.md" + + if not desktop_path.exists(): + print(f" Warning: {desktop_path} not found") + return None + + content = desktop_path.read_text() + + # Remove YAML frontmatter + if content.startswith("---"): + parts = content.split("---", 2) + if len(parts) >= 3: + content = parts[2].strip() + + # Extract key sections (first 150 lines or so) + lines = content.split("\n") + + # Find main heading and take content + simplified = [] + in_content = False + line_count = 0 + max_lines = 120 + + for line in lines: + if line.startswith("# "): + in_content = True + + if in_content: + simplified.append(line) + line_count += 1 + + if line_count >= max_lines: + simplified.append("\n[... see full documentation for more ...]") + break + + return "\n".join(simplified) + + +def generate_individual_files(): + """Generate individual skill files for Claude.ai.""" + INDIVIDUAL_DIR.mkdir(parents=True, exist_ok=True) + + print("Generating individual skill files...") + + for skill_dir, name, desc, triggers in SKILLS: + content = extract_skill_content(skill_dir) + if content: + # Create simplified header with YAML frontmatter + num = skill_dir.split("-")[0] + skill_name = name.lower().replace(' ', '-') + filename = f"{num}-{skill_name}.md" + + header = f"""--- +name: ourdigital-{skill_name} +description: | + {desc.capitalize()}. + Triggers (ourdigital or our prefix): + - {triggers} +--- + +# OurDigital {name} + +**Purpose**: {desc.capitalize()} +**Triggers**: Use "our" or "ourdigital" prefix + +--- + +""" + output_path = INDIVIDUAL_DIR / filename + output_path.write_text(header + content) + print(f" Created: {filename}") + + +def generate_bundle(): + """Generate combined bundle file.""" + print("Generating bundle file...") + + # Read existing bundle (already created manually with full content) + bundle_path = EXPORT_DIR / "ourdigital-skills-bundle.md" + if bundle_path.exists(): + print(f" Bundle exists: {bundle_path}") + else: + print(f" Warning: Bundle not found at {bundle_path}") + + +def main(): + parser = argparse.ArgumentParser(description="Export skills for Claude.ai") + parser.add_argument("--bundle", action="store_true", help="Generate bundle only") + parser.add_argument("--individual", action="store_true", help="Generate individual files only") + args = parser.parse_args() + + print(f"Export directory: {EXPORT_DIR}\n") + + if args.bundle: + generate_bundle() + elif args.individual: + generate_individual_files() + else: + generate_bundle() + generate_individual_files() + + print("\nDone! Files ready for upload to Claude.ai Projects.") + print(f" Bundle: {EXPORT_DIR / 'ourdigital-skills-bundle.md'}") + print(f" Individual: {INDIVIDUAL_DIR}/") + + +if __name__ == "__main__": + main() diff --git a/custom-skills/_ourdigital-shared/scripts/validate_install.py b/custom-skills/_ourdigital-shared/scripts/validate_install.py new file mode 100755 index 0000000..1856be6 --- /dev/null +++ b/custom-skills/_ourdigital-shared/scripts/validate_install.py @@ -0,0 +1,284 @@ +#!/usr/bin/env python3 +""" +OurDigital Skills Installation Validator + +Checks that all components are properly installed and configured. + +Usage: + python validate_install.py + python validate_install.py --verbose + python validate_install.py --fix # Attempt to fix issues +""" + +import os +import sys +import json +import argparse +from pathlib import Path +from typing import List, Tuple, Dict + +# Colors for terminal output +class Colors: + GREEN = '\033[92m' + YELLOW = '\033[93m' + RED = '\033[91m' + CYAN = '\033[96m' + BOLD = '\033[1m' + END = '\033[0m' + +def ok(msg: str) -> None: + print(f"{Colors.GREEN}[✓]{Colors.END} {msg}") + +def warn(msg: str) -> None: + print(f"{Colors.YELLOW}[!]{Colors.END} {msg}") + +def fail(msg: str) -> None: + print(f"{Colors.RED}[✗]{Colors.END} {msg}") + +def info(msg: str) -> None: + print(f"{Colors.CYAN}[i]{Colors.END} {msg}") + + +class InstallationValidator: + def __init__(self, verbose: bool = False): + self.verbose = verbose + self.home = Path.home() + self.script_dir = Path(__file__).parent.parent + self.skills_dir = self.script_dir.parent + + self.env_file = self.home / ".env.ourdigital" + self.config_dir = self.home / ".ourdigital" + self.venv_dir = self.skills_dir / ".venv-ourdigital" + + self.results: List[Tuple[str, bool, str]] = [] + + def check(self, name: str, condition: bool, fix_hint: str = "") -> bool: + """Record a check result.""" + self.results.append((name, condition, fix_hint)) + return condition + + def validate_directories(self) -> int: + """Check required directories exist.""" + info("Checking directories...") + passed = 0 + + checks = [ + ("Config directory", self.config_dir.exists(), + f"mkdir -p {self.config_dir}"), + ("Credentials directory", (self.config_dir / "credentials").exists(), + f"mkdir -p {self.config_dir}/credentials"), + ("Logs directory", (self.config_dir / "logs").exists(), + f"mkdir -p {self.config_dir}/logs"), + ] + + for name, condition, fix in checks: + if self.check(name, condition, fix): + ok(name) + passed += 1 + else: + fail(name) + if self.verbose: + print(f" Fix: {fix}") + + return passed + + def validate_files(self) -> int: + """Check required files exist.""" + info("Checking files...") + passed = 0 + + checks = [ + ("Environment file (.env.ourdigital)", self.env_file.exists(), + "cp _ourdigital-shared/.env.ourdigital.template ~/.env.ourdigital"), + ("Config file (config.yaml)", (self.config_dir / "config.yaml").exists(), + "cp _ourdigital-shared/config/ourdigital.yaml ~/.ourdigital/config.yaml"), + ] + + for name, condition, fix in checks: + if self.check(name, condition, fix): + ok(name) + passed += 1 + else: + fail(name) + if self.verbose: + print(f" Fix: {fix}") + + return passed + + def validate_env_variables(self) -> int: + """Check environment variables are set.""" + info("Checking environment variables...") + passed = 0 + + required_vars = [ + "NOTION_API_TOKEN", + "GHOST_BLOG_ADMIN_KEY", + "GHOST_JOURNAL_ADMIN_KEY", + ] + + optional_vars = [ + "FIGMA_ACCESS_TOKEN", + "N8N_API_KEY", + ] + + if self.env_file.exists(): + env_content = self.env_file.read_text() + + for var in required_vars: + has_value = f"{var}=" in env_content and \ + f"{var}=<" not in env_content and \ + f"{var}=$" not in env_content + if self.check(f"Required: {var}", has_value, f"Set {var} in {self.env_file}"): + ok(f"{var}") + passed += 1 + else: + fail(f"{var} (required)") + + for var in optional_vars: + has_value = f"{var}=" in env_content and \ + f"{var}=<" not in env_content + if has_value: + ok(f"{var} (optional)") + passed += 1 + else: + warn(f"{var} (optional, not set)") + else: + fail("Environment file not found") + + return passed + + def validate_python_env(self) -> int: + """Check Python virtual environment.""" + info("Checking Python environment...") + passed = 0 + + if self.check("Virtual environment", self.venv_dir.exists(), + f"python3 -m venv {self.venv_dir}"): + ok("Virtual environment exists") + passed += 1 + + # Check for key packages + pip_path = self.venv_dir / "bin" / "pip" + if pip_path.exists(): + ok("pip available") + passed += 1 + else: + fail("Virtual environment not found") + + return passed + + def validate_skills(self) -> int: + """Check skills are properly structured.""" + info("Checking skills...") + passed = 0 + + expected_skills = [ + "01-ourdigital-brand-guide", + "02-ourdigital-blog", + "03-ourdigital-journal", + "04-ourdigital-research", + "05-ourdigital-document", + "06-ourdigital-designer", + "07-ourdigital-ad-manager", + "08-ourdigital-trainer", + "09-ourdigital-backoffice", + "10-ourdigital-skill-creator", + ] + + for skill in expected_skills: + skill_dir = self.skills_dir / skill + has_desktop = (skill_dir / "desktop" / "SKILL.md").exists() + has_code = (skill_dir / "code" / "SKILL.md").exists() + + if has_desktop and has_code: + ok(f"{skill}") + passed += 1 + elif has_desktop or has_code: + warn(f"{skill} (incomplete)") + else: + fail(f"{skill} (missing)") + + return passed + + def validate_permissions(self) -> int: + """Check file permissions are secure.""" + info("Checking permissions...") + passed = 0 + + if self.env_file.exists(): + mode = oct(self.env_file.stat().st_mode)[-3:] + if mode in ('600', '400'): + ok(f".env.ourdigital permissions ({mode})") + passed += 1 + else: + warn(f".env.ourdigital permissions ({mode}, should be 600)") + + creds_dir = self.config_dir / "credentials" + if creds_dir.exists(): + mode = oct(creds_dir.stat().st_mode)[-3:] + if mode in ('700', '500'): + ok(f"credentials/ permissions ({mode})") + passed += 1 + else: + warn(f"credentials/ permissions ({mode}, should be 700)") + + return passed + + def run(self) -> Dict[str, int]: + """Run all validation checks.""" + print(f"\n{Colors.CYAN}{Colors.BOLD}OurDigital Skills Installation Validator{Colors.END}\n") + + results = { + "directories": self.validate_directories(), + "files": self.validate_files(), + "env_variables": self.validate_env_variables(), + "python_env": self.validate_python_env(), + "skills": self.validate_skills(), + "permissions": self.validate_permissions(), + } + + # Summary + total_passed = sum(results.values()) + total_checks = len(self.results) + + print(f"\n{Colors.CYAN}{'='*50}{Colors.END}") + print(f"{Colors.BOLD}Summary:{Colors.END} {total_passed}/{total_checks} checks passed") + + if total_passed == total_checks: + print(f"{Colors.GREEN}All checks passed! Installation is complete.{Colors.END}") + else: + failed = [r for r in self.results if not r[1]] + print(f"{Colors.YELLOW}Some checks failed. Review above for details.{Colors.END}") + + if self.verbose: + print(f"\n{Colors.BOLD}Failed checks:{Colors.END}") + for name, _, fix in failed: + print(f" - {name}") + if fix: + print(f" Fix: {fix}") + + return results + + +def main(): + parser = argparse.ArgumentParser(description="Validate OurDigital Skills installation") + parser.add_argument("--verbose", "-v", action="store_true", + help="Show detailed output with fix suggestions") + parser.add_argument("--json", action="store_true", + help="Output results as JSON") + args = parser.parse_args() + + validator = InstallationValidator(verbose=args.verbose) + results = validator.run() + + if args.json: + print(json.dumps(results, indent=2)) + + # Exit with error if any checks failed + total_passed = sum(results.values()) + total_checks = len(validator.results) + sys.exit(0 if total_passed == total_checks else 1) + + +if __name__ == "__main__": + main() diff --git a/settings-audit-report.json b/docs/settings-audit-report.json similarity index 100% rename from settings-audit-report.json rename to docs/settings-audit-report.json diff --git a/settings-audit-report.md b/docs/settings-audit-report.md similarity index 100% rename from settings-audit-report.md rename to docs/settings-audit-report.md diff --git a/reference/SKILL-FORMAT-REQUIREMENTS.md b/reference/SKILL-FORMAT-REQUIREMENTS.md index 4566958..154aedb 100644 --- a/reference/SKILL-FORMAT-REQUIREMENTS.md +++ b/reference/SKILL-FORMAT-REQUIREMENTS.md @@ -4,15 +4,15 @@ This document describes the format requirements for Claude Skills in this repository. Skills support dual-platform development (Claude Code and Claude Desktop) with separated concerns. -## Desktop Skill Structure (Recommended) +## Desktop Skill Structure -For Claude Desktop skills, metadata is stored in a separate `skill.yaml` file: +For Claude Desktop skills: ``` skill-name/ └── desktop/ - ├── skill.yaml # Metadata (name, description, allowed-tools, license) - ├── SKILL.md # Content only (no frontmatter) + ├── SKILL.md # MUST have YAML frontmatter (name, description) + ├── skill.yaml # Optional extended metadata ├── tools/ # MCP tool documentation │ ├── firecrawl.md # Tool-specific docs │ └── notion.md @@ -20,10 +20,35 @@ skill-name/ └── examples/ # Usage examples ``` -### skill.yaml Format +### SKILL.md Format (REQUIRED) + +**Claude Desktop REQUIRES YAML frontmatter** with at least `name` and `description`. + +```markdown +--- +name: skill-name-here +description: | + Brief description of what the skill does. + Include trigger keywords in the description. + Triggers: keyword1, keyword2. +--- + +# Skill Name + +Purpose and overview... + +## Workflow + +Step-by-step instructions... + +## MCP Tool Usage + +Tool-specific guidance... +``` + +### skill.yaml (Optional, for extended metadata) ```yaml -# Required fields name: skill-name-here description: Brief description of what the skill does and trigger keywords @@ -46,24 +71,6 @@ triggers: - keyword2 ``` -### SKILL.md Content - -With metadata separated into skill.yaml, SKILL.md contains only the skill directive: - -```markdown -# Skill Name - -Purpose and overview... - -## Workflow - -Step-by-step instructions... - -## MCP Tool Usage - -Tool-specific guidance... -``` - ### tools/ Directory Document MCP tools used by the skill: @@ -145,18 +152,21 @@ The script: 3. Creates `tools/` directory 4. Generates tool stub files based on `allowed-tools` -## Legacy Format (Deprecated) +## Required vs Optional Fields -The old format with frontmatter embedded in SKILL.md is deprecated: +### SKILL.md Frontmatter (Required) -```yaml ---- -name: skill-name -description: Description -allowed-tools: mcp__firecrawl__*, Read, Write ---- +| Field | Required | Description | +|-------|----------|-------------| +| `name` | **Yes** | Skill identifier in kebab-case | +| `description` | **Yes** | Multi-line, include trigger keywords | -# Skill content... -``` +### skill.yaml (Optional) -Use the migration script to convert to the new format. +| Field | Description | +|-------|-------------| +| `name` | Same as SKILL.md | +| `description` | Same or extended | +| `allowed-tools` | List of permitted tools | +| `license` | MIT, Internal-use Only | +| `triggers` | Explicit trigger list |