bloby-bot 0.69.4 → 0.69.6

package/workspace/skills/create-skill/references/patterns.md

@@ -0,0 +1,126 @@
+# 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.)