write-a-skill

name	write-a-skill
description	Create or update rankingdepadel.club Codex skills with concise instructions, triggerable metadata, progressive disclosure, and repository validation. Use when the user asks to create, write, build, adapt, or revise a skill under .codex/skills.

Write a Skill

Use this skill for repository-local Codex skills.

Scope

• Target path: .codex/skills/<skill-name>/.
• Required file: SKILL.md.
• Optional file: agents/openai.yaml when the skill should appear in UI surfaces.
• Optional folders: references/, scripts/, and assets/ only when they directly support the skill.
• Do not add auxiliary docs such as README.md, quick references, or changelogs inside a skill.

Workflow

1. Verify the branch before editing. If not on develop, warn and wait.
2. Gather enough requirements from the user and repository context:
   • task or domain the skill covers
   • trigger phrases and situations
   • expected workflow or decision points
   • whether deterministic scripts, references, or assets are needed
3. Inspect nearby skills for tone, section shape, and metadata style.
4. Draft or update SKILL.md with concise frontmatter and only core workflow instructions.
5. Add one-level-deep references only when optional detail would otherwise bloat SKILL.md.
6. For skills that rely on remote docs, MCP tools, scripts, or bundled references, define the source of truth, fallback order, and when fallback use must be disclosed.
7. Add scripts only for repeatable, deterministic work that Codex would otherwise regenerate.
8. Add or refresh agents/openai.yaml only when the skill should appear in UI surfaces.
9. If router instructions change, update AGENTS.md metadata. Leave release-pinned docs/PROJECT_INSTRUCTIONS.md metadata for release preparation or release closure.
10. Validate changed Markdown and governance metadata.

SKILL.md Rules

• Frontmatter must include name and description.
• Use kebab-case for name and the directory.
• The description is the trigger surface; make it specific.
• Prefer two description sentences:
  • what the skill does
  • Use when ... with concrete triggers
• Keep the body compact and procedural.
• Trust Codex's general knowledge; include only repo-specific workflow, constraints, edge cases, or validation steps.
• Preserve explicit user targets for migrations, upgrades, and rewrites. Use "latest", "current", or default-target lookup only when the user leaves the target unspecified.
• Bound the skill's change scope. State meaningful non-goals when adjacent changes are likely but not intended.
• If authoritative guidance and repository behavior disagree, instruct Codex to state the conflict and stop before broad edits.
• Keep detailed examples out unless they prevent likely mistakes.

Progressive Disclosure

• Keep SKILL.md under 100 lines when practical.
• Split details into references/<topic>.md when a section is long, rarely needed, or domain-specific.
• Link every reference directly from SKILL.md and state when to read it.
• Avoid nested reference chains.
• Treat the AGENTS.md 1800-character router target as a soft compaction signal, not a rewrite trigger. Do not rewrite only for size until it is more than 15% over target, and stop after one scoped compaction pass even if it remains above target. Still respect the validator's hard maximum.

Local UI Metadata

Use this shape unless the repository has changed its convention:

display_name: Skill Name
short_description: Short human-facing purpose.
default_prompt: Use $skill-name to ...

Keep default_prompt short and include the $skill-name invocation.

Validation

• Run python scripts/validate_governance.py after routed-skill, governance, router, project-instruction metadata, or validation-policy edits.
• Run markdownlint on changed Markdown files when available; MD013 is non-blocking.
• For scripts added to a skill, run their smallest meaningful check.