feat: Add installation tool, Claude.ai export, and skill standardization (#1)
## Summary - Add portable installation tool (`install.sh`) for cross-machine setup - Add Claude.ai export files with proper YAML frontmatter - Add multi-agent-guide v2.0 with consolidated framework template - Rename `00-claude-code-setting` → `00-our-settings-audit` (avoid reserved word) - Add YAML frontmatter to 25+ SKILL.md files for Claude Desktop compatibility ## Commits Included - `93f604a` feat: Add portable installation tool for cross-machine setup - `9b84104` feat: Add Claude.ai export for portable skill installation - `f7ab973` fix: Add YAML frontmatter to Claude.ai export files - `3fed49a` feat(multi-agent-guide): Add v2.0 with consolidated framework - `3be26ef` refactor: Rename settings-audit skill and add YAML frontmatter Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
Andrew Yim
@@ -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/
|
||||
|
||||
@@ -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)
|
||||
125
custom-skills/00-our-settings-audit/README.md
Normal file
125
custom-skills/00-our-settings-audit/README.md
Normal file
@@ -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)
|
||||
633
custom-skills/00-our-settings-audit/desktop/SKILL.md
Normal file
633
custom-skills/00-our-settings-audit/desktop/SKILL.md
Normal file
@@ -0,0 +1,633 @@
|
||||
---
|
||||
name: our-settings-audit
|
||||
description: |
|
||||
Diagnose all Claude Desktop errors and optimize context usage.
|
||||
Covers 8 error categories: context limits, output interruption,
|
||||
length/file errors, usage limits, server capacity, MCP connection,
|
||||
account issues, and output quality problems.
|
||||
Triggers: settings audit, exceed response limit, MCP error, token error.
|
||||
---
|
||||
|
||||
# Claude Desktop Settings Checker
|
||||
|
||||
Diagnose Claude Desktop errors and optimize context usage.
|
||||
|
||||
## Error Quick Reference
|
||||
|
||||
| Error Type | Message Pattern | Category |
|
||||
|------------|-----------------|----------|
|
||||
| Context too large | "Exceed response limit" | Input |
|
||||
| Output interrupted | "Response could not be fully generated" | Output |
|
||||
| Length exceeded | "Message will exceed the length limit" | Input |
|
||||
| Conversation limit | "This conversation reached its maximum length" | Input |
|
||||
| File too large | "Files larger than 10mb" / "X% over the length limit" | File |
|
||||
| Rate limited | "5-hour limit reached" / "X messages left" | Usage |
|
||||
| Server overload | "Due to unexpected capacity constraints" | Server |
|
||||
| MCP failure | "Error connecting to [ServerName]" | MCP |
|
||||
| Account issue | "Account has been disabled" | Account |
|
||||
|
||||
## Quick Diagnosis Tree
|
||||
|
||||
```
|
||||
Error occurred?
|
||||
│
|
||||
├─ BEFORE response started?
|
||||
│ ├─ "Exceed response limit" → Reduce input context
|
||||
│ ├─ "Length limit" → Break into smaller messages
|
||||
│ ├─ "File too large" → Reduce file size or excerpt
|
||||
│ ├─ "Capacity constraints" → Wait and retry
|
||||
│ └─ "MCP error" → Check MCP configuration
|
||||
│
|
||||
├─ DURING response?
|
||||
│ ├─ "Could not be fully generated" → Request smaller output
|
||||
│ └─ Output suddenly stopped → Retry or chunk request
|
||||
│
|
||||
└─ BEFORE even sending?
|
||||
├─ "5-hour limit reached" → Wait for reset
|
||||
├─ "Messages left" → Near usage limit
|
||||
└─ "Account disabled" → Contact support
|
||||
```
|
||||
|
||||
## Understanding Token Limits
|
||||
|
||||
| Model | Context Window | Output Limit | Practical Available |
|
||||
|-------|---------------|--------------|---------------------|
|
||||
| Claude 3.5 Sonnet | 200K tokens | ~8K tokens | ~150K after system |
|
||||
| Claude 3 Opus | 200K tokens | ~4K tokens | ~150K after system |
|
||||
| Claude 3 Haiku | 200K tokens | ~4K tokens | ~160K after system |
|
||||
|
||||
---
|
||||
|
||||
# CATEGORY 1: Input/Context Errors
|
||||
|
||||
## Error: "Exceed response limit"
|
||||
|
||||
**Causes:**
|
||||
1. Loaded context too large (MCP tools + skills + files)
|
||||
2. Conversation history accumulated
|
||||
3. Multiple large files attached
|
||||
|
||||
## Quick Diagnosis
|
||||
|
||||
When user reports "Exceed response limit":
|
||||
|
||||
### Step 1: Check Loaded Context
|
||||
|
||||
Ask user to share their `claude_desktop_config.json`:
|
||||
- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
|
||||
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
|
||||
|
||||
Analyze:
|
||||
- [ ] Number of MCP servers configured
|
||||
- [ ] Servers with many tools (>20 tools each)
|
||||
- [ ] Missing or poor `serverInstructions`
|
||||
|
||||
### Step 2: Estimate Token Usage
|
||||
|
||||
| Component | Tokens (approx) | Notes |
|
||||
|-----------|-----------------|-------|
|
||||
| Per MCP server | 500-2,000 | Base overhead |
|
||||
| Per tool definition | 100-500 | Depends on schema complexity |
|
||||
| Playwright MCP | ~13,500 | 20+ tools, detailed schemas |
|
||||
| Notion MCP | ~5,000 | Moderate |
|
||||
| GitHub MCP | ~18,000 | Many tools |
|
||||
| Custom SKILL.md | 200-2,000 | Depends on length |
|
||||
| Attached file | Variable | ~4 tokens per word |
|
||||
|
||||
**Red flags:**
|
||||
- More than 5 MCP servers active
|
||||
- Any server without `serverInstructions`
|
||||
- Total MCP tools > 100
|
||||
|
||||
### Step 3: Review Loaded Skills
|
||||
|
||||
Check for:
|
||||
- Skills with long SKILL.md files (>1,000 words)
|
||||
- Multiple skills loaded simultaneously
|
||||
- Skills with embedded reference data
|
||||
|
||||
## Optimization Recommendations
|
||||
|
||||
### MCP Server Optimization
|
||||
|
||||
**Priority 1: Add serverInstructions**
|
||||
|
||||
Every MCP server needs concise instructions:
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"playwright": {
|
||||
"command": "...",
|
||||
"serverInstructions": "Browser automation for web testing. Use for: screenshots, page analysis, form testing. Keywords: browser, DOM, screenshot"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Pattern: `[Purpose]. Use for: [case1], [case2]. Keywords: [kw1], [kw2]`
|
||||
|
||||
**Priority 2: Reduce Active Servers**
|
||||
|
||||
Keep only essential servers active. Disable or remove:
|
||||
- Servers used less than weekly
|
||||
- Servers with overlapping functionality
|
||||
- Servers with 30+ tools (like Zapier)
|
||||
|
||||
### Conversation Management
|
||||
|
||||
**Before complex tasks:**
|
||||
1. Start fresh conversation for unrelated work
|
||||
2. Avoid attaching multiple large files
|
||||
3. Request concise outputs
|
||||
|
||||
**During long sessions:**
|
||||
1. Start new conversation at natural breakpoints
|
||||
2. Summarize important context before continuing
|
||||
3. Remove completed file attachments
|
||||
|
||||
### Project File Optimization
|
||||
|
||||
For project skills and configurations:
|
||||
|
||||
| File Type | Target Length | Max |
|
||||
|-----------|--------------|-----|
|
||||
| SKILL.md | 500 words | 1,000 words |
|
||||
| Project instructions | 200 words | 500 words |
|
||||
| Embedded data | 0 | Move to external |
|
||||
|
||||
**Optimization techniques:**
|
||||
1. Move reference data to separate files (load on demand)
|
||||
2. Use tables instead of prose
|
||||
3. Remove redundant information
|
||||
4. Link to documentation instead of embedding
|
||||
|
||||
## Token Budget Calculator
|
||||
|
||||
Help user calculate their baseline:
|
||||
|
||||
```
|
||||
System overhead: ~10,000 tokens (fixed)
|
||||
MCP servers: [count] × ~3,000 = [estimate]
|
||||
Loaded skills: [count] × ~500 = [estimate]
|
||||
Project instructions: ~[estimate based on length]
|
||||
────────────────────────────────────────────────
|
||||
Baseline total: [sum]
|
||||
Available for work: 200,000 - [sum] = [remaining]
|
||||
Available percentage: [remaining/200,000 × 100]%
|
||||
```
|
||||
|
||||
**Targets:**
|
||||
- Baseline: < 40,000 tokens (20%)
|
||||
- Available: > 160,000 tokens (80%)
|
||||
|
||||
**Warning zone:**
|
||||
- Baseline > 60,000 tokens: Likely to hit limits
|
||||
- Available < 140,000 tokens: Reduce configuration
|
||||
|
||||
## Output Format
|
||||
|
||||
After diagnosis, provide:
|
||||
|
||||
```markdown
|
||||
## Settings Check Report
|
||||
|
||||
### Configuration Summary
|
||||
- MCP Servers: [count] ([tokens estimate])
|
||||
- Active Skills: [count] ([tokens estimate])
|
||||
- Baseline Total: ~[X] tokens ([Y]%)
|
||||
- Available: ~[Z] tokens ([W]%)
|
||||
|
||||
### Issues Found
|
||||
1. [Critical]: [issue description]
|
||||
2. [Warning]: [issue description]
|
||||
|
||||
### Recommended Actions
|
||||
1. [Action with specific steps]
|
||||
2. [Action with specific steps]
|
||||
|
||||
### Quick Wins (immediate impact)
|
||||
- [ ] [Specific change]
|
||||
- [ ] [Specific change]
|
||||
```
|
||||
|
||||
## Common Scenarios
|
||||
|
||||
### Scenario: Too Many MCP Servers
|
||||
|
||||
**Symptoms:** Errors on first message of conversation
|
||||
**Solution:** Disable non-essential servers, add serverInstructions
|
||||
|
||||
### Scenario: Long Conversation History
|
||||
|
||||
**Symptoms:** Errors after many exchanges
|
||||
**Solution:** Start new conversation, summarize context
|
||||
|
||||
### Scenario: Large File Attachments
|
||||
|
||||
**Symptoms:** Errors when attaching files
|
||||
**Solution:** Attach smaller excerpts, use file references
|
||||
|
||||
### Scenario: Complex Skill Loaded
|
||||
|
||||
**Symptoms:** Errors when using specific skill
|
||||
**Solution:** Refactor skill, move data to references
|
||||
|
||||
---
|
||||
|
||||
## Error 2: "Response could not be fully generated"
|
||||
|
||||
This error occurs when **output generation** is interrupted mid-stream.
|
||||
|
||||
### Causes
|
||||
|
||||
| Cause | Description | Frequency |
|
||||
|-------|-------------|-----------|
|
||||
| **Output token limit** | Response exceeded ~4K-8K output limit | Common |
|
||||
| **Safety filter** | Content flagged during generation | Occasional |
|
||||
| **Network interruption** | Connection dropped mid-stream | Occasional |
|
||||
| **Server timeout** | Generation took too long | Rare |
|
||||
| **Rate limiting** | Too many requests in short time | Rare |
|
||||
|
||||
### Common Triggers
|
||||
|
||||
**1. Requesting too much output:**
|
||||
```
|
||||
❌ "Write a complete 50-page report on..."
|
||||
❌ "Generate the entire application code"
|
||||
❌ "List all 500 items with full descriptions"
|
||||
|
||||
✅ "Write section 1: introduction and overview"
|
||||
✅ "Generate the authentication module first"
|
||||
✅ "List items 1-50 with descriptions"
|
||||
```
|
||||
|
||||
**2. Vague prompts (produce longer responses):**
|
||||
```
|
||||
❌ "Explain everything about machine learning"
|
||||
✅ "Explain gradient descent in 3 paragraphs"
|
||||
```
|
||||
|
||||
**3. Code generation without scope:**
|
||||
```
|
||||
❌ "Build me a full-stack e-commerce site"
|
||||
✅ "Create the product listing component with pagination"
|
||||
```
|
||||
|
||||
### Solutions
|
||||
|
||||
| Situation | Fix |
|
||||
|-----------|-----|
|
||||
| Long report/document | Request section by section |
|
||||
| Large codebase | Generate module by module |
|
||||
| Comprehensive list | Paginate (1-50, 51-100, etc.) |
|
||||
| Detailed explanation | Ask for "brief" or "concise" version |
|
||||
| Transient failure | Simply retry the request |
|
||||
|
||||
### Prompting Techniques
|
||||
|
||||
**Add output constraints:**
|
||||
- "In under 500 words..."
|
||||
- "Provide a concise summary..."
|
||||
- "List the top 10..."
|
||||
- "Focus only on..."
|
||||
|
||||
**Chunk large tasks:**
|
||||
- "First, outline the structure"
|
||||
- "Now write section 1"
|
||||
- "Continue with section 2"
|
||||
|
||||
**Request format control:**
|
||||
- "Use bullet points, not paragraphs"
|
||||
- "Provide a table summary"
|
||||
- "Give me just the key points"
|
||||
|
||||
### When to Retry vs. Rephrase
|
||||
|
||||
| Scenario | Action |
|
||||
|----------|--------|
|
||||
| Error on first attempt | Retry once |
|
||||
| Error persists after retry | Rephrase with smaller scope |
|
||||
| Error always at same point | Content may be triggering filter |
|
||||
| Error after long generation | Request was too ambitious |
|
||||
|
||||
---
|
||||
|
||||
# CATEGORY 3: Length & File Errors
|
||||
|
||||
## Error: "Your message will exceed the length limit"
|
||||
|
||||
**Full message:** "Your message will exceed the length limit for this chat..."
|
||||
|
||||
**Causes:**
|
||||
- Single message too long (approaching context limit)
|
||||
- Too much text pasted at once
|
||||
|
||||
**Solutions:**
|
||||
1. Break content into smaller chunks
|
||||
2. Summarize key sections before sending
|
||||
3. Ask Claude to identify relevant portions first
|
||||
4. Start a new conversation
|
||||
|
||||
## Error: "This conversation reached its maximum length"
|
||||
|
||||
**Cause:** Accumulated conversation history filled context window
|
||||
|
||||
**Solutions:**
|
||||
1. Start a new conversation
|
||||
2. Copy essential context to new chat
|
||||
3. Use shorter exchanges going forward
|
||||
|
||||
## Error: "Message is X% over the length limit"
|
||||
|
||||
**Full message:** "Message is X% over the length limit. Try replacing the attached file with smaller excerpts."
|
||||
|
||||
**Cause:** Attached file(s) too large for remaining context
|
||||
|
||||
**Solutions:**
|
||||
1. Extract relevant excerpts only
|
||||
2. Summarize large documents before attaching
|
||||
3. Split across multiple messages
|
||||
4. Use file references instead of full content
|
||||
|
||||
## Error: "You may not upload files larger than 10MB"
|
||||
|
||||
**Cause:** Single file exceeds 10MB limit
|
||||
|
||||
**Solutions:**
|
||||
1. Compress file if possible
|
||||
2. Split into smaller files
|
||||
3. Extract text content only
|
||||
4. Use external link and describe content
|
||||
|
||||
---
|
||||
|
||||
# CATEGORY 4: Usage & Rate Limit Errors
|
||||
|
||||
## Error: "5-hour limit reached - resets [time]"
|
||||
|
||||
**Cause:** Hit plan's usage cap within 5-hour window
|
||||
|
||||
**Solutions:**
|
||||
1. Wait until reset time shown
|
||||
2. Upgrade plan for higher limits
|
||||
3. Optimize prompts to use fewer tokens
|
||||
|
||||
## Error: "Approaching 5-hour limit"
|
||||
|
||||
**Cause:** Warning before hitting limit
|
||||
|
||||
**Solutions:**
|
||||
1. Prioritize remaining important tasks
|
||||
2. Use concise prompts
|
||||
3. Avoid exploratory conversations
|
||||
|
||||
## Error: "X messages left until [time]"
|
||||
|
||||
**Cause:** Near message limit (free tier)
|
||||
|
||||
**Solutions:**
|
||||
1. Combine multiple questions into one
|
||||
2. Wait for reset
|
||||
3. Consider paid plan
|
||||
|
||||
## Error: "5-hour limit resets [time] - continuing with extra usage"
|
||||
|
||||
**Note:** This is informational for paid plans with extra usage enabled
|
||||
**Action:** Extra usage automatically continues; monitor costs
|
||||
|
||||
---
|
||||
|
||||
# CATEGORY 5: Server & Capacity Errors
|
||||
|
||||
## Error: "Due to unexpected capacity constraints, Claude is unable to respond"
|
||||
|
||||
**Cause:** High system-wide demand
|
||||
|
||||
**Solutions:**
|
||||
1. Wait 2-5 minutes and retry
|
||||
2. Try during off-peak hours
|
||||
3. Check [status.claude.com](https://status.claude.com) for incidents
|
||||
|
||||
## HTTP Error Codes
|
||||
|
||||
| Code | Meaning | Solution |
|
||||
|------|---------|----------|
|
||||
| 500 | Internal Server Error | Wait and retry |
|
||||
| 429 | Too Many Requests | Slow down, wait |
|
||||
| 403 | Forbidden | Check account status |
|
||||
| 400 | Bad Request | Check input format |
|
||||
|
||||
## Error: "Claude AI Saving Chat Failed"
|
||||
|
||||
**Cause:** Issue saving conversation to servers
|
||||
|
||||
**Solutions:**
|
||||
1. Refresh the page
|
||||
2. Check internet connection
|
||||
3. Copy important content locally
|
||||
4. Try again later
|
||||
|
||||
---
|
||||
|
||||
# CATEGORY 6: MCP Connection Errors
|
||||
|
||||
## Error: "There was an error connecting to [ServerName]"
|
||||
|
||||
**Causes:**
|
||||
1. Server not running
|
||||
2. Incorrect configuration
|
||||
3. Transport type mismatch (stdio vs HTTP)
|
||||
4. Authentication failure
|
||||
|
||||
### Diagnosis Steps
|
||||
|
||||
**Step 1: Check server logs**
|
||||
- macOS: `~/Library/Logs/Claude/mcp-server-SERVERNAME.log`
|
||||
- Windows: `%APPDATA%\Claude\logs\mcp-server-SERVERNAME.log`
|
||||
|
||||
**Step 2: Verify configuration**
|
||||
```bash
|
||||
# macOS
|
||||
cat ~/Library/Application\ Support/Claude/claude_desktop_config.json
|
||||
|
||||
# Windows PowerShell
|
||||
Get-Content "$env:APPDATA\Claude\claude_desktop_config.json"
|
||||
```
|
||||
|
||||
**Step 3: Test server independently**
|
||||
```bash
|
||||
# Test if server starts
|
||||
npx @anthropic-ai/mcp-server-name
|
||||
```
|
||||
|
||||
### Common MCP Issues
|
||||
|
||||
| Issue | Symptom | Fix |
|
||||
|-------|---------|-----|
|
||||
| Transport mismatch | HTTP server with stdio config | Add `"transport": "http"` |
|
||||
| Path with spaces | Server fails on Windows | Use escaped paths or `%APPDATA%` |
|
||||
| Missing env vars | Auth failures | Add to `"env"` in config |
|
||||
| Server not installed | "command not found" | Run `npm install -g` first |
|
||||
| Port conflict | Server won't start | Change port or kill existing |
|
||||
|
||||
### After Config Changes
|
||||
|
||||
**Critical:** Completely quit and restart Claude Desktop after any config changes.
|
||||
|
||||
## Error: "Required parameter" validation errors
|
||||
|
||||
**Cause:** MCP tool schema mismatch (regression bug)
|
||||
|
||||
**Solutions:**
|
||||
1. Update Claude Desktop to latest version
|
||||
2. Check MCP server for updates
|
||||
3. Temporarily disable problematic server
|
||||
|
||||
---
|
||||
|
||||
# CATEGORY 7: Account Errors
|
||||
|
||||
## Error: "Your account has been disabled"
|
||||
|
||||
**Full message:** "Your account has been disabled after an automatic review of your recent activities."
|
||||
|
||||
**Cause:** Automated system flagged account
|
||||
|
||||
**Solutions:**
|
||||
1. Contact Anthropic support
|
||||
2. Review Terms of Service
|
||||
3. Do not create new accounts (may worsen situation)
|
||||
|
||||
## Error: "This organization has been disabled"
|
||||
|
||||
**Cause:** Organization-level suspension
|
||||
|
||||
**Solution:** Organization admin must contact Anthropic
|
||||
|
||||
## Error: "There was an error logging you in"
|
||||
|
||||
**Causes:**
|
||||
- VPN interference
|
||||
- Browser extensions blocking
|
||||
- Cached credentials issue
|
||||
|
||||
**Solutions:**
|
||||
1. Disable VPN
|
||||
2. Disable browser extensions temporarily
|
||||
3. Clear browser cache and cookies
|
||||
4. Try incognito/private window
|
||||
5. Check [status.claude.com](https://status.claude.com)
|
||||
|
||||
## Error: "Error Sending Codes - Check Your Phone Number"
|
||||
|
||||
**Cause:** Phone verification failed during signup
|
||||
|
||||
**Solutions:**
|
||||
1. Verify correct country code
|
||||
2. Check all digits entered correctly
|
||||
3. Try different phone number
|
||||
4. Wait and retry later
|
||||
|
||||
---
|
||||
|
||||
# CATEGORY 8: Output Quality Issues
|
||||
|
||||
## Issue: Output Suddenly Stops (Cutoff)
|
||||
|
||||
**Symptoms:** Response ends mid-sentence or mid-code
|
||||
|
||||
**Causes:**
|
||||
1. Hit output token limit (~4K-8K)
|
||||
2. Safety filter triggered
|
||||
3. Server timeout
|
||||
|
||||
**Solutions:**
|
||||
1. Ask "Please continue from where you stopped"
|
||||
2. Request smaller chunks upfront
|
||||
3. Be more specific in scope
|
||||
|
||||
## Issue: Gibberish or Nonsensical Output
|
||||
|
||||
**Symptoms:** Incoherent text, random characters
|
||||
|
||||
**Causes:**
|
||||
1. Model confusion from complex prompt
|
||||
2. Conflicting instructions
|
||||
3. Edge case in training
|
||||
|
||||
**Solutions:**
|
||||
1. Simplify prompt
|
||||
2. Start new conversation
|
||||
3. Rephrase request differently
|
||||
|
||||
## Issue: Mixed Languages or Character Issues
|
||||
|
||||
**Symptoms:** Unexpected language switches, formatting problems
|
||||
|
||||
**Causes:**
|
||||
1. Ambiguous language context
|
||||
2. Copy-pasted special characters
|
||||
|
||||
**Solutions:**
|
||||
1. Explicitly state desired language
|
||||
2. Clean input text of special characters
|
||||
3. Add "Please respond in [language]"
|
||||
|
||||
## Issue: Claude Refuses to Respond
|
||||
|
||||
**Symptoms:** Declines request citing policy
|
||||
|
||||
**Causes:**
|
||||
1. Request triggered safety guidelines
|
||||
2. Ambiguous phrasing interpreted as harmful
|
||||
|
||||
**Solutions:**
|
||||
1. Rephrase more clearly
|
||||
2. Explain legitimate use case
|
||||
3. Break into smaller, clearer requests
|
||||
|
||||
---
|
||||
|
||||
## Prevention Checklist
|
||||
|
||||
### Context/Input Errors
|
||||
|
||||
- [ ] Maximum 5 MCP servers active
|
||||
- [ ] All servers have serverInstructions
|
||||
- [ ] Skills under 1,000 words
|
||||
- [ ] Start fresh conversations for new topics
|
||||
- [ ] Avoid attaching files over 50KB (prefer excerpts)
|
||||
- [ ] Individual files under 10MB
|
||||
|
||||
### Output Errors
|
||||
|
||||
- [ ] Break large requests into chunks
|
||||
- [ ] Use specific scope in prompts
|
||||
- [ ] Request concise/brief outputs when possible
|
||||
- [ ] Paginate lists and tables (50 items max)
|
||||
- [ ] Generate code module by module
|
||||
- [ ] Retry once before rephrasing
|
||||
|
||||
### Usage Limits
|
||||
|
||||
- [ ] Monitor "messages left" warnings
|
||||
- [ ] Combine related questions into single prompts
|
||||
- [ ] Use concise prompts to conserve tokens
|
||||
- [ ] Know your plan's reset schedule
|
||||
|
||||
### MCP Stability
|
||||
|
||||
- [ ] Test MCP servers independently before adding
|
||||
- [ ] Keep server logs accessible for debugging
|
||||
- [ ] Restart Claude Desktop after config changes
|
||||
- [ ] Update MCP servers regularly
|
||||
- [ ] Document working configurations
|
||||
|
||||
### General Best Practices
|
||||
|
||||
- [ ] Check [status.claude.com](https://status.claude.com) when experiencing issues
|
||||
- [ ] Keep Claude Desktop updated
|
||||
- [ ] Clear browser cache periodically (web version)
|
||||
- [ ] Disable VPN if experiencing login issues
|
||||
- [ ] Back up important conversations locally
|
||||
@@ -0,0 +1,76 @@
|
||||
# Sample Settings Check Report
|
||||
|
||||
## Configuration Summary
|
||||
|
||||
| Component | Count | Tokens (est.) | Status |
|
||||
|-----------|-------|---------------|--------|
|
||||
| MCP Servers | 6 | ~45,000 | ⚠️ High |
|
||||
| Active Skills | 3 | ~1,500 | ✓ OK |
|
||||
| Project Files | 2 | ~2,000 | ✓ OK |
|
||||
| **Baseline Total** | — | ~48,500 | ⚠️ Warning |
|
||||
| **Available** | — | ~151,500 (76%) | Marginal |
|
||||
|
||||
## Issues Found
|
||||
|
||||
### Critical
|
||||
1. **GitHub MCP server loading all tools** (~18,000 tokens)
|
||||
- 25+ tools loaded but only 3-4 commonly used
|
||||
- Missing `serverInstructions`
|
||||
|
||||
### Warnings
|
||||
1. **Zapier MCP enabled** (~25,000 tokens)
|
||||
- 50+ tools, rarely used
|
||||
- Consider disabling
|
||||
|
||||
2. **Playwright missing serverInstructions**
|
||||
- Tool discovery inefficient
|
||||
- Add: `"serverInstructions": "Browser automation..."`
|
||||
|
||||
3. **Custom skill SKILL.md is 1,500 words**
|
||||
- Exceeds 1,000 word recommendation
|
||||
- Move reference data to separate file
|
||||
|
||||
## Recommended Actions
|
||||
|
||||
### Immediate (save ~35,000 tokens)
|
||||
|
||||
1. **Disable Zapier MCP** (saves ~25,000)
|
||||
```json
|
||||
// Remove or comment out in claude_desktop_config.json
|
||||
// "zapier": { ... }
|
||||
```
|
||||
|
||||
2. **Add serverInstructions to all servers** (saves ~5,000)
|
||||
```json
|
||||
"github": {
|
||||
"command": "...",
|
||||
"serverInstructions": "GitHub operations. Use for: repos, issues, PRs. Keywords: github, repo, issue, pull request"
|
||||
}
|
||||
```
|
||||
|
||||
3. **Refactor long skill** (saves ~1,000)
|
||||
- Move data tables to `references/` directory
|
||||
- Keep SKILL.md under 500 words
|
||||
|
||||
### Secondary
|
||||
|
||||
4. Consider starting fresh conversations for unrelated tasks
|
||||
5. Review GitHub usage - if only for viewing, use web instead
|
||||
|
||||
## After Optimization
|
||||
|
||||
| Component | Tokens (est.) | Status |
|
||||
|-----------|---------------|--------|
|
||||
| MCP Servers | ~15,000 | ✓ Good |
|
||||
| Skills + Files | ~2,500 | ✓ Good |
|
||||
| **Baseline Total** | ~17,500 | ✓ Good |
|
||||
| **Available** | ~182,500 (91%) | ✓ Excellent |
|
||||
|
||||
## Quick Wins Checklist
|
||||
|
||||
- [x] Disable Zapier MCP
|
||||
- [x] Add serverInstructions to Playwright
|
||||
- [x] Add serverInstructions to GitHub
|
||||
- [x] Add serverInstructions to Notion
|
||||
- [ ] Refactor jamie-brand skill (move procedures data)
|
||||
- [ ] Review PostgreSQL usage frequency
|
||||
@@ -0,0 +1,77 @@
|
||||
# Claude Desktop Configuration Locations
|
||||
|
||||
## Primary Config File
|
||||
|
||||
### macOS
|
||||
```
|
||||
~/Library/Application Support/Claude/claude_desktop_config.json
|
||||
```
|
||||
|
||||
### Windows
|
||||
```
|
||||
%APPDATA%\Claude\claude_desktop_config.json
|
||||
```
|
||||
|
||||
### Linux
|
||||
```
|
||||
~/.config/Claude/claude_desktop_config.json
|
||||
```
|
||||
|
||||
## MCP Server Configuration Example
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"playwright": {
|
||||
"command": "npx",
|
||||
"args": ["-y", "@anthropic-ai/mcp-playwright"],
|
||||
"serverInstructions": "Browser automation. Use for: screenshots, page testing, DOM inspection. Keywords: browser, page, screenshot, navigate"
|
||||
},
|
||||
"notion": {
|
||||
"command": "npx",
|
||||
"args": ["-y", "@anthropic-ai/mcp-notion", "--token", "YOUR_TOKEN"],
|
||||
"serverInstructions": "Notion workspace access. Use for: search pages, create content, update databases. Keywords: notion, page, database, workspace"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Key Fields
|
||||
|
||||
| Field | Purpose | Token Impact |
|
||||
|-------|---------|--------------|
|
||||
| `command` | Executable path | Minimal |
|
||||
| `args` | Arguments | Minimal |
|
||||
| `serverInstructions` | Usage hints | Reduces discovery overhead |
|
||||
| `env` | Environment vars | None |
|
||||
|
||||
## serverInstructions Best Practices
|
||||
|
||||
**Good:**
|
||||
```json
|
||||
"serverInstructions": "File system access. Use for: read/write files, directory listing. Keywords: file, read, write, directory"
|
||||
```
|
||||
|
||||
**Bad (too vague):**
|
||||
```json
|
||||
"serverInstructions": "Various file operations"
|
||||
```
|
||||
|
||||
**Bad (too long):**
|
||||
```json
|
||||
"serverInstructions": "This MCP server provides comprehensive file system access capabilities including reading files, writing files, creating directories, listing directory contents, and more. It can be used for any operation that requires..."
|
||||
```
|
||||
|
||||
## Viewing Current Configuration
|
||||
|
||||
Ask user to run:
|
||||
|
||||
**macOS/Linux:**
|
||||
```bash
|
||||
cat ~/Library/Application\ Support/Claude/claude_desktop_config.json | python3 -m json.tool
|
||||
```
|
||||
|
||||
**Windows (PowerShell):**
|
||||
```powershell
|
||||
Get-Content "$env:APPDATA\Claude\claude_desktop_config.json" | ConvertFrom-Json | ConvertTo-Json -Depth 10
|
||||
```
|
||||
@@ -0,0 +1,88 @@
|
||||
# MCP Server Token Estimates
|
||||
|
||||
Approximate token usage for common MCP servers when loaded.
|
||||
|
||||
## Official Anthropic Servers
|
||||
|
||||
| Server | Tools | Tokens (est.) | Recommendation |
|
||||
|--------|-------|---------------|----------------|
|
||||
| Playwright | 20+ | 13,500 | Keep if testing |
|
||||
| Filesystem | 8 | 4,000 | Essential |
|
||||
| Memory | 5 | 3,000 | Optional |
|
||||
| Brave Search | 2 | 1,500 | Alternative to web |
|
||||
| Fetch | 2 | 1,200 | Keep for web access |
|
||||
|
||||
## Third-Party Servers
|
||||
|
||||
| Server | Tools | Tokens (est.) | Recommendation |
|
||||
|--------|-------|---------------|----------------|
|
||||
| Notion | 10 | 5,000 | Keep if using Notion |
|
||||
| GitHub | 25+ | 18,000 | Lazy load only |
|
||||
| PostgreSQL | 15 | 8,000 | Lazy load only |
|
||||
| Slack | 12 | 6,000 | Lazy load only |
|
||||
| Figma | 15 | 10,000 | Lazy load only |
|
||||
| Zapier | 50+ | 25,000+ | **Avoid** |
|
||||
| Firecrawl | 5 | 3,500 | Useful for SEO |
|
||||
| Perplexity | 2 | 1,500 | Alternative to web |
|
||||
|
||||
## Token Budget Guidelines
|
||||
|
||||
### Conservative Setup (High Available Context)
|
||||
```
|
||||
2-3 essential MCP servers
|
||||
Total: ~10,000-15,000 tokens
|
||||
Available: 185,000+ tokens (92%+)
|
||||
```
|
||||
|
||||
### Standard Setup
|
||||
```
|
||||
4-5 MCP servers
|
||||
Total: ~20,000-30,000 tokens
|
||||
Available: 170,000+ tokens (85%+)
|
||||
```
|
||||
|
||||
### Heavy Setup (Risk Zone)
|
||||
```
|
||||
6+ MCP servers
|
||||
Total: 40,000+ tokens
|
||||
Available: <160,000 tokens (<80%)
|
||||
⚠️ Higher chance of "Exceed response limit"
|
||||
```
|
||||
|
||||
## Reduction Strategies
|
||||
|
||||
### If using GitHub MCP heavily:
|
||||
- Start conversation specifically for GitHub work
|
||||
- Don't load other heavy servers simultaneously
|
||||
|
||||
### If using multiple API servers:
|
||||
- Choose ONE per category:
|
||||
- Web search: Brave OR Perplexity (not both)
|
||||
- Automation: Zapier OR n8n (not both)
|
||||
- Database: PostgreSQL OR MySQL (not both)
|
||||
|
||||
### If testing/development:
|
||||
- Playwright OR Puppeteer (not both)
|
||||
- Load only when actively testing
|
||||
|
||||
## Impact of serverInstructions
|
||||
|
||||
**Without serverInstructions:**
|
||||
- Full tool schemas loaded (~500 tokens per tool)
|
||||
- Discovery overhead on each interaction
|
||||
|
||||
**With serverInstructions:**
|
||||
- Reduced discovery queries
|
||||
- More efficient tool selection
|
||||
- Saves ~30-50% on tool-related tokens
|
||||
|
||||
## Quick Reference
|
||||
|
||||
**Token estimation formula:**
|
||||
```
|
||||
Server tokens ≈ (number of tools × 400) + 500 base
|
||||
```
|
||||
|
||||
**Example:**
|
||||
- 10 tools = (10 × 400) + 500 = 4,500 tokens
|
||||
- 25 tools = (25 × 400) + 500 = 10,500 tokens
|
||||
@@ -0,0 +1,349 @@
|
||||
# Claude Settings Audit Guide
|
||||
|
||||
> **Purpose**: Condensed reference for Claude.ai Projects
|
||||
> **Source**: 00-claude-settings-audit skill
|
||||
> **Version**: 1.0
|
||||
|
||||
Comprehensive reference for diagnosing Claude Desktop errors and optimizing context usage.
|
||||
|
||||
## Error Quick Reference
|
||||
|
||||
| Error Type | Message Pattern | Category |
|
||||
|------------|-----------------|----------|
|
||||
| Context too large | "Exceed response limit" | Input |
|
||||
| Output interrupted | "Response could not be fully generated" | Output |
|
||||
| Length exceeded | "Message will exceed the length limit" | Input |
|
||||
| Conversation limit | "Conversation reached maximum length" | Input |
|
||||
| File too large | "Files larger than 10mb" | File |
|
||||
| Rate limited | "5-hour limit reached" | Usage |
|
||||
| Server overload | "Unexpected capacity constraints" | Server |
|
||||
| MCP failure | "Error connecting to [ServerName]" | MCP |
|
||||
| Account issue | "Account has been disabled" | Account |
|
||||
|
||||
## Quick Diagnosis Tree
|
||||
|
||||
```
|
||||
Error occurred?
|
||||
│
|
||||
├─ BEFORE response started?
|
||||
│ ├─ "Exceed response limit" → Reduce input context
|
||||
│ ├─ "Length limit" → Break into smaller messages
|
||||
│ ├─ "File too large" → Reduce file size or excerpt
|
||||
│ ├─ "Capacity constraints" → Wait and retry
|
||||
│ └─ "MCP error" → Check MCP configuration
|
||||
│
|
||||
├─ DURING response?
|
||||
│ ├─ "Could not be fully generated" → Request smaller output
|
||||
│ └─ Output suddenly stopped → Retry or chunk request
|
||||
│
|
||||
└─ BEFORE even sending?
|
||||
├─ "5-hour limit reached" → Wait for reset
|
||||
├─ "Messages left" → Near usage limit
|
||||
└─ "Account disabled" → Contact support
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Token Limits by Model
|
||||
|
||||
| Model | Context Window | Output Limit | Practical Available |
|
||||
|-------|---------------|--------------|---------------------|
|
||||
| Claude 3.5 Sonnet | 200K tokens | ~8K tokens | ~150K after system |
|
||||
| Claude 3 Opus | 200K tokens | ~4K tokens | ~150K after system |
|
||||
| Claude 3 Haiku | 200K tokens | ~4K tokens | ~160K after system |
|
||||
|
||||
---
|
||||
|
||||
# ERROR CATEGORIES
|
||||
|
||||
## 1. Input/Context Errors
|
||||
|
||||
### "Exceed response limit"
|
||||
|
||||
**Causes:**
|
||||
- Loaded context too large (MCP tools + skills + files)
|
||||
- Conversation history accumulated
|
||||
- Multiple large files attached
|
||||
|
||||
**Solutions:**
|
||||
1. Reduce MCP servers (max 5 recommended)
|
||||
2. Add `serverInstructions` to all MCP servers
|
||||
3. Start fresh conversation
|
||||
4. Attach file excerpts instead of full files
|
||||
|
||||
### "Message will exceed the length limit"
|
||||
|
||||
**Solutions:**
|
||||
1. Break content into smaller chunks
|
||||
2. Summarize key sections before sending
|
||||
3. Start a new conversation
|
||||
|
||||
### "Conversation reached maximum length"
|
||||
|
||||
**Solutions:**
|
||||
1. Start a new conversation
|
||||
2. Copy essential context to new chat
|
||||
|
||||
---
|
||||
|
||||
## 2. Output Errors
|
||||
|
||||
### "Response could not be fully generated"
|
||||
|
||||
**Causes:**
|
||||
- Output exceeded ~4K-8K token limit
|
||||
- Safety filter triggered
|
||||
- Network interruption
|
||||
- Server timeout
|
||||
|
||||
**Solutions:**
|
||||
1. Request smaller chunks of output
|
||||
2. Add constraints: "In under 500 words..."
|
||||
3. Be more specific in scope
|
||||
4. Retry once before rephrasing
|
||||
|
||||
**Prompting techniques:**
|
||||
- "Provide a concise summary..."
|
||||
- "List the top 10..."
|
||||
- "First, outline the structure"
|
||||
- "Use bullet points, not paragraphs"
|
||||
|
||||
---
|
||||
|
||||
## 3. File Errors
|
||||
|
||||
### "Files larger than 10MB"
|
||||
|
||||
**Solutions:**
|
||||
1. Compress file if possible
|
||||
2. Split into smaller files
|
||||
3. Extract text content only
|
||||
|
||||
### "Message is X% over the length limit"
|
||||
|
||||
**Solutions:**
|
||||
1. Extract relevant excerpts only
|
||||
2. Summarize large documents
|
||||
3. Split across multiple messages
|
||||
|
||||
---
|
||||
|
||||
## 4. Usage Limit Errors
|
||||
|
||||
### "5-hour limit reached"
|
||||
|
||||
**Solutions:**
|
||||
1. Wait until reset time shown
|
||||
2. Upgrade plan for higher limits
|
||||
3. Optimize prompts to use fewer tokens
|
||||
|
||||
### "X messages left until [time]"
|
||||
|
||||
**Solutions:**
|
||||
1. Combine multiple questions into one
|
||||
2. Wait for reset
|
||||
3. Consider paid plan
|
||||
|
||||
---
|
||||
|
||||
## 5. Server/Capacity Errors
|
||||
|
||||
### "Unexpected capacity constraints"
|
||||
|
||||
**Solutions:**
|
||||
1. Wait 2-5 minutes and retry
|
||||
2. Try during off-peak hours
|
||||
3. Check status.claude.com for incidents
|
||||
|
||||
### HTTP Error Codes
|
||||
|
||||
| Code | Meaning | Solution |
|
||||
|------|---------|----------|
|
||||
| 500 | Internal Server Error | Wait and retry |
|
||||
| 429 | Too Many Requests | Slow down, wait |
|
||||
| 403 | Forbidden | Check account status |
|
||||
| 400 | Bad Request | Check input format |
|
||||
|
||||
---
|
||||
|
||||
## 6. MCP Connection Errors
|
||||
|
||||
### "Error connecting to [ServerName]"
|
||||
|
||||
**Causes:**
|
||||
1. Server not running
|
||||
2. Incorrect configuration
|
||||
3. Transport type mismatch (stdio vs HTTP)
|
||||
4. Authentication failure
|
||||
|
||||
**Diagnosis steps:**
|
||||
1. Check server logs:
|
||||
- macOS: `~/Library/Logs/Claude/mcp-server-SERVERNAME.log`
|
||||
- Windows: `%APPDATA%\Claude\logs\mcp-server-SERVERNAME.log`
|
||||
|
||||
2. Verify configuration in `claude_desktop_config.json`
|
||||
|
||||
3. Test server independently
|
||||
|
||||
**Common fixes:**
|
||||
|
||||
| Issue | Fix |
|
||||
|-------|-----|
|
||||
| Transport mismatch | Add `"transport": "http"` to config |
|
||||
| Path with spaces | Use escaped paths |
|
||||
| Missing env vars | Add to `"env"` in config |
|
||||
| Server not installed | Run `npm install -g` first |
|
||||
|
||||
**Critical:** Restart Claude Desktop after config changes.
|
||||
|
||||
---
|
||||
|
||||
## 7. Account Errors
|
||||
|
||||
### "Account has been disabled"
|
||||
|
||||
**Solutions:**
|
||||
1. Contact Anthropic support
|
||||
2. Review Terms of Service
|
||||
3. Do not create new accounts
|
||||
|
||||
### "Error logging you in"
|
||||
|
||||
**Solutions:**
|
||||
1. Disable VPN
|
||||
2. Clear browser cache and cookies
|
||||
3. Try incognito window
|
||||
4. Check status.claude.com
|
||||
|
||||
---
|
||||
|
||||
## 8. Output Quality Issues
|
||||
|
||||
### Output Suddenly Stops
|
||||
|
||||
**Solutions:**
|
||||
1. Ask "Please continue from where you stopped"
|
||||
2. Request smaller chunks upfront
|
||||
3. Be more specific in scope
|
||||
|
||||
### Gibberish Output
|
||||
|
||||
**Solutions:**
|
||||
1. Simplify prompt
|
||||
2. Start new conversation
|
||||
3. Rephrase request differently
|
||||
|
||||
### Claude Refuses to Respond
|
||||
|
||||
**Solutions:**
|
||||
1. Rephrase more clearly
|
||||
2. Explain legitimate use case
|
||||
3. Break into smaller requests
|
||||
|
||||
---
|
||||
|
||||
# TOKEN BUDGET GUIDELINES
|
||||
|
||||
## MCP Server Token Estimates
|
||||
|
||||
| Server | Tokens (approx) |
|
||||
|--------|-----------------|
|
||||
| Playwright | ~13,500 |
|
||||
| Notion | ~5,000 |
|
||||
| GitHub | ~18,000 |
|
||||
| Filesystem | ~4,000 |
|
||||
| Zapier | ~25,000+ (avoid) |
|
||||
|
||||
## serverInstructions Pattern
|
||||
|
||||
Every MCP server should have:
|
||||
|
||||
```json
|
||||
"serverInstructions": "[Purpose]. Use for: [case1], [case2]. Keywords: [kw1], [kw2]"
|
||||
```
|
||||
|
||||
Example:
|
||||
```json
|
||||
"serverInstructions": "Browser automation. Use for: screenshots, page testing. Keywords: browser, DOM, screenshot"
|
||||
```
|
||||
|
||||
## Budget Calculator
|
||||
|
||||
```
|
||||
System overhead: ~10,000 tokens (fixed)
|
||||
MCP servers: [count] × ~3,000 = [estimate]
|
||||
Loaded skills: [count] × ~500 = [estimate]
|
||||
Project instructions: ~[estimate]
|
||||
────────────────────────────────────────────
|
||||
Baseline total: [sum]
|
||||
Available for work: 200,000 - [sum] = [remaining]
|
||||
```
|
||||
|
||||
**Targets:**
|
||||
- Baseline: < 40,000 tokens (20%)
|
||||
- Available: > 160,000 tokens (80%)
|
||||
|
||||
---
|
||||
|
||||
# PREVENTION CHECKLIST
|
||||
|
||||
## Context/Input
|
||||
- [ ] Maximum 5 MCP servers active
|
||||
- [ ] All servers have serverInstructions
|
||||
- [ ] Skills under 1,000 words
|
||||
- [ ] Start fresh conversations for new topics
|
||||
- [ ] Files under 10MB, prefer excerpts
|
||||
|
||||
## Output
|
||||
- [ ] Break large requests into chunks
|
||||
- [ ] Use specific scope in prompts
|
||||
- [ ] Paginate lists (50 items max)
|
||||
- [ ] Retry once before rephrasing
|
||||
|
||||
## Usage Limits
|
||||
- [ ] Monitor "messages left" warnings
|
||||
- [ ] Combine related questions
|
||||
- [ ] Use concise prompts
|
||||
|
||||
## MCP Stability
|
||||
- [ ] Test servers before adding
|
||||
- [ ] Restart app after config changes
|
||||
- [ ] Keep servers updated
|
||||
|
||||
## General
|
||||
- [ ] Check status.claude.com when issues occur
|
||||
- [ ] Keep Claude Desktop updated
|
||||
- [ ] Back up important conversations
|
||||
|
||||
---
|
||||
|
||||
# CONFIGURATION LOCATIONS
|
||||
|
||||
## Config Files
|
||||
|
||||
**macOS:**
|
||||
```
|
||||
~/Library/Application Support/Claude/claude_desktop_config.json
|
||||
```
|
||||
|
||||
**Windows:**
|
||||
```
|
||||
%APPDATA%\Claude\claude_desktop_config.json
|
||||
```
|
||||
|
||||
## Log Files
|
||||
|
||||
**macOS:**
|
||||
```
|
||||
~/Library/Logs/Claude/mcp-server-SERVERNAME.log
|
||||
```
|
||||
|
||||
**Windows:**
|
||||
```
|
||||
%APPDATA%\Claude\logs\mcp-server-SERVERNAME.log
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
*Reference: Claude Settings Audit Skill v1.0*
|
||||
*Last updated: 2025-02*
|
||||
39
custom-skills/00-our-settings-audit/desktop/skill.yaml
Normal file
39
custom-skills/00-our-settings-audit/desktop/skill.yaml
Normal file
@@ -0,0 +1,39 @@
|
||||
# OurDigital Settings Audit
|
||||
# Comprehensive error diagnosis and context optimization
|
||||
|
||||
name: our-settings-audit
|
||||
|
||||
description: |
|
||||
Diagnose all Claude Desktop errors and optimize context usage.
|
||||
Covers 8 error categories: context limits, output interruption,
|
||||
length/file errors, usage limits, server capacity, MCP connection,
|
||||
account issues, and output quality problems.
|
||||
|
||||
allowed-tools:
|
||||
- Read
|
||||
- Glob
|
||||
- Grep
|
||||
|
||||
license: Internal-use Only
|
||||
|
||||
triggers:
|
||||
- settings audit
|
||||
- settings check
|
||||
- audit settings
|
||||
- exceed response limit
|
||||
- response could not be generated
|
||||
- length limit
|
||||
- file too large
|
||||
- conversation limit
|
||||
- 5-hour limit
|
||||
- messages left
|
||||
- rate limit
|
||||
- capacity constraints
|
||||
- server error
|
||||
- MCP error
|
||||
- server connection failed
|
||||
- account disabled
|
||||
- login error
|
||||
- output cutoff
|
||||
- token error
|
||||
- gibberish output
|
||||
@@ -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
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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단계 워크플로우 스킬.
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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)
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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 메타데이터 생성
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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"
|
||||
}
|
||||
]
|
||||
}
|
||||
|
||||
@@ -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
|
||||
|
||||
|
||||
95
custom-skills/91-multi-agent-guide/commands/quick-setup.md
Normal file
95
custom-skills/91-multi-agent-guide/commands/quick-setup.md
Normal file
@@ -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 <file>`
|
||||
- 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.
|
||||
@@ -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
|
||||
|
||||
@@ -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 <noreply@anthropic.com>
|
||||
```
|
||||
|
||||
### 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*
|
||||
@@ -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**
|
||||
@@ -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 |
|
||||
|
||||
@@ -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`
|
||||
@@ -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 ...]
|
||||
@@ -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 ...]
|
||||
@@ -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 ...]
|
||||
@@ -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 ...]
|
||||
@@ -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 ...]
|
||||
@@ -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 ...]
|
||||
@@ -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 ...]
|
||||
@@ -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 ...]
|
||||
@@ -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 ...]
|
||||
@@ -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 ...]
|
||||
@@ -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.
|
||||
415
custom-skills/_ourdigital-shared/install.sh
Executable file
415
custom-skills/_ourdigital-shared/install.sh
Executable file
@@ -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
|
||||
158
custom-skills/_ourdigital-shared/scripts/export_for_claude_ai.py
Executable file
158
custom-skills/_ourdigital-shared/scripts/export_for_claude_ai.py
Executable file
@@ -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()
|
||||
284
custom-skills/_ourdigital-shared/scripts/validate_install.py
Executable file
284
custom-skills/_ourdigital-shared/scripts/validate_install.py
Executable file
@@ -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()
|
||||
@@ -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 |
|
||||
|
||||
Reference in New Issue
Block a user