cognitive-core 0.2.1 → 0.2.3

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

@@ -1,339 +0,0 @@
----
-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

@@ -1,326 +0,0 @@
-# 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: []
-  }
-};
-```