feat(writing-skills): refactor skill to gold standard architecture

skills/writing-skills/references/standards/README.md

@@ -0,0 +1,152 @@
+---
+description: Standards and naming rules for creating agent skills.
+metadata:
+  tags: [standards, naming, yaml, structure]
+---
+
+# Skill Development Guide
+
+Comprehensive reference for creating effective agent skills.
+
+## Directory Structure
+
+```
+~/.config/opencode/skills/
+  {skill-name}/           # kebab-case, matches `name` field
+    SKILL.md              # Required: main skill definition
+    references/           # Optional: supporting documentation
+      README.md           # Sub-topic entry point
+      *.md                # Additional files
+```
+
+**Project-local alternative:**
+```
+.agent/skills/{skill-name}/SKILL.md
+```
+
+## Naming Rules
+
+| Element | Rule | Example |
+|---------|------|---------|
+| Directory | kebab-case, 1-64 chars | `react-best-practices` |
+| `SKILL.md` | ALL CAPS, exact filename | `SKILL.md` (not `skill.md`) |
+| `name` field | Must match directory name | `name: react-best-practices` |
+
+## SKILL.md Structure
+
+```markdown
+---
+name: {skill-name}
+description: >-
+  Use when [trigger condition].
+metadata:
+  category: technique
+  triggers: keyword1, keyword2, error-text
+---
+
+# Skill Title
+
+Brief description of what this skill does.
+
+## When to Use
+
+- Symptom or situation A
+- Symptom or situation B
+
+## How It Works
+
+Step-by-step instructions or reference content.
+
+## Examples
+
+Concrete usage examples.
+
+## Common Mistakes
+
+What to avoid and why.
+```
+
+## Description Best Practices
+
+The `description` field is critical for skill discovery:
+
+```yaml
+# ❌ BAD: Workflow summary (agent skips reading full skill)
+description: Analyzes code, finds bugs, suggests fixes
+
+# ✅ GOOD: Trigger conditions only
+description: Use when debugging errors or reviewing code quality.
+metadata:
+  triggers: bug, error, code review
+```
+
+**Rules:**
+- Start with "Use when..."
+- Put triggers under `metadata.triggers`
+- Keep under 500 characters
+- Use third person (not "I" or "You")
+
+## Context Efficiency
+
+Skills load into context on-demand. Optimize for token usage:
+
+| Guideline | Reason |
+|-----------|--------|
+| Keep SKILL.md < 500 lines | Reduces context consumption |
+| Put details in supporting files | Agent reads only what's needed |
+| Use tables for reference data | More compact than prose |
+| Link to `--help` for CLI tools | Avoids duplicating docs |
+
+## Supporting Files
+
+For complex skills, use additional files:
+
+```
+my-skill/
+  SKILL.md              # Overview + navigation
+  patterns.md           # Detailed patterns
+  examples.md           # Code examples
+  troubleshooting.md    # Common issues
+```
+
+**Supporting file frontmatter is required** (for any `.md` besides `SKILL.md`):
+
+```markdown
+---
+description: >-
+  Short summary used for search and retrieval.
+metadata:
+  tags: [pattern, troubleshooting, api]
+  source: internal
+---
+```
+
+This frontmatter helps the LLM locate the right file when referenced from `SKILL.md`.
+
+Reference from SKILL.md:
+```markdown
+## Detailed Reference
+
+- [Patterns](patterns.md) - Common usage patterns
+- [Examples](examples.md) - Code samples
+```
+
+## Skill Types
+
+| Type | Purpose | Example |
+|------|---------|---------|
+| **Reference** | Documentation, APIs | `bigquery-analysis` |
+| **Technique** | How-to guides | `condition-based-waiting` |
+| **Pattern** | Mental models | `flatten-with-flags` |
+| **Discipline** | Rules to enforce | `test-driven-development` |
+
+## Verification Checklist
+
+Before deploying:
+
+- [ ] `name` matches directory name?
+- [ ] `SKILL.md` is ALL CAPS?
+- [ ] Description starts with "Use when..."?
+- [ ] Triggers listed under metadata?
+- [ ] Under 500 lines?
+- [ ] Tested with real scenarios?

skills/writing-skills/references/standards/metadata-standard.md

@@ -0,0 +1,65 @@
+# SKILL.md Metadata Standard
+
+Official frontmatter fields recognized by OpenCode.
+
+## Required Fields
+
+```yaml
+---
+name: skill-name
+description: >-
+  Use when [trigger condition].
+metadata:
+  triggers: keyword1, keyword2, error-message
+---
+```
+
+| Field | Rules |
+|-------|-------|
+| `name` | 1-64 chars, lowercase, hyphens only, must match directory name |
+| `description` | 1-1024 chars, should describe when to use |
+
+## Optional Fields
+
+```yaml
+---
+name: skill-name
+description: Purpose and triggers.
+metadata:
+  license: MIT
+  compatibility: opencode
+  author: "your-name"
+  version: "1.0.0"
+  category: "reference"
+  tags: "tag1, tag2"
+---
+```
+
+| Field | Purpose |
+|-------|---------|
+| `license` | License identifier (e.g., MIT, Apache-2.0) |
+| `compatibility` | Tool compatibility marker |
+| `metadata` | String-to-string map for custom key-values |
+
+## Name Validation
+
+```regex
+^[a-z0-9]+(-[a-z0-9]+)*$
+```
+
+**Valid**: `my-skill`, `git-release`, `tdd`  
+**Invalid**: `My-Skill`, `my_skill`, `-my-skill`, `my--skill`
+
+## Common Metadata Keys
+
+Use these conventions for consistency across skills:
+
+| Key | Example | Purpose |
+|-----|---------|---------|
+| `author` | `"your-name"` | Skill creator |
+| `version` | `"1.0.0"` | Semantic version |
+| `category` | `"reference"` | Type: reference, technique, discipline, pattern |
+| `tags` | `"react, hooks"` | Searchable keywords |
+
+> [!IMPORTANT]
+> Any field not listed here is **ignored** by OpenCode's skill loader.