yaojingang
68 lines
1.6 KiB
Markdown
68 lines
1.6 KiB
Markdown
# Skill Design Guidelines
|
|
|
|
This document captures the operating rules for `yao-meta-skill`.
|
|
|
|
## 1. Treat Skill Creation As Product Design
|
|
|
|
A generated skill should answer these questions clearly:
|
|
|
|
- What exact recurring job does this package improve?
|
|
- Who is the intended user or agent?
|
|
- What is in scope and out of scope?
|
|
- What should be stable across runs?
|
|
- What is expected to evolve over time?
|
|
|
|
## 2. Separate Three Kinds Of Content
|
|
|
|
Put each kind of content in the right place:
|
|
|
|
- `SKILL.md`: core workflow, trigger surface, decision rules
|
|
- `references/`: detailed domain material, examples, schemas, policy docs
|
|
- `scripts/`: deterministic or brittle operations
|
|
|
|
If you mix all three into `SKILL.md`, quality and maintainability drop fast.
|
|
|
|
## 3. Use A Trigger Matrix
|
|
|
|
Every important skill should have a trigger matrix:
|
|
|
|
- positive prompts
|
|
- clear negatives
|
|
- near neighbors
|
|
|
|
The goal is not just "can it trigger", but "does it trigger at the right boundary".
|
|
|
|
## 4. Keep The Body Small On Purpose
|
|
|
|
Do not optimize only for completeness.
|
|
|
|
Optimize for:
|
|
|
|
- low context cost
|
|
- clear branch selection
|
|
- discoverable references
|
|
- safe defaults
|
|
|
|
## 5. Add Lifecycle Metadata Only When It Helps
|
|
|
|
For personal or disposable skills, extra metadata can be noise.
|
|
|
|
For shared skills, a `manifest.json` is useful for:
|
|
|
|
- owner
|
|
- version
|
|
- updated_at
|
|
- target platforms
|
|
- review cadence
|
|
|
|
## 6. Prefer Progressive Industrialization
|
|
|
|
Move through these stages:
|
|
|
|
1. Working draft
|
|
2. Trigger-hardened draft
|
|
3. Reusable team skill
|
|
4. Governed skill asset
|
|
|
|
Do not start every skill at stage 4.
|