ag2-skills: Instructions file for Codex

AGENTS.md

This file provides guidance to AI coding agents (Claude Code, Cursor, Copilot, etc.) when working with code in this repository.

Repository Overview

A collection of skills for working with AG2 — an async, protocol-driven Python agent framework (ag2). Skills are packaged instructions and optional helper scripts that extend an agent's capabilities.

Skills follow the Agent Skills format: a SKILL.md with YAML frontmatter, plus optional scripts/ and references/ directories.

Creating a New Skill

Directory Structure

skills/
  {skill-name}/           # kebab-case directory name
    SKILL.md              # Required: skill definition
    scripts/              # Optional: executable scripts
      {script-name}.py    # Python preferred (matches AG2's runtime)
    references/           # Optional: supporting docs the agent reads on demand
  {skill-name}.zip        # Optional: packaged for distribution

Naming Conventions

• Skill directory: kebab-case, prefixed ag2- for AG2-feature skills (e.g. ag2-quickstart, ag2-middleware).
• SKILL.md: Always uppercase, always this exact filename.
• Scripts: kebab-case or snake_case — pick one per skill and stay consistent.
• Zip file: Must match directory name exactly: {skill-name}.zip.

SKILL.md Format

---
name: {skill-name}
description: {One paragraph describing exactly when to use this skill. Lead with the action and key API surface; include trigger phrases and what to use it *with* (sibling skills).}
license: Apache-2.0
---

# {Skill Title}

## When to use

{Concrete situations where this skill applies. List trigger phrases and the user goals it serves.}

## Recipe

{Numbered steps or a minimal working example, in Python. Show the imports.}

## Reference

{Link to any files in `references/` or upstream AG2 docs (`website/docs/user-guide/...`).}

Frontmatter limits (per the Agent Skills spec)