skills: expand description to get better triggers

modules/opencode/skills/code-comments/SKILL.md

···
 ---
 name: code-comments
-description: Guide writing high-quality code comments following Ousterhout's principles. Use when writing, reviewing, or improving comments in code. Triggers: "add comments", "how should I comment", "comment this code", "review comments"
+description: Guide writing high-quality code comments following Ousterhout's principles. Covers what comments are for (capturing information code cannot express), what to comment (why decisions were made, units, ranges, invariants, edge cases), interface vs implementation comments, and comment-driven development where interface comments are written before implementation. Use when adding comments to code, reviewing existing comments, improving documentation quality, or establishing commenting conventions.
 ---
 
 ## What comments are for

modules/opencode/skills/code-writing/SKILL.md

···
 ---
 name: code-writing
-description: |
-  Load when writing or refactoring code. Enforces guard clauses,
-  early returns, pure functions, and clean conventions. Use for any code
-  implementation task. Triggers: "implement", "refactor", "write function",
-  "edit code", "fix bug in".
+description: Enforces clean coding conventions for any implementation task. Covers guard clauses and early returns, happy-path left-alignment, pure functions separated from I/O, hexagonal architecture, error handling without panics, input validation at boundaries, parameterized queries, no hardcoded secrets, removing dead code, matching existing project patterns, and keeping functions small and single-responsibility. Use when writing new code, refactoring, fixing bugs, or reviewing code for quality.
 ---
 
 ## Guard Clauses

modules/opencode/skills/debugging/SKILL.md

···
 ---
 name: debugging
-description: Load when debugging failures, errors, crashes, or unexpected behavior. Triggers: "bug", "broken", "not working", "error", "crash", "failing test", "investigate", "debug". Emphasizes empirical investigation over code reasoning.
+description: Systematic debugging protocol emphasizing empirical investigation over code reasoning. Covers the observe-hypothesize-experiment-narrow loop, establishing failure conditions, gathering evidence from logs and git history, forming specific testable hypotheses, designing experiments that distinguish between alternatives, and fixing with minimal changes. Use when investigating crashes, test failures, unexpected behavior, or any situation where the system is not doing what it should.
 ---
 
 # Debugging Protocol

modules/opencode/skills/decision-framework/SKILL.md

···
 ---
 name: decision-framework
-description: Load BEFORE implementing when you need to explore alternatives, surface blind spots, or produce a decision document. Triggers: "help me decide", "what are the options", "tradeoffs", "RFC", "design doc", "before I build this", "not sure which approach".
+description: Structured thinking process for exploring alternatives before committing to an implementation. Covers probing the real problem vs symptoms, surfacing multiple alternatives, finding blind spots like dependencies and failure modes, making tradeoffs visible, and producing a concise decision document. Use when facing architectural choices, evaluating multiple approaches, writing RFCs or design docs, or when unsure which direction to take.
 ---
 
 ## Your Role

modules/opencode/skills/mermaid-diagram-writing/SKILL.md

···
 ---
 name: mermaid-diagram-writing
-description: Load when writing ANY Mermaid diagram. Triggers: "sequence diagram", "flowchart", "visualize the flow", "draw the architecture", "show me how X works", "diagram", "mermaid".
+description: Guidelines for creating clear, readable Mermaid diagrams. Covers minimal styling, preferring many small focused diagrams over one large diagram, participant naming, structured flow control with alt/else/loop/opt, consistent message patterns, and common patterns for API endpoints and error handling. Use when creating sequence diagrams, flowcharts, architecture diagrams, or any visual representation of system behavior.
 ---
 
 # Mermaid Diagram Writing

modules/opencode/skills/skill-builder/SKILL.md

···
 ---
 name: skill-builder
-description: Load when creating new opencode agents or skills. Provides naming conventions, structure requirements, frontmatter formats, and validation checklist.
+description: Complete guide for creating new opencode skills and agents. Covers naming conventions, description requirements, directory structure for global and project-local skills, frontmatter formats with permission settings, content guidelines including line limits and RFC 2119 language, and a validation checklist. Use when building a new skill, creating a new agent, or setting up skill/agent directories.
 ---
 
 ## Naming Conventions

modules/opencode/skills/software-architecture/SKILL.md

···
 ---
 name: software-architecture
-description: Load BEFORE any non-trivial design work. Triggers: "design", "architecture", "design the API", "how should this work". Skip for one-liners and typo fixes.
+description: Design principles for non-trivial software design work. Covers deep modules, small interfaces, making illegal states unrepresentable, fail fast at boundaries, exploring alternatives before implementing, coupling and cohesion, compression-oriented design, and pre-implementation questions. Use when designing new components, refactoring existing systems, adding abstractions, or planning API surfaces.
 ---
 
 ## Deep Modules