Common Patterns

Degrees of freedom
Template pattern
Examples pattern
Conditional workflow pattern
Workflow with checklist
Feedback loops
Domain-specific organization

Degrees of freedom

Match specificity to task fragility. Think of an agent exploring a path: a narrow bridge with cliffs needs specific guardrails (low freedom), while an open field allows many routes (high freedom).

High freedom (text instructions)

Use when multiple approaches are valid or decisions depend on context.

## Code review process

1. Analyze the code structure and organization
2. Check for potential bugs or edge cases
3. Suggest improvements for readability
4. Verify adherence to project conventions

Medium freedom (pseudocode/parameterized scripts)

Use when a preferred pattern exists but some variation is acceptable.

## Generate report

Use this template and customize as needed:

```python
def generate_report(data, format="markdown", include_charts=True):
    # Process data
    # Generate output in specified format
```

Low freedom (specific scripts)

Use when operations are fragile, consistency is critical, or a specific sequence must be followed.

## Database migration

Run exactly this script:

```bash
python scripts/migrate.py --verify --backup
```

Do not modify the command or add additional flags.

Template pattern

Provide output format templates. Match strictness to requirements.

Strict (API responses, data formats):

## Report structure

ALWAYS use this exact template:

```markdown
# [Title]

## Executive summary

[One paragraph]

## Key findings

- Finding 1
- Finding 2
```

Flexible (when adaptation is useful):

## Report structure

Sensible default format—adapt based on analysis:

```markdown
# [Title]

## Executive summary

## Key findings
```

Adjust sections as needed.

Examples pattern

Provide input/output pairs for output-quality-dependent tasks.

## Commit message format

**Example 1:**
Input: Added user authentication with JWT tokens
Output:

```
feat(auth): implement JWT-based authentication

Add login endpoint and token validation middleware
```

**Example 2:**
Input: Fixed bug where dates displayed incorrectly
Output:

```
fix(reports): correct date formatting in timezone conversion
```

Conditional workflow pattern

Guide through decision points:

## Document modification

1. Determine the modification type:

   **Creating new content?** → Follow "Creation workflow"
   **Editing existing?** → Follow "Editing workflow"

2. Creation workflow:
   - Use docx-js library
   - Build from scratch
   - Export to .docx

3. Editing workflow:
   - Unpack existing document
   - Modify XML directly
   - Validate after each change

Workflow with checklist

For complex multi-step tasks:

## Form filling workflow

Copy this checklist:

```
- [ ] Step 1: Analyze form (run analyze_form.py)
- [ ] Step 2: Create field mapping
- [ ] Step 3: Validate mapping
- [ ] Step 4: Fill the form
- [ ] Step 5: Verify output
```

**Step 1: Analyze the form**
Run: `python scripts/analyze_form.py input.pdf`

Feedback loops

Run validator → fix errors → repeat. This pattern greatly improves output quality.

## Document editing process

1. Make edits to document
2. **Validate immediately**: `python scripts/validate.py`
3. If validation fails:
   - Review the error message
   - Fix the issues
   - Validate again
4. **Only proceed when validation passes**

Domain-specific organization

For skills with multiple domains, organize by domain to avoid loading irrelevant context.

bigquery-skill/
├── SKILL.md
└── reference/
    ├── finance.md
    ├── sales.md
    ├── product.md
    └── marketing.md

# SKILL.md

## Available datasets

**Finance**: Revenue, billing → See [reference/finance.md](reference/finance.md)
**Sales**: Pipeline, accounts → See [reference/sales.md](reference/sales.md)

When user asks about revenue, the agent reads only finance.md.

patterns.md