claude-code-swarm 0.3.3 → 0.3.5

package/references/skill-tree/skills/skill-writer/SKILL.md

@@ -0,0 +1,339 @@
+---
+name: skill-writer
+description: Comprehensive guide for creating high-quality skills for Claude. Use when building a new skill, writing a SKILL.md, designing skill frontmatter, planning skill structure, debugging trigger issues, or reviewing an existing skill for improvements. Covers standalone skills, MCP-enhanced skills, and skill-tree programmatic skills.
+metadata:
+  author: skill-tree
+  version: 1.0.0
+  category: meta
+  tags: [skill-creation, authoring, best-practices]
+---
+
+# Skill Writer
+
+Create well-structured, effective skills that trigger reliably, follow Anthropic's progressive disclosure model, and produce consistent results.
+
+## Core Concepts
+
+A skill is a folder containing instructions that teach Claude to handle specific tasks or workflows. Skills eliminate the need to re-explain preferences, processes, and domain expertise in every conversation.
+
+### Progressive Disclosure (Three Levels)
+
+1. **YAML frontmatter** (always in system prompt): Enough for Claude to decide *when* to load the skill
+2. **SKILL.md body** (loaded when relevant): Full instructions and guidance
+3. **Linked files** (loaded as needed): References, scripts, assets in subdirectories
+
+This minimizes token usage while maintaining specialized expertise.
+
+### Design Principles
+
+- **Composability**: Skills run alongside other skills. Never assume exclusive context.
+- **Portability**: Skills work across Claude.ai, Claude Code, and API without modification (given environment dependencies are met).
+- **Progressive complexity**: Start simple, add depth through references.
+
+## Instructions
+
+### Step 1: Define Use Cases
+
+Before writing anything, identify 2-3 concrete use cases.
+
+For each use case, document:
+- **Trigger**: What the user says or does
+- **Steps**: The multi-step workflow required
+- **Result**: The concrete outcome produced
+
+Determine which category the skill falls into:
+
+| Category | Purpose | Example |
+|----------|---------|---------|
+| Document/Asset Creation | Consistent, high-quality output | frontend-design, docx, pptx |
+| Workflow Automation | Multi-step processes with methodology | skill-creator, sprint-planner |
+| MCP Enhancement | Workflow guidance for MCP tool access | sentry-code-review |
+
+### Step 2: Create the Folder Structure
+
+```
+your-skill-name/
+├── SKILL.md              # Required - main instruction file
+├── scripts/              # Optional - executable code (Python, Bash)
+├── references/           # Optional - detailed docs loaded as needed
+└── assets/               # Optional - templates, fonts, icons
+```
+
+Critical naming rules:
+- Folder: **kebab-case only** (`my-skill-name`)
+- File: **exactly** `SKILL.md` (case-sensitive, no variations)
+- No `README.md` inside the skill folder
+- No spaces, underscores, or capitals in folder name
+
+### Step 3: Write the YAML Frontmatter
+
+The frontmatter is *the most important part* - it determines whether Claude loads the skill.
+
+Minimal required format:
+
+```yaml
+---
+name: your-skill-name
+description: What it does. Use when user asks to [specific phrases].
+---
+```
+
+#### The `name` Field
+
+- kebab-case only, no spaces or capitals
+- Must match the folder name
+- Never use "claude" or "anthropic" as a prefix (reserved)
+
+#### The `description` Field (Critical)
+
+Structure: `[What it does] + [When to use it] + [Key capabilities]`
+
+Must include BOTH:
+1. What the skill does
+2. When to use it (trigger conditions with specific phrases)
+
+Constraints:
+- Under 1024 characters
+- No XML angle brackets (`<` or `>`)
+- Include specific tasks/phrases users would actually say
+- Mention relevant file types if applicable
+
+**Good descriptions:**
+
+```yaml
+# Specific + actionable + trigger phrases
+description: Analyzes Figma design files and generates developer
+  handoff documentation. Use when user uploads .fig files, asks for
+  "design specs", "component documentation", or "design-to-code handoff".
+
+# Clear value proposition + triggers
+description: End-to-end customer onboarding workflow for PayFlow.
+  Handles account creation, payment setup, and subscription management.
+  Use when user says "onboard new customer", "set up subscription",
+  or "create PayFlow account".
+```
+
+**Bad descriptions:**
+
+```yaml
+# Too vague - won't trigger
+description: Helps with projects.
+
+# Missing triggers - Claude won't know when to load
+description: Creates sophisticated multi-page documentation systems.
+
+# Too technical, no user-facing triggers
+description: Implements the Project entity model with hierarchical
+  relationships.
+```
+
+#### Optional Fields
+
+```yaml
+license: MIT                              # For open-source skills
+compatibility: Requires Python 3.10+      # 1-500 chars, environment needs
+allowed-tools: "Bash(python:*) WebFetch"  # Restrict tool access
+metadata:                                 # Custom key-value pairs
+  author: Your Name
+  version: 1.0.0
+  mcp-server: server-name
+  tags: [automation, productivity]
+```
+
+#### Security Restrictions
+
+Forbidden in frontmatter:
+- XML angle brackets (`<` `>`) - prevents prompt injection
+- Skills named with "claude" or "anthropic" prefix
+
+### Step 4: Write the Instructions Body
+
+After the frontmatter, write instructions in Markdown.
+
+#### Recommended Structure
+
+```markdown
+# Skill Name
+
+## Instructions
+
+### Step 1: [First Major Step]
+Clear explanation of what happens.
+
+Example:
+\`\`\`bash
+python scripts/fetch_data.py --project-id PROJECT_ID
+\`\`\`
+Expected output: [describe what success looks like]
+
+(Add more steps as needed)
+
+## Examples
+
+### Example 1: [Common Scenario]
+User says: "Set up a new marketing campaign"
+Actions:
+1. Fetch existing campaigns via MCP
+2. Create new campaign with provided parameters
+Result: Campaign created with confirmation link
+
+## Troubleshooting
+
+### Error: [Common error message]
+Cause: [Why it happens]
+Solution: [How to fix]
+```
+
+#### Writing Style Rules
+
+- **Imperative/infinitive form**: "To accomplish X, execute Y" or "Load this skill when Z"
+- **Avoid second person**: Do NOT write "You should..." or "If you need..."
+- **Be specific and actionable**: Include exact commands, parameters, expected outputs
+- **Use bullet points and numbered lists** for scanability
+- **Put critical instructions at the top** using `## Important` or `## Critical` headers
+
+#### Error Handling
+
+Always include error handling:
+
+```markdown
+## Common Issues
+
+### MCP Connection Failed
+If "Connection refused" appears:
+1. Verify MCP server is running: Check Settings > Extensions
+2. Confirm API key is valid
+3. Try reconnecting: Settings > Extensions > [Service] > Reconnect
+```
+
+#### Progressive Disclosure in Practice
+
+Keep SKILL.md focused on core instructions (under 5,000 words). Move detailed documentation to `references/`:
+
+```markdown
+Before writing queries, consult `references/api-patterns.md` for:
+- Rate limiting guidance
+- Pagination patterns
+- Error codes and handling
+```
+
+#### Combating Instruction Drift
+
+For critical validations, prefer bundling a script over relying on language instructions:
+
+```markdown
+CRITICAL: Before calling create_project, verify:
+- Project name is non-empty
+- At least one team member assigned
+- Start date is not in the past
+```
+
+For deterministic checks, use `scripts/validate.py` instead of prose instructions.
+
+### Step 5: Choose an Implementation Pattern
+
+Select the pattern that fits the skill's workflow. See `references/patterns.md` for detailed examples.
+
+| Pattern | Use When |
+|---------|----------|
+| Sequential Workflow | Multi-step processes in specific order |
+| Multi-MCP Coordination | Workflows spanning multiple services |
+| Iterative Refinement | Output quality improves with iteration |
+| Context-Aware Selection | Same outcome, different tools per context |
+| Domain Intelligence | Specialized knowledge beyond tool access |
+
+### Step 6: Test the Skill
+
+#### Triggering Tests
+Run 10-20 test queries. Target: skill triggers on 90%+ of relevant queries.
+
+Should trigger:
+- Obvious task descriptions
+- Paraphrased requests
+- Domain-specific terminology
+
+Should NOT trigger:
+- Unrelated topics
+- Queries better served by other skills
+
+Debug triggering: Ask Claude "When would you use the [skill name] skill?" and compare against expected triggers.
+
+#### Functional Tests
+- Valid outputs generated
+- API/MCP calls succeed
+- Error handling works
+- Edge cases covered
+
+#### Performance Comparison
+Compare with and without the skill:
+- Number of back-and-forth messages
+- Failed API calls
+- Total tokens consumed
+- User corrections needed
+
+### Step 7: Iterate
+
+Skills are living documents. Watch for:
+
+**Undertriggering** (skill doesn't load when it should):
+- Add more trigger phrases to the description
+- Include technical keywords and synonyms
+
+**Overtriggering** (skill loads for unrelated queries):
+- Add negative triggers: "Do NOT use for simple data exploration"
+- Be more specific about scope
+- Clarify boundaries with other skills
+
+**Execution issues** (inconsistent results):
+- Make instructions more specific
+- Add error handling
+- Move verbose content to references
+
+## Skill-Tree Programmatic Skills
+
+When creating skills for the skill-tree library (as opposed to SKILL.md files), structure them with these fields:
+
+```typescript
+{
+  id: "kebab-case-id",
+  name: "Human-Readable Name",
+  version: "1.0.0",
+  description: "Short description for semantic matching (1-2 sentences)",
+  problem: "What problem this skill solves",
+  triggerConditions: [
+    { type: "error", value: "Cannot find module", description: "ES module import failure" },
+    { type: "keyword", value: "typescript, import", description: "TypeScript imports" },
+    { type: "pattern", value: "\\.(ts|tsx)$", description: "TypeScript files" }
+  ],
+  solution: "Step-by-step solution in imperative form",
+  verification: "How to verify the skill worked",
+  examples: [
+    { scenario: "Description", before: "Before state", after: "After state" }
+  ],
+  tags: ["typescript", "modules"],
+  status: "active"
+}
+```
+
+Trigger condition types:
+- `error`: Error message patterns (regex)
+- `keyword`: Comma-separated keywords
+- `pattern`: Regex for file paths or content
+- `context`: Contextual description
+- `custom`: Freeform condition
+
+## Quality Checklist
+
+Before shipping, verify against `references/quality-checklist.md`.
+
+Quick validation:
+- [ ] Folder is kebab-case, SKILL.md exists (exact spelling)
+- [ ] Frontmatter has `---` delimiters, `name` and `description` fields
+- [ ] Description includes WHAT it does and WHEN to use it
+- [ ] No XML tags anywhere in frontmatter
+- [ ] Instructions are specific and actionable (not vague)
+- [ ] Error handling included for common failure modes
+- [ ] Examples provided for primary use cases
+- [ ] SKILL.md is under 5,000 words
+- [ ] Detailed docs moved to references/
+- [ ] Tested: triggers correctly, doesn't overtrigger, produces correct output

package/references/skill-tree/skills/skill-writer/references/examples.md

@@ -0,0 +1,326 @@
+# Skill Examples
+
+Complete examples demonstrating different skill categories and patterns.
+
+---
+
+## Example 1: Document Creation Skill (Category 1)
+
+A standalone skill for generating API documentation.
+
+```
+api-docs-generator/
+├── SKILL.md
+├── references/
+│   └── style-guide.md
+└── assets/
+    └── doc-template.md
+```
+
+### SKILL.md
+
+```yaml
+---
+name: api-docs-generator
+description: >-
+  Generates consistent API documentation from code and OpenAPI specs.
+  Use when user asks to "document this API", "generate API docs",
+  "create endpoint documentation", or uploads .yaml/.json OpenAPI files.
+metadata:
+  author: api-team
+  version: 1.2.0
+  tags: [documentation, api, openapi]
+---
+```
+
+```markdown
+# API Documentation Generator
+
+## Instructions
+
+### Step 1: Identify API Source
+Determine the documentation source:
+- OpenAPI/Swagger spec file (.yaml or .json)
+- Source code with route definitions
+- Existing partial documentation to extend
+
+### Step 2: Extract Endpoints
+For each endpoint, capture:
+- HTTP method and path
+- Request parameters (path, query, body)
+- Response schema and status codes
+- Authentication requirements
+
+### Step 3: Generate Documentation
+Apply the style guide from `references/style-guide.md`.
+
+For each endpoint, produce:
+1. One-line description
+2. Full URL with base path
+3. Request example with curl
+4. Response example with JSON
+5. Error responses table
+
+### Step 4: Validate
+- All endpoints from source are documented
+- Examples are syntactically valid
+- Cross-references between related endpoints exist
+
+## Examples
+
+### Example: REST API with OpenAPI spec
+User says: "Generate docs for this API"
+Given: openapi.yaml with 5 endpoints
+Result: Markdown documentation with curl examples for each endpoint
+
+## Troubleshooting
+
+### Missing endpoints
+Cause: Spec uses $ref to external files
+Solution: Resolve all $ref references before processing
+```
+
+---
+
+## Example 2: Workflow Automation Skill (Category 2)
+
+A skill for standardized code review workflows.
+
+```
+code-review/
+├── SKILL.md
+├── scripts/
+│   └── check-coverage.sh
+└── references/
+    └── review-standards.md
+```
+
+### SKILL.md
+
+```yaml
+---
+name: code-review
+description: >-
+  Conducts structured code reviews with consistent methodology.
+  Use when user asks to "review this PR", "review my code",
+  "check this for issues", or "do a code review". Covers security,
+  performance, maintainability, and test coverage.
+metadata:
+  author: engineering
+  version: 2.0.0
+  tags: [code-review, quality, security]
+---
+```
+
+```markdown
+# Code Review
+
+## Instructions
+
+### Step 1: Understand the Change
+1. Read the PR description or user's explanation of the change
+2. Identify the affected files and their roles
+3. Determine the change category: feature, bugfix, refactor, or config
+
+### Step 2: Security Review
+Check for OWASP Top 10 vulnerabilities:
+- SQL injection in database queries
+- XSS in user-facing output
+- Authentication/authorization gaps
+- Secrets or credentials in code
+- Input validation at system boundaries
+
+### Step 3: Code Quality Review
+Consult `references/review-standards.md` for project-specific standards.
+
+Check:
+- Functions under 50 lines
+- Clear naming conventions
+- Error handling for external calls
+- No dead code or commented-out blocks
+- DRY violations (3+ repetitions)
+
+### Step 4: Test Coverage
+Run `scripts/check-coverage.sh` if available.
+
+Verify:
+- New code has corresponding tests
+- Edge cases are covered
+- Tests are meaningful (not just coverage padding)
+
+### Step 5: Produce Review Summary
+Structure the review as:
+1. **Summary**: One paragraph on overall assessment
+2. **Critical Issues**: Must fix before merge (security, correctness)
+3. **Suggestions**: Improvements that can be addressed later
+4. **Positive Notes**: What was done well
+
+## Examples
+
+### Example: Feature PR with 3 files changed
+User says: "Review this PR"
+Actions:
+1. Read diff for all 3 files
+2. Check for security issues in new endpoint
+3. Verify test coverage for new functionality
+4. Flag missing input validation
+Result: Structured review with 1 critical issue and 2 suggestions
+```
+
+---
+
+## Example 3: MCP Enhancement Skill (Category 3)
+
+A skill that enhances a project management MCP with workflow expertise.
+
+```
+linear-sprint-planner/
+├── SKILL.md
+└── references/
+    └── velocity-formulas.md
+```
+
+### SKILL.md
+
+```yaml
+---
+name: linear-sprint-planner
+description: >-
+  Plans and creates sprints in Linear with best practices for agile
+  teams. Use when user says "plan this sprint", "create sprint tasks",
+  "set up next sprint", or "help me with sprint planning". Requires
+  Linear MCP server connection.
+compatibility: Requires Linear MCP server
+metadata:
+  author: agile-team
+  version: 1.0.0
+  mcp-server: linear
+  tags: [linear, sprint, agile, project-management]
+---
+```
+
+```markdown
+# Linear Sprint Planner
+
+## Instructions
+
+### Step 1: Gather Sprint Context
+Call Linear MCP to fetch:
+1. Current project status: `linear_get_projects`
+2. Backlog items: `linear_list_issues` with status "Backlog"
+3. Team members: `linear_get_team_members`
+4. Previous sprint velocity (see `references/velocity-formulas.md`)
+
+### Step 2: Analyze Capacity
+Calculate available capacity:
+- Team members x working days x focus factor (0.7)
+- Subtract known PTO or meetings
+- Compare against historical velocity
+
+### Step 3: Prioritize and Select Items
+From the backlog, recommend items for the sprint:
+1. Priority items first (P0, P1)
+2. Dependencies resolved (blocked items excluded)
+3. Total story points within capacity
+4. Mix of feature work and tech debt (80/20 suggested)
+
+Present the recommended sprint plan to the user for approval.
+
+### Step 4: Create Sprint in Linear
+After user approval:
+1. Create sprint: `linear_create_cycle` with start/end dates
+2. Move selected issues: `linear_update_issue` for each item
+3. Assign owners based on expertise and load balancing
+4. Add labels: `linear_add_label` for sprint tracking
+
+### Step 5: Generate Sprint Summary
+Create a summary with:
+- Sprint goal (one sentence)
+- Total story points committed
+- Team member assignments
+- Key risks or dependencies
+- Definition of done
+
+## Troubleshooting
+
+### Linear MCP not connected
+If "Connection refused" or tool calls fail:
+1. Verify Linear MCP is connected: Settings > Extensions
+2. Check API key permissions (needs read/write)
+3. Test independently: "Use Linear MCP to list my projects"
+
+### No backlog items found
+Cause: Filter too restrictive or wrong project selected
+Solution: List all projects first, confirm the correct one
+```
+
+---
+
+## Example 4: Skill-Tree Programmatic Skill
+
+For the skill-tree library, skills are structured as TypeScript objects:
+
+```typescript
+const typescriptImportFix: Skill = {
+  id: "typescript-import-fix",
+  name: "TypeScript ES Module Import Fix",
+  version: "1.0.0",
+  description: "Fix TypeScript ES module import errors by adding .js extensions",
+
+  problem: "When using ES modules with TypeScript, relative imports fail without explicit .js extensions. The TypeScript compiler does not add extensions during compilation, causing 'Cannot find module' errors at runtime.",
+
+  triggerConditions: [
+    {
+      type: "error",
+      value: "Cannot find module",
+      description: "Node.js module resolution failure"
+    },
+    {
+      type: "error",
+      value: "ERR_MODULE_NOT_FOUND",
+      description: "ES module not found error"
+    },
+    {
+      type: "keyword",
+      value: "typescript, import, esm, module",
+      description: "TypeScript module-related discussion"
+    },
+    {
+      type: "pattern",
+      value: "from ['\"]\\./.*['\"]",
+      description: "Relative import without .js extension"
+    }
+  ],
+
+  solution: `1. Identify all relative imports in TypeScript files
+2. Add .js extension to each relative import path:
+   - import { foo } from './bar'  →  import { foo } from './bar.js'
+   - import { baz } from '../utils'  →  import { baz } from '../utils.js'
+3. Ensure tsconfig.json has "module": "ESNext" or "Node16"
+4. Ensure package.json has "type": "module"
+5. Rebuild the project: npx tsc --noEmit to verify`,
+
+  verification: "Run the application. All imports resolve without 'Cannot find module' errors. TypeScript compilation succeeds with no module-related diagnostics.",
+
+  examples: [
+    {
+      scenario: "Fixing imports in a utility file",
+      before: `import { helper } from './utils'\nimport { Config } from '../types'`,
+      after: `import { helper } from './utils.js'\nimport { Config } from '../types.js'`
+    }
+  ],
+
+  notes: "This only applies to relative imports. Package imports (from 'lodash') do not need extensions. Index files should use './dir/index.js' explicitly.",
+
+  author: "skill-tree",
+  tags: ["typescript", "esm", "modules", "imports"],
+  status: "active",
+  createdAt: new Date(),
+  updatedAt: new Date(),
+  metrics: {
+    usageCount: 0,
+    successRate: 0,
+    feedbackScores: []
+  }
+};
+```