document-learnings

name	document-learnings
description	Guidelines for documenting reusable patterns discovered during work. Use when completing tasks that reveal non-obvious workflows or project conventions.

Purpose

Capture reusable knowledge so future sessions avoid repeated debugging and rediscovery.

When to Document

• After discovering a required workflow with multiple mandatory steps
• After fixing a non-obvious bug or uncovering a subtle constraint
• After establishing a new pattern or convention
• After the user corrects the model's approach — this reveals the user's preferred way of working
• When the user asks to document learnings

When NOT to Document

• Obvious or standard practices
• One-off debugging that won't recur
• Information already well-covered in existing docs

Where to Put Documentation

Scope	Location
Project-specific workflows	.opencode/skills/<name>/SKILL.md
Short reference needed every invocation	AGENTS.md

Skill File Format

---
name: skill-name
description: Short description. Use when ...
---

## Purpose
What this skill covers.

## Instructions
### 1. Step One
Specific, actionable steps with code examples.

## Common Pitfalls
| Pitfall | Fix |
|---------|-----|
| ... | ... |

Tips

• Keep skill descriptions actionable
• Include code examples and common pitfalls tables
• Commit skills to the repo so the whole team benefits
• Pay special attention when the user corrects or refines the model's output — that feedback encodes the user's standards and preferences for this project
• Document the "why" behind conventions, not just the "what" — e.g., why a checklist exists, what goes wrong if a step is skipped