ChainGraph Skill Authoring Guide

This skill provides guidelines for creating and maintaining Claude Code skills for the ChainGraph monorepo.

Skill Tree Philosophy

Skills in ChainGraph form a composition graph, not a hierarchy. Multiple skills trigger simultaneously based on task context. Design skills to compose well together.

FOUNDATION          PACKAGE CONTEXT       TECHNOLOGY         FEATURES
     │                    │                   │                  │
     ▼                    ▼                   ▼                  ▼
chaingraph-concepts → frontend-architecture → effector-patterns → port-system
                   → executor-architecture → dbos-patterns     → subscription-sync
                   → types-architecture    → xyflow-patterns   → optimistic-updates

Naming Conventions

DO

• Use lowercase with hyphens: effector-patterns, port-system
• Use clear, self-explanatory names
• Group by conceptual area, not package prefix

DON'T

• No prefixes like pkg-, lib-, feat- (clutters the list)
• No abbreviations that aren't universally known
• No version numbers in names

Naming Categories

Directory Structure

.claude/skills/
├── {skill-name}/
│   ├── SKILL.md           # Required: Main skill content
│   ├── reference.md       # Optional: Detailed reference (if SKILL.md > 400 lines)
│   └── examples.md        # Optional: Code examples

Keep SKILL.md under 500 lines. Use supporting files for deep dives.

Description Writing (CRITICAL)

The description field determines when Claude triggers the skill. Write it strategically:

Structure

description: |
  {What this skill covers} - {key concepts}.
  Use when {trigger conditions}.
  {Additional context}.
  Triggers: {comma-separated keywords}

Example

description: |
  Effector state management patterns and CRITICAL anti-patterns.
  Use when writing Effector stores, events, effects, samples, or
  any reactive state code. Contains anti-patterns to avoid.
  Triggers: effector, store, createStore, createEvent, createEffect,
  sample, combine, domain, useUnit, $store

Description Best Practices

1. Include trigger keywords - Words users naturally say
2. Mention file paths - apps/chaingraph-frontend, packages/chaingraph-executor
3. Flag CRITICAL content - Use caps for must-know information
4. List related concepts - Helps semantic matching
5. Keep under 1024 chars - Claude Code limit

Skill Content Structure

Required Sections

# {Skill Title}

Brief overview (2-3 sentences).

## Key Concepts
Core concepts the agent must understand.

## Patterns
Code patterns to follow with examples.

## Anti-Patterns (if applicable)
What to AVOID with examples of wrong vs right.

## Key Files
| File | Purpose |
|------|---------|
| `path/to/file` | What it does |

## Quick Reference
Concise lookup table or checklist.

Optional Sections

• ## Examples - Detailed code examples
• ## Common Tasks - Step-by-step for frequent operations
• ## Troubleshooting - Common issues and solutions
• ## Related Skills - Links to related skills

Skill Composition Principles

1. Single Responsibility

Each skill covers ONE coherent knowledge domain. Don't mix unrelated concepts.

2. Composable Knowledge

Skills should work together. A frontend port bug might trigger:

• chaingraph-concepts (what ports ARE)
• frontend-architecture (where the code IS)
• effector-patterns (HOW stores work)
• port-system (port-SPECIFIC knowledge)

3. Layered Depth

• Foundation skills: Brief, always relevant
• Package skills: Architecture overview
• Technology skills: Deep patterns, anti-patterns
• Feature skills: Specific subsystem knowledge

4. No Duplication

Don't repeat information across skills. Reference other skills instead:

For Effector patterns, see the `effector-patterns` skill.

When to Create a New Skill

Create a new skill when:

• A knowledge domain is large enough (>100 lines of guidance)
• Agents frequently need this knowledge for specific tasks
• The knowledge is reusable across multiple task types
• Existing skills don't cover this area well

DON'T create a skill for:

• One-off information (put in CLAUDE.md instead)
• Package-specific details that fit in existing package skill
• Information that changes frequently (becomes stale)

Skill Tree Organization

Current Categories

Adding New Categories

Only add a category if:

• 3+ skills would belong to it
• It represents a distinct knowledge domain
• Existing categories don't fit

Quality Checklist

Before committing a new skill:

• Name follows conventions (lowercase, hyphens, no prefixes)
• Description under 1024 chars with trigger keywords
• SKILL.md under 500 lines
• Has Key Concepts section
• Has Patterns section with code examples
• Anti-patterns documented if applicable
• Key Files table included
• No duplication with existing skills
• Tested: would this trigger for the intended tasks?

Maintaining Consistency

When Updating Skills

• Keep the same structure
• Update examples to match current codebase
• Add new patterns discovered during development
• Remove deprecated patterns

Version Tracking

Skills don't have versions. Keep them evergreen by:

• Updating when architecture changes
• Removing obsolete information
• Adding new patterns as they emerge

Example: Creating a New Skill

Task: Create skill for "node-creation" (creating new ChainGraph nodes)

1. Check if needed: Is this knowledge large enough? Yes, 100+ lines.
2. Choose name: node-creation (clear, follows pattern)
3. Write description:

   description: |
     Creating new ChainGraph nodes with decorators. Use when
     implementing new node types in packages/chaingraph-nodes.
     Covers @Node, @Input, @Output, port decorators, execute().
     Triggers: create node, new node, @Node, BaseNode, execute
   

4. Structure content: Key Concepts → Patterns → Anti-Patterns → Key Files
5. Review checklist: All items checked
6. Test mentally: "Create an AI node" - would this trigger? Yes.