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:
   yaml

   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.