Quick Reference (30 seconds)

Core Principle: Clear separation between Agents (orchestrators) and Skills (capabilities).

Component Location Contains

Agents .claude/agents/

workflows/ (TOON + MD steps)

Skills .claude/skills/

scripts/ (UV Python) OR modules/ (single-file MDs)

Decision Tree:

Need external Python packages? → UV Script (.py) Need system commands? → UV Script (.py) Reference/documentation? → Single-File MD (.md) Simple data/rules? → Single-File MD (.md)

Naming (Mandatory Prefixes):

• Scripts: {skill}_{action}.py (underscore)

• Modules: {category}-{topic}.md (hyphen)

Architecture Overview

Agents = Orchestrators with Workflows

.claude/agents/{category}/{agent-name}/ ├── {agent-name}.md # Agent definition └── workflows/ # Agent-owned workflows └── {workflow-name}/ ├── WORKFLOW.toon # Structure (TOON tabular) ├── instructions.md # Overall guidance ├── checklist.md # Validation (tier-2+) └── steps/ └── step-NN-{action}.md

Skills = Capabilities with Scripts OR Modules

.claude/skills/{skill-name}/ ├── SKILL.md # Main entry (REQUIRED) ├── scripts/ # For complex automation (OPTIONAL) │ └── {skill}_{action}.py # UV scripts with prefix └── modules/ # For simple reference MDs (OPTIONAL) └── {category}-{topic}.md # Single-file MDs with prefix

When to Use This Skill

Use this skill when:

• Creating a new skill and deciding between scripts vs modules

• Choosing workflow complexity tier (0-3)

• Naming new files (scripts or modules)

• Understanding the architecture separation

• Reverse-engineering third-party apps

Load Order: This skill should be loaded FIRST when creating any new skill, agent, or workflow.

Available Modules

Module Purpose When to Load

rule-script-vs-md.md

Decision logic for script vs MD Creating new skill content

rule-naming-convention.md

Prefix naming system Naming any new file

rule-skill-tiers.md

Tier 1-4 skill complexity Assessing skill scope

rule-workflow-complexity.md

Tier 0-3 workflow selection Creating workflows

pattern-single-file.md

Universal single-file rules Reviewing file constraints

Available Schemas

Schema Purpose When to Load

workflow-schema.toon

Canonical WORKFLOW.toon format Creating any workflow

step-schema.md

Template for step-NN-{action}.md Creating workflow steps

Decision Flowcharts

Script vs MD Decision

┌─────────────────────────────────────┐ │ NEW SKILL CONTENT NEEDED │ └──────────────┬──────────────────────┘ │ ▼ ┌─────────────────────────────────────┐ │ Requires external Python packages? │ │ (httpx, pandas, click, psutil...) │ ├─────────────┬───────────────────────┤ │ YES │ NO │ │ ↓ │ ↓ │ │ UV SCRIPT │ Requires shell/sys? │ └─────────────┴───────────┬───────────┘ │ ┌───────────┴───────────┐ │ YES │ NO │ │ ↓ │ ↓ │ │ UV SCRIPT │ MD OK │ └─────────────┴─────────┘

Workflow Tier Selection

┌─────────────────────────────────────┐ │ WORKFLOW COMPLEXITY │ └──────────────┬──────────────────────┘ │ ┌──────────┼──────────┬───────────┐ ▼ ▼ ▼ ▼ ┌───────┐ ┌───────┐ ┌─────────┐ ┌─────────┐ │Tier 0 │ │Tier 1 │ │ Tier 2 │ │ Tier 3 │ │1 step │ │3-5 │ │ 5-10 │ │ 10+ │ │hotfix │ │simple │ │ medium │ │ complex │ └───────┘ └───────┘ └─────────┘ └─────────┘

Prefix Naming Quick Reference

Scripts (UV Python)

Pattern: {skill-name}{action}.py Separator: underscore ()

Examples: kalshi_get-market.py kalshi_search-events.py system_analyze-cpu.py builder_generate-skill.py

Modules (Single-File MDs)

Pattern: {category}-{topic}.md Separator: hyphen (-)

Categories: api, pattern, rule, guide, schema, example

Examples: api-endpoints.md pattern-authentication.md rule-naming-convention.md guide-quick-start.md

Works Well With

Agents:

• builder-skill

• Skill creation with tier system

• builder-workflow

• TOON + MD workflow generation

• builder-agent

• Agent with workflows/ generation

Skills:

• moai-library-toon

• TOON format reference

• moai-foundation-core

• Core execution rules

• builder-skill-uvscript

• UV script examples

Commands:

• /moai:1-plan

• SPEC generation with decision framework

• /builder:generate-skill

• Skill creation workflow

Version: 1.0.0 Status: Active Last Updated: 2025-12-02