awesome-gbb: Instructions file for Codex

AGENTS.md — Contributor & Sub-Agent Guide

Rules for anyone (human or AI) who edits this repo. Read this before opening a PR, asking a sub-agent to refactor a skill, or running a mass scrub / sync pass. Violating an invariant here breaks downstream consumers in subtle ways that won't fail CI.

This repo is the canonical home of the awesome-gbb skill catalog. The README covers what each skill does. This file covers how to safely change them.

---

1 · Repo layout (what lives where)

awesome-gbb/
├── README.md                 # Public catalog (skills index, install instructions)
├── AGENTS.md                 # ← you are here
├── plugin.json               # Single plugin manifest ("skills": "skills/")
├── skills/                   # SOURCE OF TRUTH for every skill
│   └── <skill-name>/
│       ├── SKILL.md          # Skill definition (frontmatter + instructions)
│       ├── README.md         # Optional extended docs
│       ├── references/       # Optional: scaffolds, templates, canon data
│       │   └── …             # SemVer-stable; consumed by the SKILL at runtime
│       └── templates/        # Optional: copy-paste templates (Bicep, Dockerfile, …)
└── .github/plugin/
    └── marketplace.json      # Lists the plugin for `copilot plugin marketplace add`

There is no monorepo build step for individual skills — each skills/<name>/SKILL.md is a self-contained markdown contract loaded directly by the runtime (Copilot CLI, Copilot Desktop App, VS Code agent mode, Claude Code, etc.).

The repo IS the plugin — plugin.json at the repo root declares "skills": "skills/", so the CLI auto-discovers all skills. No copies, no sync step, no plugins/ directory.

---

2 · Core invariants (do not break these)

These rules govern every edit, however small. If you can't satisfy all of them, do not commit — open a discussion first.

2.1 Skills are agnostic

A skill is a reusable building block. It must read sensibly to a stranger who has never seen the PoC, customer, or repo it was last used in.