init

.opencode/skills/skill-creator/references/metadata-quality-criteria.md

@@ -0,0 +1,94 @@
+# Metadata Quality Criteria
+
+Metadata determines when Claude activates the skill. Poor metadata = wrong activation or missed activation.
+
+## Name Field
+
+**Format:** use either `skill-name` or `namespace:skill-name` (for example `ck:plan`), all lowercase
+
+**Good Examples:**
+- `pdf-editor` - clear domain
+- `ck:bigquery-analyst` - namespaced variant
+- `frontend-webapp-builder` - specific function
+
+**Bad Examples:**
+- `helper` - too generic
+- `mySkill` - wrong case
+- `pdf` - too short, unclear purpose
+
+## Description Field
+
+**Constraint:** ≤1024 characters (official max). Shorter is better for token efficiency, but longer descriptions trigger more reliably.
+
+**Purpose:** Trigger automatic activation during implementation. Be "pushy" — include specific trigger contexts.
+
+### Good Descriptions
+
+Specific, action-oriented, includes use cases:
+
+```yaml
+description: Build React/TypeScript frontends with modern patterns. Use for components, Suspense, lazy loading, performance optimization.
+```
+
+```yaml
+description: Process PDFs with rotation, splitting, merging. Use for document manipulation, page extraction, PDF conversion.
+```
+
+### Bad Descriptions
+
+Too generic or educational:
+
+```yaml
+description: A skill for working with databases.  # Too vague
+```
+
+```yaml
+description: This skill helps you understand how React works.  # Educational, not actionable
+```
+
+## Trigger Precision
+
+Description should answer: "What phrases would a user say that should trigger this skill?"
+
+**Example for `image-editor` skill:**
+- "Remove red-eye from this image"
+- "Rotate this photo 90 degrees"
+- "Crop the background out"
+
+Include these trigger phrases/actions in description.
+
+## Third-Person Style
+
+**Correct:** "This skill should be used when..."
+**Wrong:** "Use this skill when..." or "You should use this..."
+
+## Validation
+
+Check with packaging script:
+
+```bash
+scripts/package_skill.py <skill-path>
+```
+
+Fails if:
+- Missing name or description
+- Description exceeds 1024 characters
+- Name exceeds 64 characters
+- Invalid YAML syntax
+
+## Pushy Descriptions (Anti-Undertriggering)
+
+**Problem:** Generic descriptions cause skills to activate too rarely.
+
+```yaml
+# BAD — undertriggers
+description: Data processing skill
+
+# GOOD — triggers reliably
+description: Process CSV files and tabular data. Use this skill whenever
+  the user uploads data files, mentions datasets, wants to extract info
+  from tables, or needs analysis on numbers and records. Make sure to
+  use this skill whenever data transformation is needed.
+```
+
+Include "Use this skill whenever..." and list specific trigger contexts.