Agent Skills

This repository is the organization-level source of truth for reusable agent skills used by agentic harnesses such as Codex. New repositories should reference this repo's skills and conventions instead of pointing agents at entire implementation repositories.

Layout

.
+-- AGENTS.md
+-- README.md
+-- scripts/
|   +-- new-skill.sh
|   +-- validate-skills.sh
+-- skills/
|   +-- <skill-name>/
|       +-- SKILL.md
|       +-- agents/
|       |   +-- openai.yaml
|       +-- scripts/
|       +-- references/
|       +-- assets/
+-- templates/
    +-- skill/
        +-- SKILL.md.template
        +-- agents/
            +-- openai.yaml.template

Only SKILL.md is required for a skill. Add agents/openai.yaml, scripts/, references/, and assets/ when they help the agent perform the task.

Add a Skill

Create a scaffold:

./scripts/new-skill.sh "GitHub PR Triage" --resources references,scripts

Then edit skills/github-pr-triage/SKILL.md:

• Set a trigger-focused description: that explains when an agent should use the skill.
• Keep the body short, imperative, and workflow-oriented.
• Put detailed docs in references/.
• Put deterministic utilities in scripts/.
• Put reusable starter files or media in assets/.

Validate before publishing changes:

./scripts/validate-skills.sh

Skill Conventions

• Skill folders use lowercase hyphenated names.
• The folder name and SKILL.md frontmatter name: must match.
• Do not add README, changelog, or process notes inside individual skill folders unless the skill itself needs them.
• Keep each skill portable across repositories and harnesses.