agent-skills: Instructions file for Codex

AGENTS.md - Agent Skills Repository

This repository contains AI agent skills following the Agent Skills format.

Repository Structure

skills/
  <skill-name>/
    SKILL.md      # Skill definition with YAML frontmatter and documentation

Commands

This is a documentation/skill repository with no build, lint, or test commands.

Validation

Skills are validated using the skills-ref validator from the agentskills project:

# Install the validator
pip install git+https://github.com/agentskills/agentskills.git#subdirectory=skills-ref

# Validate a single skill
skills-ref validate skills/<skill-name>

# Validate all skills
for skill_dir in skills/*/; do
  skills-ref validate "$skill_dir"
done

Validation runs automatically on pull requests via GitHub Actions (.github/workflows/validate-skills.yml).

Code Style Guidelines

SKILL.md Files

Frontmatter (required at the top):

---
name: skill-name
description: Brief description of what the skill does
license: MIT
compatibility: Optional requirements (e.g., "Requires GitHub CLI")
metadata:
  version: "1.0.0"
---

• name: kebab-case, matches directory name
• description: One sentence, imperative mood, explains when to use the skill
• license: MIT (standard for this repository)
• compatibility: Optional, list external requirements
• metadata.version: Semantic version

Content Guidelines:

• Use clear headings (#, ##, ###)
• Include code examples in fenced blocks with language tags
• Keep all lines under 100 characters
• Use tables for structured data (types, options, examples)

File Naming

• Skill directories: kebab-case (e.g., conventional-commit, create-pr)
• Skill files: SKILL.md (uppercase, consistent across all skills)
• Workflow files: kebab-case with .yml extension

Writing Style

• Use imperative mood for instructions ("Run tests", not "You should run tests")
• Include code examples in fenced blocks with language specification
• Explain what and why, not just how
• Use present tense throughout