# Authoring Patterns & Anti-Patterns

Read this while you're actually drafting a skill. `SKILL.md` has the workflow; this has
the craft.

## Writing good descriptions

The description is the trigger, so it's worth obsessing over a little.

- **Third person.** "Extracts text from PDFs." Not "I can help you…" or "You can use…".
- **What + When.** Capabilities *and* the situations that should fire it.
- **Trigger terms.** Name the file types, phrases, and contexts. Include the cases where
  the human won't say the obvious keyword but clearly needs the skill.

```yaml
# PDF processing
description: Extract text and tables from PDFs, fill forms, merge documents. Use whenever
  a PDF, form, or scanned document is involved, or the human asks to pull data out of a file.

# Spreadsheet analysis
description: Analyze spreadsheets, build pivot tables, generate charts. Use for .xlsx/.csv
  files, tabular data, "summarize this sheet", or any number-crunching over rows and columns.

# Commit messages
description: Write descriptive commit messages from a git diff. Use when the human asks for
  a commit message or wants staged changes summarized.
```

## Degrees of freedom — match specificity to fragility

| Freedom | When | How |
|---|---|---|
| **High** (prose guidance) | many valid approaches, context-dependent | code review, writing voice |
| **Medium** (templates/pseudocode) | a preferred shape with acceptable variation | report generation |
| **Low** (exact scripts) | fragile, consistency is critical | DB migrations, packaging |

Give the model room where judgment helps, and lock it down only where a wrong step is
expensive. Over-constraining a flexible task makes the skill brittle and annoying.

## Output format pattern

When the result must take a specific shape, show the template:

```markdown
## Report structure
Use this template:
# [Title]
## Summary
## Key findings
## Recommendations
```

## Examples pattern

For skills where quality depends on seeing a few examples, show input → output:

```markdown
**Example 1**
Input: Added user auth with JWT tokens
Output: feat(auth): implement JWT-based authentication

**Example 2**
Input: Fixed dates showing in the wrong timezone
Output: fix(reports): use UTC timestamps in report generation
```

Concrete examples teach far better than abstract description.

## Workflow / checklist pattern

For multi-step operations, give a checklist the model can copy and track:

```markdown
## Form-filling workflow
- [ ] Analyze the form
- [ ] Map the fields
- [ ] Validate the mapping
- [ ] Fill and verify
```

## Feedback-loop pattern

For quality-critical work, build in a validate step:

```markdown
1. Make the edit
2. Validate immediately: `python scripts/validate.py output/`
3. If it fails: read the error, fix, re-run
4. Only proceed once validation passes
```

## Scripts: bundle, don't regenerate

A pre-made script in `scripts/` beats code the model writes fresh each time — it's more
reliable, costs no context tokens, and stays consistent. Make clear whether the model
should **run** it (usual) or **read** it as reference. Document required packages, and
remember Bloby installs into the workspace `node_modules`/`package.json` — never the
parent. Use forward-slash paths (`scripts/helper.py`), never backslashes.

---

## Anti-patterns to avoid

1. **Verbosity.** Don't explain what the model already knows ("A PDF is a file format…").
   Every token competes for context. Challenge each line: does it justify its cost?

2. **Too many options.** "Use pypdf or pdfplumber or PyMuPDF or…" paralyzes. Give one
   default with an escape hatch: "Use pdfplumber; for scanned PDFs needing OCR, use
   pdf2image + pytesseract."

3. **Time-sensitive notes.** "Before August, use the old API" rots. Use a *Current* section
   and tuck legacy behavior into a collapsed "Old patterns" block.

4. **Inconsistent terminology.** Pick one word and stick to it — "field" everywhere, not
   a mix of "box"/"element"/"control". Drift makes instructions ambiguous.

5. **Vague names.** `processing-pdfs`, not `helper`/`utils`/`tools`.

6. **Walls of MUST/NEVER.** Rigid all-caps rules signal you stopped explaining. Reframe
   with the reasoning — it's more humane and more robust.

7. **Deeply nested references.** Keep `references/` one level deep from `SKILL.md`.
   Deeply chained reads get truncated or skipped.

8. **Skills that surprise.** A skill's behavior must match what its description implies.
   No malware, no exfiltration, no hidden side effects. (Roleplay/persona skills are fine.)