Skip to content

PATTERNS.md

Latest commit

 

History

History
172 lines (127 loc) · 4.35 KB

PATTERNS.md

File metadata and controls

172 lines (127 loc) · 4.35 KB

Patterns

Patterns are code generation templates that guide how the LLM structures handler code. They capture proven approaches for common tasks.

What Are Patterns?

Patterns are short markdown files that describe:

  • When to use a specific approach
  • What modules/profiles are needed
  • Step-by-step structure

Unlike skills (which provide domain knowledge), patterns focus on code architecture.

Built-in Patterns

Pattern Description
two-handler-pipeline Research → Build using shared-state
file-generation Creating binary files (ZIP, PPTX, etc.)
fetch-and-process Fetch data then transform it
data-transformation Transform input data structures
data-extraction Extract specific data from sources
image-embed Embed images in generated files

Pattern File Format

Patterns live in patterns/<name>/PATTERN.md:

---
name: two-handler-pipeline
description: Research data then build output using separate handlers
modules: [shared-state]
profiles: []
---

1. Register a RESEARCH handler that collects data
2. Store results in ha:shared-state
3. Register a BUILD handler that reads shared-state
4. Execute research → build in sequence
5. Use ha:shared-state for cross-handler data

Frontmatter Fields

Field Description
name Pattern identifier
description One-line summary
modules Required modules
profiles Suggested profiles

Body Content

Numbered steps describing the pattern structure. Keep it concise — these are injected into prompts.

How Patterns Are Used

Referenced by Skills

Skills can reference patterns in their frontmatter:

---
name: pptx-expert
patterns:
  - two-handler-pipeline
  - file-generation
  - image-embed
---

When the skill is loaded, referenced patterns are included in the system message.

Pattern Loading

Patterns are loaded by src/agent/pattern-loader.ts:

  • Discovers patterns in patterns/ directory
  • Parses YAML frontmatter
  • Provides pattern content to system message builder

Common Patterns Explained

two-handler-pipeline

For tasks that need to gather data before building output:

┌──────────────────┐     ┌──────────────────┐
│  RESEARCH        │     │  BUILD           │
│  handler         │────▶│  handler         │
│                  │     │                  │
│  Collects data   │     │  Creates output  │
│  Stores in       │     │  Reads from      │
│  shared-state    │     │  shared-state    │
└──────────────────┘     └──────────────────┘

Why two handlers?

  • Keeps each handler small and focused, pushes the LLM to structure code in a modular way
  • Separates concerns
  • Shared-state persists across recompiles

file-generation

For creating binary files:

  1. Import required modules (zip-format, pptx, etc.)
  2. Build file structure in memory
  3. Return as Uint8Array or base64
  4. Host writes to filesystem (if fs-write enabled)

fetch-and-process

For web data tasks:

  1. Validate URLs (require fetch plugin)
  2. Fetch data with error handling
  3. Parse response (JSON, HTML, etc.)
  4. Transform into desired format
  5. Store or return results

Creating Custom Patterns

1. Create Directory

mkdir -p patterns/my-pattern

2. Create PATTERN.md

---
name: my-pattern
description: Brief description of when to use this
modules: [required-module]
profiles: [suggested-profile]
---

1. First step
2. Second step
3. Third step

3. Reference in Skills

Add to skill frontmatter:

patterns:
  - my-pattern

Pattern vs Skill

Aspect Pattern Skill
Focus Code structure Domain knowledge
Content Step-by-step instructions Guidance and context
Size Brief (10-20 lines) Detailed (100+ lines)
Usage Referenced by skills Loaded directly

Patterns and skills work together:

  • Skills provide domain expertise
  • Skills reference patterns for code structure
  • Both are injected into system message

See Also