How Skills Work

Overview

Fluxwing skills are specialized workflows that enable Claude Code to create, manage, and compose UI components using natural language. Each skill is a self-contained package with:

SKILL.md — Instructions and workflow logic
templates/ — Pre-built component examples (read-only)
schemas/ — JSON Schema validation rules
docs/ — Detailed reference documentation

Skills Location:
Plugin installation         # Managed by Claude Code
  └── fluxwing-component-creator/
  └── fluxwing-library-browser/
  └── fluxwing-component-expander/
  └── fluxwing-screen-scaffolder/
  └── fluxwing-component-viewer/
  └── fluxwing-screenshot-importer/

Your Workspace:
./fluxwing/                 # All outputs go here
  ├── components/           # Your components
  ├── screens/              # Complete screens
  └── library/              # Customized templates

Activation

Skills activate automatically when Claude Code detects matching natural language triggers. Each skill has a description that helps Claude recognize when to use it.

Trigger Examples

Your Request	Skill Activated
"Create a submit button"	fluxwing-component-creator
"Show me all components"	fluxwing-library-browser
"Add hover state to my button"	fluxwing-component-expander
"Build a login screen"	fluxwing-screen-scaffolder
"View the primary-button component"	fluxwing-component-viewer
"Import this screenshot"	fluxwing-screenshot-importer

How Matching Works

Claude Code analyzes your natural language request and:

Extracts intent keywords (create, show, add, build, view, import)
Identifies target objects (button, component, screen, state)
Matches against skill descriptions
Activates the most relevant skill
Loads skill-specific instructions from SKILL.md

Skill Lifecycle

Every skill follows a consistent workflow from activation to completion:

┌─────────────────────────────────────────────────────────┐
│ Phase 1: TRIGGER                                        │
├─────────────────────────────────────────────────────────┤
│ • User describes desired component/action               │
│ • Claude Code detects matching skill                    │
│ • Skill's SKILL.md instructions load                    │
└─────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────┐
│ Phase 2: CONTEXT GATHERING                              │
├─────────────────────────────────────────────────────────┤
│ • Load required documentation modules                   │
│ • Read relevant schemas                                 │
│ • Check existing components in workspace                │
│ • Search bundled templates for reference                │
└─────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────┐
│ Phase 3: AGENT INVOCATION (if needed)                   │
├─────────────────────────────────────────────────────────┤
│ • Spawn general-purpose agent                           │
│ • Pass skill-specific instructions                      │
│ • Agent performs file operations                        │
│ • Return results to skill                               │
└─────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────┐
│ Phase 4: FILE OPERATIONS                                │
├─────────────────────────────────────────────────────────┤
│ • Create/edit .uxm file (JSON metadata)                 │
│ • Create/edit .md file (ASCII template)                 │
│ • For screens: create .rendered.md (example with data)  │
│ • Write to ./fluxwing/ workspace                        │
└─────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────┐
│ Phase 5: VALIDATION                                     │
├─────────────────────────────────────────────────────────┤
│ • Validate .uxm against JSON Schema                     │
│ • Check variable consistency (.uxm ↔ .md)               │
│ • Verify ASCII dimensions                               │
│ • Ensure required fields present                        │
└─────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────┐
│ Phase 6: COMPLETION                                     │
├─────────────────────────────────────────────────────────┤
│ • Report results to user                                │
│ • Show file paths created/modified                      │
│ • Suggest next steps or related actions                 │
└─────────────────────────────────────────────────────────┘

Example: Creating a Button

User: "Create a submit button"

Phase 1 — Trigger:
  ✓ fluxwing-component-creator skill activated
  ✓ SKILL.md instructions loaded

Phase 2 — Context:
  ✓ Loaded uxm-component.schema.json
  ✓ Loaded 03-component-creation.md documentation
  ✓ Found 11 bundled templates for reference
  ✓ Checked ./fluxwing/components/ (empty)

Phase 3 — Agent:
  ✓ Spawned general-purpose agent with component creation instructions
  ✓ Agent analyzed schema requirements
  ✓ Agent selected "button" type, generated ID "submit-button"

Phase 4 — Files:
  ✓ Created ./fluxwing/components/submit-button.uxm
  ✓ Created ./fluxwing/components/submit-button.md

Phase 5 — Validation:
  ✓ JSON Schema validation passed
  ✓ Variable consistency verified (text prop matches {{text}} in .md)
  ✓ ASCII dimensions within limits (20×3)

Phase 6 — Complete:
  ✓ Reported success to user
  ✓ Showed file paths
  ✓ Suggested: "Try adding hover state with component-expander"

Agent System

Skills use Claude Code's built-in agent system to perform complex operations. Agents are spawned with specialized instructions and have access to specific tools.

Agent Types Used

Agent Type	Used By Skills	Purpose
`general-purpose`	component-creator, screen-scaffolder, screenshot-importer	Create/modify components and screens
Direct tool use	library-browser, component-viewer	Read-only operations (Glob, Grep, Read)
Direct tool use	component-expander	Edit existing files (Edit tool)

Why Agents?

Context isolation — Agents work with focused instructions, not the entire conversation
Parallel execution — Multiple agents can run simultaneously
Specialized tools — Agents have access to specific tool subsets
Error recovery — Agent failures don't crash the main conversation

Skill Invokes Agent:
┌──────────────────────────────────────────────────────────┐
│ Task({                                                   │
│   subagent_type: "general-purpose",                     │
│   description: "Create uxscii component",               │
│   prompt: `You are a uxscii component designer...       │
│                                                          │
│   Component requirements:                               │
│   - Name: submit-button                                 │
│   - Type: button                                        │
│   - Load schema from {SKILL_ROOT}/schemas/...           │
│   - Create .uxm file (valid JSON)                       │
│   - Create .md file (ASCII template)                    │
│   - Save to ./fluxwing/components/                      │
│                                                          │
│   Follow uxscii standard strictly.`                     │
│ })                                                       │
└──────────────────────────────────────────────────────────┘

Agent Returns:
┌──────────────────────────────────────────────────────────┐
│ {                                                        │
│   success: true,                                        │
│   filesCreated: [                                       │
│     "./fluxwing/components/submit-button.uxm",         │
│     "./fluxwing/components/submit-button.md"           │
│   ],                                                    │
│   validationPassed: true                               │
│ }                                                        │
└──────────────────────────────────────────────────────────┘

File Operations

Skills follow strict rules about where to read from and where to write to. This ensures portability and prevents accidental modification of bundled resources.

Read Operations (Templates & Schemas)

Bundled Templates (READ-ONLY):
skills/fluxwing-component-creator/templates/
  ├── primary-button.uxm          # Reference implementation
  ├── primary-button.md
  ├── text-input.uxm              # 11 component types
  ├── text-input.md
  └── ...

Usage:
✓ Load as reference/inspiration
✓ Copy patterns and structure
✓ Use as derivation source
✗ NEVER modify these files
✗ NEVER write to skill directories

Write Operations (User Workspace)

Project Workspace (READ-WRITE):
./fluxwing/
  ├── components/                # User/agent-created components
  │   ├── my-button.uxm
  │   ├── my-button.md
  │   ├── email-input.uxm
  │   └── email-input.md
  ├── screens/                   # Complete screen compositions
  │   ├── login.uxm
  │   ├── login.md
  │   └── login.rendered.md      # With real data
  └── library/                   # Customized bundled templates
      ├── custom-button.uxm
      └── custom-button.md

Usage:
✓ Create new components
✓ Modify existing components
✓ Delete outdated files
✓ Version control with git
✓ Share across team

Inventory Check Order

When searching for components, skills follow this priority:

User components → ./fluxwing/components/*.uxm
User library → ./fluxwing/library/*.uxm
Bundled templates → skills/*/templates/*.uxm

This ensures user-created components take precedence over defaults.

Validation

All components must pass validation before being considered complete. Validation happens automatically during the skill lifecycle.

JSON Schema Validation

The .uxm file is validated against uxm-component.schema.json (JSON Schema Draft-07):

Required Fields:
  ✓ id (pattern: ^[a-z0-9]+(?:-[a-z0-9]+)*$, length: 2-64)
  ✓ type (enum: button, input, checkbox, ...)
  ✓ version (pattern: ^\d+\.\d+\.\d+$)
  ✓ metadata.name (string, 1-100 chars)
  ✓ metadata.description (string, 1-500 chars)
  ✓ ascii.templateFile (string, ends with .md)
  ✓ ascii.width (number, 1-120)
  ✓ ascii.height (number, 1-50)

Optional Fields:
  • metadata.created (ISO 8601 timestamp)
  • metadata.author (string)
  • metadata.tags (array of strings)
  • props (object with component-specific properties)
  • behavior (interactions, states)
  • layout (positioning, spacing)
  • extends (parent component ID)
  • slots (named content areas)

Variable Consistency Check

All {{variables}} in the .md template must be declared in the .uxm file's props object:

✓ Valid Example:

// submit-button.uxm
{
  "props": {
    "text": "Submit"
  }
}

// submit-button.md
┌────────────────┐
│   {{text}}     │
└────────────────┘

✗ Invalid Example:

// submit-button.uxm
{
  "props": {
    "label": "Submit"  // Mismatch!
  }
}

// submit-button.md
┌────────────────┐
│   {{text}}     │  // ← Variable not defined in .uxm
└────────────────┘

ASCII Dimension Limits

Width: 1-120 characters (reasonable terminal width)
Height: 1-50 lines (single viewport without scrolling)
Rationale: Ensures components render well in standard terminal environments

Data Flow

Understanding how data moves through the skill system helps debug issues and optimize workflows.

User Input → Skill → Agent → Files → Validation → Output
     ↓           ↓       ↓       ↓         ↓           ↓
"Create     component  spawns  creates  validates   reports
 button"    creator    agent   .uxm+.md  against    success
            skill              files     schema     + paths

┌────────────────────────────────────────────────────────────┐
│                    DETAILED DATA FLOW                      │
├────────────────────────────────────────────────────────────┤
│                                                            │
│  1. User Request (Natural Language)                        │
│     ↓                                                      │
│  2. Claude Code Intent Analysis                            │
│     ↓                                                      │
│  3. Skill Activation (SKILL.md loaded)                     │
│     ↓                                                      │
│  4. Context Loading                                        │
│     • JSON Schema from {SKILL_ROOT}/schemas/               │
│     • Documentation from {SKILL_ROOT}/docs/                │
│     • Templates from {SKILL_ROOT}/templates/               │
│     ↓                                                      │
│  5. Agent Invocation (if needed)                           │
│     • Task tool with general-purpose agent                 │
│     • Embedded instructions from skill                     │
│     ↓                                                      │
│  6. File Creation/Modification                             │
│     • Read from bundled templates (reference)              │
│     • Write to ./fluxwing/ (user workspace)                │
│     ↓                                                      │
│  7. Validation Pipeline                                    │
│     • JSON Schema validation (.uxm)                        │
│     • Variable consistency check (.uxm ↔ .md)              │
│     • ASCII dimension check                                │
│     ↓                                                      │
│  8. Result Reporting                                       │
│     • Success/failure status                               │
│     • File paths created/modified                          │
│     • Validation errors (if any)                           │
│     • Suggested next steps                                 │
│                                                            │
└────────────────────────────────────────────────────────────┘

Data Sources

Source	Type	Purpose
User input	Natural language	Triggers skill, provides requirements
SKILL.md	Markdown + YAML	Workflow instructions, tool permissions
schemas/*.json	JSON Schema	Validation rules
templates/*.uxm	JSON	Reference implementations
templates/*.md	ASCII + variables	Visual patterns
docs/*.md	Markdown	Detailed instructions

Error Handling

Skills handle errors gracefully and provide actionable feedback to help you fix issues quickly.

Common Errors

1. Schema Validation Failure

Error:
Component validation failed: Required property 'metadata.description' missing

Cause:
.uxm file missing required field

Fix:
Add "description" field to metadata:
{
  "metadata": {
    "name": "My Button",
    "description": "Primary action button"  ← Add this
  }
}

2. Variable Mismatch

Error:
Template variable {{label}} not defined in props

Cause:
.md template uses variable not declared in .uxm

Fix:
Either:
  • Add "label" to props in .uxm, OR
  • Change {{label}} to existing prop name in .md

3. Invalid ID Format

Error:
Component ID "Submit_Button" doesn't match pattern ^[a-z0-9]+(?:-[a-z0-9]+)*$

Cause:
ID contains uppercase or underscores

Fix:
Use lowercase with hyphens: "submit-button"

4. ASCII Dimensions Exceeded

Error:
ASCII width (125) exceeds maximum (120)

Cause:
.md template too wide for standard terminals

Fix:
Reduce template width to 120 characters or less

Error Recovery

When errors occur, skills typically:

Report — Show clear error message with context
Suggest — Provide actionable fix recommendations
Preserve — Keep partial work (don't delete files)
Retry — Allow immediate retry with corrections

Best Practices

For Component Creation

Start with bundled templates as reference
Use descriptive IDs (submit-button, email-input, user-card)
Keep ASCII dimensions reasonable (<80 width for portability)
Define all props in .uxm before using in .md
Add accessibility fields (aria role, labels, focusable)
Use semantic versioning (1.0.0, 1.1.0, 2.0.0)

For Screen Composition

Build atomic components first (button, input)
Then compose into molecules (form-field = label + input)
Finally assemble screens from molecules
Always create .rendered.md for screens (shows real intent)
Use consistent spacing and alignment
Test rendering at multiple terminal widths

For Workspace Organization

Keep related components together in components/
Use screens/ only for complete page layouts
Customize bundled templates in library/ (not in place)
Version control ./fluxwing/ with git
Add .gitignore for generated files (if any)

For Performance

Load documentation modules only when needed
Reuse existing components instead of recreating
Use derivation (extends) instead of duplication
Spawn agents in parallel for independent tasks
Cache validation results when processing multiple files

Quick Workflow Checklist

Before Creating a Component:
  □ Check if similar component exists (library-browser)
  □ Review bundled templates for reference
  □ Plan props and states upfront

During Creation:
  □ Use descriptive, lowercase-hyphenated ID
  □ Add complete metadata (name, description, tags)
  □ Define all props before using in template
  □ Keep ASCII dimensions terminal-friendly
  □ Add accessibility fields

After Creation:
  □ Verify files created in ./fluxwing/
  □ Check validation passed (no errors)
  □ Test rendering in terminal
  □ Consider adding states (hover, focus, disabled)
  □ Version control with git