skill-standards

name	skill-standards
description	Standards for creating or updating repo-local skills. Use when: adding a new skill, revising a skill, checking whether a skill is too broad, or enforcing the repo skill length rule.

Skill Standards

Hard Limits

• SKILL.md must stay at or below 100 lines, including frontmatter
• One skill = one operation or one edit family
• Prefer a short skill plus referenced repo docs over a long inline guide

Required Shape

• Clear When to Use
• Canonical files or outputs
• Ordered procedure
• Guardrails
• Validation or handoff step

Granularity Rules

• If a skill mixes research and publish steps, split it
• If a skill touches unrelated outputs by default, split it
• If trigger text uses broad and/or language, tighten it
• If most lines are examples, move detail to repo docs
• Do not create a skill for a workflow that is still only planned; point to a decision doc or handoff note until the repo has the owning surfaces

Repo Conventions

• Prefer .agents/skills/<name>/SKILL.md
• Keep names concrete and task-shaped
• Reuse sibling skills instead of duplicating their workflow
• Keep .agents/skill-keeper-agent/AGENT.md aligned when skill ownership or catalog rules change
• Point long process detail to docs/ or research/ references
• Keep durable repo memory in tracked repo artifacts; do not rely on external memory files for repo workflow truth

Quality Bar

• Future agents should know exactly when to trigger the skill
• A failed or unclear case should say to stop, mark under_review, or hand off
• A skill should not require hidden tribal knowledge outside the repo
• A skill must describe live repo behavior, not an approved-but-unimplemented design