agent-skills: Instructions file for Codex

AGENTS.md

Guidelines for AI agents working in this repository.

Repository Overview

This is a documentation-only repository containing agent skills -- structured Markdown reference documents designed to be installed into AI coding agents (OpenCode, Claude Code, Copilot, etc.) via the skills.sh ecosystem. There is no application code, no build system, no dependencies, and no tests.

Structure

skills/
  <skill-name>/
    SKILL.md              # Main entry point (has YAML frontmatter)
    references/
      <topic>.md          # Deep-dive reference documents
      allowlist.md        # Tool permission patterns (optional)

Current skills: bun-api, bun-cli, git-commit, git-pr, git-ci, git-project, coderabbit, deps-upgrade.

Build / Lint / Test Commands

There are none. This repository contains only Markdown files. No package.json, no CI/CD, no linter configuration, no test runner.

To validate changes, manually review Markdown rendering. If adding links, verify they point to valid targets.

Content Style Guidelines

SKILL.md Files (Main Entry Points)

Every skill's SKILL.md must include YAML frontmatter:

---
name: skill-name
description: >-
  What the skill covers, when to use it, and when not to use it.
  No trailing period. Use YAML folded scalar (>-) for multi-line
---

• name: kebab-case, matches the directory name
• description: concise, plain text, no trailing period. Use YAML >- (folded scalar) for multi-line. Include trigger guidance (when to use / not use) since skills.sh uses this field for auto-loading decisions

Document Structure

1. H1 heading immediately after frontmatter -- matches the skill's subject
2. Opening paragraph -- bold, concise, establishes context and scope
3. Version pin (skills that drive a CLI) -- a bold **Verified against <tool> vX.Y.Z** (YYYY-MM-DD) line right after the opening paragraph, naming what was checked and what to do when the installed version is newer
4. "When to Use" section -- bullet list of triggering scenarios
5. "Critical Rule" or "Critical Rules" section -- bold, imperative, must-follow constraints
6. Major topic sections (H2) covering the skill's API/CLI surface
7. Key Gotchas / Best Practices -- a numbered list at the end; use either name (most skills use ## Key Gotchas)
8. References -- blockquote pointers to references/*.md files