skill-authoring-quality

Skill Authoring Quality

Read the platform's current skill-creation guidance completely before creating or revising a skill. Use it for the authoring mechanics, then apply this governance and audit workflow.

Take these inputs:

• the complete candidate packet and, for external intake, its pinned source URL plus commit or digest
• realistic prompts that should and should not activate the skill
• the intended canonical source, discovery scope, distribution path, and private/public posture
• the observable completion criterion for each step or review claim

Produce either a review decision or the smallest owned revision, plus exact validation evidence and residual risks.

Audit The Packet

1. Classify the request as review, create/revise, or external intake. For a review, report findings without editing. For external intake, decide adopt, adapt-pattern-only, reject, or not_proven before installation or redistribution.
2. Read the whole packet and any directly routed resources. Classify it as repo-owned, plugin-owned, third-party, private-only, public-safe, or pattern-only. Preserve source and license provenance.
3. Keep one skill focused on one workflow family. Start with instructions; introduce a script only when repeated code, deterministic behavior, or an external tool makes it worthwhile.
4. Write imperative steps with explicit inputs, outputs, proof, stop conditions, and checkable completion criteria. Make exhaustive criteria name the full set that must be accounted for instead of inviting premature completion.
5. Remove generic autonomy prose, repeated examples, and background that Codex already knows. Treat the repository, command help, and generated config as the source of truth; do not cache cheap lookups in instructions.

Check Metadata And Routing

• Use a lowercase hyphen-case name containing only letters, digits, and hyphens, no longer than 64 characters. Match the skill directory name exactly; namespace the name when that prevents ambiguity.
• Keep SKILL.md frontmatter to name and description. Front-load the description with the job and realistic trigger words, then state clear positive and negative boundaries. Put every activation rule in the description because the body loads only after activation.
• Treat every always-loaded description or AGENTS.md pointer as a routing contract. Name the job and each genuinely distinct trigger branch once; collapse synonyms that spend context without adding a branch.
• Budget context load separately from human cognitive load. Keep only the routing pointer always visible, then disclose branch-specific detail behind a direct reference when that detail is not needed for every invocation.
• Put UI-facing display_name, short_description, and default_prompt in agents/openai.yaml. Keep them aligned with SKILL.md; make the default prompt mention $skill-name. Add icons, brand color, invocation policy, or dependencies only when the task supplies them.
• Test the description with realistic positive and negative prompts. Confirm the positive prompts select the skill for a governance need and the negative prompts route generic mechanics to the platform authoring guidance or leave unrelated work alone.