Repo Skill Authoring

Harness Entrypoints

Use these entrypoints:

• Codex skill entrypoint: .agents/skills/repo-skill-authoring/SKILL.md ($repo-skill-authoring)
• Claude skill entrypoint: .claude/skills/repo-skill-authoring/SKILL.md

Repo Skill Shape

Required shape for a repo-local skill:

.agents/skills/<skill-name>/SKILL.md
.agents/skills/<skill-name>/agents/openai.yaml

Optional shape, when the workflow needs it:

.agents/skills/<skill-name>/scripts/
.agents/skills/<skill-name>/references/
.agents/skills/<skill-name>/assets/
.claude/skills/<skill-name>/SKILL.md

Keep .agents/skills/<name>/SKILL.md as the single source of truth. Any harness-specific shim should point directly to it.

Naming And Trigger Rules

• Skill folder names use lowercase letters, digits, and hyphens only.
• The folder name and SKILL.md frontmatter name must match exactly.
• The Codex description must say what the skill does and when to use it.
• Prefer names that describe the reusable workflow, not the implementation detail.
• Keep the skill focused on repo-local conventions that are not already handled by generic guidance.

Agent Execution Standard

For agent implementation and review tasks, follow this workflow:

1. Define the user/problem shape.
   • Write down the jobs the skill should handle.
   • Prefer concrete trigger phrases and in-scope task examples.
2. Split the content deliberately.
   • Put the canonical workflow, conventions, and examples in this SKILL.md.
   • Add scripts/ only when deterministic validation or repeated logic is worth the maintenance cost.
   • Add references/ only when detailed content should be loaded on demand instead of sitting in the skill body.
3. Add the skill entrypoint.
   • Include frontmatter name and description.
   • Keep this file readable by both agents and humans.
4. Add the minimum harness shims required.
   • Add .claude/skills/<name>/SKILL.md when Claude needs a pointer.
   • Point every shim directly back to .agents/skills/<name>/SKILL.md.
5. Sanity check the result.
   • Confirm the skill and any shims all point to the same workflow.

Authoring principle:

• Keep the repo skill as the canonical artifact. Avoid extra pointer layers unless they materially improve discovery or ergonomics.

Required agent response sections:

1. Implementation Checklist
2. Files To Add Or Modify
3. Validation
4. Assumptions

Minimal Examples

Canonical Repo Skill

---