Symfony Contributions Skills

Contribute to Symfony like a regular, with your AI agent already knowing the house rules. 🤖

A small plugin that teaches Claude Code, OpenAI Codex, and Gemini CLI the official Symfony contribution rules, so your pull requests land clean on the first try instead of bouncing through three rounds of review. The rules are distilled from Symfony's own contribution docs and stay traceable to the exact .rst sources they came from.

· Works with Claude Code · OpenAI Codex · Gemini CLI

✨ Why

Open a PR on symfony/symfony or symfony/symfony-docs and a reviewer will (kindly) point out that your comparison should be Yoda-style, your deprecation is missing its UPGRADE-*.md note, or your .rst used single backticks instead of double. These skills front-load all of it, so your agent gets it right while writing the code, not after someone flags it.

🧩 Skills

Skill	Reach for it when	Distilled from
symfony-code-contribution	You're writing or reviewing PHP for Symfony core, a bundle, UX (PHP side), AI, etc. Coding standards, naming, deprecations, the backward-compatibility promise, and the patch-version policy.	standards · conventions · bc · maintenance
symfony-docs-contribution	You're writing or editing .rst docs for symfony-docs or a package. reStructuredText format, the writing standards, and the doc PR workflow.	format · standards

💡 Working on a JS/TS project like Webpack Encore? These skills don't apply: follow that project's own CONTRIBUTING.

🚀 Install

Pick your agent. Each one loads the same skills/ through its own mechanism.

🟣 Claude Code

Add the marketplace and enable the plugin in settings.json:

{
  "extraKnownMarketplaces": {
    "symfony-contribution-skills": {
      "source": { "source": "github", "repo": "kocal/symfony-contribution-skills" }
    }
  },
  "enabledPlugins": {
    "symfony-contribution-skills@symfony-contribution-skills": true
  }
}

Or do it interactively, then reload:

/plugin marketplace add kocal/symfony-contribution-skills
/plugin install symfony-contribution-skills@symfony-contribution-skills
/reload-plugins

🟢 OpenAI Codex

Codex reads the very same skills/<name>/SKILL.md format. Register the marketplace, then install from the plugin browser:

codex plugin marketplace add kocal/symfony-contribution-skills

/plugins   # open the browser, install "symfony-contribution-skills", then start a new session

Want zero setup? Codex also reads AGENTS.md. Append the highlights to your global file and every project inherits them:

curl -fsSL https://raw.githubusercontent.com/kocal/symfony-contribution-skills/main/AGENTS.md >> ~/.codex/AGENTS.md

🔵 Gemini CLI

Install the repo as an extension. Gemini loads GEMINI.md into context automatically:

gemini extensions install https://github.com/kocal/symfony-contribution-skills

Manage it anytime with /extensions.

🔄 Keep the skills fresh

The skills are a distillation of the Symfony docs, not a verbatim copy, so upstream can drift. bin/update keeps that visible instead of silent:

bin/update                 # fetch the referent .rst into references/, show what changed upstream
bin/update --regenerate    # rewrite the SKILL.md files + AGENTS/GEMINI cheat-sheets via `claude -p`
bin/update --branch 8.2    # target another symfony-docs branch (default: 8.1)

The default run is deterministic: it only downloads the .rst files and prints the diff, nothing gets rewritten. Regeneration is a separate, explicit step that uses the claude CLI to rewrite the two skills from the updated .rst, then rebuilds the AGENTS.md and GEMINI.md cheat-sheets from those skills so every agent stays in sync. Since that step is LLM-based, review it with git diff before committing. When Symfony opens a newer stable branch, bump BRANCH in the script or pass --branch.

🗂️ Layout

.
├── .claude-plugin/           # Claude Code manifests
│   ├── marketplace.json
│   └── plugin.json
├── .codex-plugin/            # OpenAI Codex manifest
│   └── plugin.json
├── gemini-extension.json     # Gemini CLI extension manifest (contextFileName -> GEMINI.md)
├── AGENTS.md                 # cross-agent cheat-sheet (Codex + generic agents)
├── GEMINI.md                 # cross-agent cheat-sheet (Gemini context file)
├── llms.txt                  # index of skills + sources (llms.txt convention)
├── skills/
│   ├── symfony-code-contribution/
│   │   └── SKILL.md
│   └── symfony-docs-contribution/
│       └── SKILL.md
├── references/               # vendored upstream .rst, baseline for bin/update diffs
│   ├── code/
│   │   ├── bc.rst
│   │   ├── conventions.rst
│   │   ├── maintenance.rst
│   │   └── standards.rst
│   └── documentation/
│       ├── format.rst
│       └── standards.rst
├── bin/
│   └── update                # refresh references/ and optionally regenerate the skills
├── README.md
└── LICENSE

Every agent points at the same two SKILL.md files, so there's one source of truth to maintain. 🎯

🙌 Credits

• Built around the Symfony contribution guidelines 💚
• Inspired by smnandre/symfony-ux-skills, skills for writing Symfony UX code by Simon Andre

📄 License

MIT for the plugin. The Symfony documentation these skills distill is licensed CC BY-SA 3.0.