95 lines
2.5 KiB
Markdown
95 lines
2.5 KiB
Markdown
# 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.
|