gordon1210gordon1210/agent-goodies/AGENTS.md

agent-goodies

AGENTS.md0 starsChanged 4 months agoMITView on GitHub

This repository distributes skills and plugins through skills.sh, Codex/ChatGPT, and Claude Code. Keep shared behavior portable and isolate host-specific packaging or configuration. - .agents/plugins/marketplace.json is the Codex/ChatGPT marketplace. - .claude-plugin/marketplace.json is the Claude Code marketplace. - skills/<skill-name>/SKILL.md is the canonical standalone-skill layout used by the skills CLI. - Claude Code may expose a standalone skill directly with a manifestless marketplace entry using strict: false and an explicit skills path. - Multi-skill plugins live under plugins/<plugin-name>/, with both host manifests and…

Where files are headingNew AGENTS.md files have more rules about keeping secrets out of the code, and fewer about code style.
Of the AGENTS.md files we read, the 31,439 first seen in the last six months, against the older ones: the kind of rule that gained most share, and the kind that lost most. About files like this in general, not this one, and an estimate, since a kind is a pattern in the words.
In this repository14 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- add-tauri-native-window-effectsSkill
- agent-councilSkill
- claude-cliSkill
- deep-code-reviewSkill
- design-ui-excellenceSkill
- godot-engineering-suiteSkill
- godot-ui-design-excellenceSkill
- grok-cliSkill
- handoffSkill
- react-codebase-excellenceSkill
- rust-codebase-excellenceSkill
- typescript-codebase-excellenceSkill
- webdesign-excellenceSkill

The file

Show its rules and text

We split this AGENTS.md into the rules it gives an agent

19 rules. About 0 are common, 13 are distinctive, and 6 are very specific to this project.

≈0
Common · estimate
Many files like this have a rule of this kind.
≈13
Distinctive · estimate
This author's own choices. Worth a look.
6
Very specific
Tied to their project's names, files or tools. Probably skip.

Common
Distinctive
Very specific

Distinctive:
Keep supporting scripts, references, and assets inside the relevant plugin or standalone skill root.
line 19
Distinctive:
Use lowercase kebab-case names.
line 24
Distinctive:
Keep the two plugin manifest versions aligned when a plugin targets both hosts.
line 26
Distinctive:
Keep the version in each host manifest, not in a marketplace entry.
line 28
Distinctive:
Add a plugin only to the marketplace buckets that should expose it.
line 30
Very specific:
Keep top-level skills/<skill-name> entries as real directories because the skills CLI's repository scan skips symlink directory entries.
line 36
Distinctive:
Do not leave placeholder metadata or unfinished TODO markers in manifests.
line 43
Very specific:
Prefer the common name and description frontmatter fields.
line 47
Distinctive:
Avoid host-specific frontmatter, substitutions, channels, and directives in shared skills.
line 49
Distinctive:
Put genuinely host-specific behavior in host-specific configuration or a host-specific skill instead of branching throughout a shared skill.
line 51
Very specific:
Keep each SKILL.md concise and place detailed material in nearby references or scripts.
line 53
Very specific:
Run python3 scripts/validate_repo.py before committing a plugin change.
line 62
Very specific:
Run python3 -m unittest tests/test_handoff.py -v after changing the Handoff skill.
line 63
Distinctive:
Run the relevant Codex and Claude validators when available.
line 65
Distinctive:
Keep README.md accurate when repository structure or installation changes.
line 67
Distinctive:
Update both host manifests and the plugin changelog in the same change.
line 72
Distinctive:
Create releases only from the default branch after validation passes.
line 75
Very specific:
Follow RELEASING.md for the full release process.
line 76
Distinctive:
Do not install, publish, commit, push, or release changes unless explicitly requested.
line 78

≈ “Common” is an estimate: at least 1 in 5 of the 40,246 AGENTS.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.

Files

AGENTS.md

Repository Instructions

Purpose

This repository distributes skills and plugins through skills.sh, Codex/ChatGPT, and Claude Code. Keep shared behavior portable and isolate host-specific packaging or configuration.

Repository layout

.agents/plugins/marketplace.json is the Codex/ChatGPT marketplace.
.claude-plugin/marketplace.json is the Claude Code marketplace.
skills/<skill-name>/SKILL.md is the canonical standalone-skill layout used by the skills CLI.
Claude Code may expose a standalone skill directly with a manifestless marketplace entry using strict: false and an explicit skills path.
Multi-skill plugins live under plugins/<plugin-name>/, with both host manifests and a skills/<skill-name>/SKILL.md subtree.
Keep supporting scripts, references, and assets inside the relevant plugin or standalone skill root.

Authoring rules

Use lowercase kebab-case names. A plugin directory and both manifest names must match.
Keep the two plugin manifest versions aligned when a plugin targets both hosts.
Keep the version in each host manifest, not in a marketplace entry. The manifests are the release source of truth.
Add a plugin only to the marketplace buckets that should expose it. The two catalogs may contain different plugins and ordering.
Preserve existing marketplace ordering unless a reorder is requested.
Codex marketplace entries must include installation policy, authentication policy, and category. Omit product gating unless explicitly requested.
Reference only paths inside the plugin root and keep manifest paths relative.
Keep top-level skills/<skill-name> entries as real directories because the skills CLI's repository scan skips symlink directory entries.
Codex marketplace plugins need a real plugin-local skills/ subtree. Its current cache installation does not preserve symlinks, so materialize and verify a wrapper if one is required for a canonical standalone skill.
Declare apps, MCP servers, hooks, or other host integrations only when their real companion configuration exists.
Do not leave placeholder metadata or unfinished TODO markers in manifests.

Portable skills

Prefer the common name and description frontmatter fields.
Describe capabilities rather than naming provider-specific tools.
Avoid host-specific frontmatter, substitutions, channels, and directives in shared skills.
Put genuinely host-specific behavior in host-specific configuration or a host-specific skill instead of branching throughout a shared skill.
Keep each SKILL.md concise and place detailed material in nearby references or scripts.

Verification

Parse every changed JSON file.
Confirm marketplace source paths resolve to the intended plugin directories.
Confirm plugin names and versions agree across applicable catalogs and manifests.
Run python3 scripts/validate_repo.py before committing a plugin change.
Run python3 -m unittest tests/test_handoff.py -v after changing the Handoff skill.
Run the relevant Codex and Claude validators when available. Report any validator that could not be run.
Keep README.md accurate when repository structure or installation changes.

Releases

Version each plugin independently with semantic versioning.
Update both host manifests and the plugin changelog in the same change.
Tag releases as <plugin-name>--v<version>; never move or reuse a release tag.
Create releases only from the default branch after validation passes.
Follow RELEASING.md for the full release process.

Do not install, publish, commit, push, or release changes unless explicitly requested.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

It worked
Partly
It didn't

What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

Check your setup, free