ai-helpers
AGENTS.md121 starsChanged 12 months agoApache-2.0View on GitHub
Claude Code plugins repository. Plugins live under plugins/. Canonical example: plugins/hello-world/
We split this AGENTS.md into the rules it gives an agent
2 rules. About 0 are common, 0 are distinctive, and 2 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈0
Distinctive · estimate
This author's own choices. Worth a look.
2
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 35
Check for overlaps: before contributing: run /utils:review-ai-helpers-overlap --idea "description".
- Very specific: line 36
Follow existing patterns: Read plugins/hello-world/commands/echo.md for command format.
≈ “Common” is an estimate: at least 1 in 5 of the 36,368 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.
Files
AGENTS.md
Claude Code plugins repository. Plugins live under plugins/.
Structure
plugins/{plugin-name}/
├── .claude-plugin/
│ └── plugin.json # Required: name, description, version, author
├── commands/
│ └── {command-name}.md # Required: at least one command
├── skills/ # Optional
│ └── {skill-name}/
│ └── SKILL.md
└── README.mdCanonical example: plugins/hello-world/
Development Commands
| Command | When |
make lint | Before every commit — validates structure, format, and marketplace registration |
Bump version in plugin.json | Once per affected plugin per PR when modifying commands, skills, hooks, or plugin.json (not README.md or OWNERS). Skip if that plugin is already higher than the base branch tip. |
make update | After version bumps — normalizes plugin metadata and syncs marketplace.json |
make site-build | Before documentation changes — generates and strictly builds the site locally |
make site-serve | Preview the generated site at http://127.0.0.1:8000/ai-helpers/ |
Contributing Rules
- AI reasoning required. Commands must require AI analysis/decisions, not just wrap scripts. If it could be a shell alias or Makefile target, it should not be a plugin command.
- Never reference real people by name, even stylistically. Describe desired qualities explicitly instead.
- Check for overlaps before contributing: run
/utils:review-ai-helpers-overlap --idea "description". - Follow existing patterns. Read
[plugins/hello-world/commands/echo.md](plugins/hello-world/commands/echo.md)for command format; the linter enforces structure. - Use kebab-case for all plugin names, command files, and skill directories.
- Use
.work/{feature-name}/for temporary files (gitignored). - Register all plugins in .claude-plugin/marketplace.json.
- Set author to
"github.com/openshift-eng"inplugin.json. - Add new commands to an existing plugin when they fit its scope, or to
plugins/utils/if no clear parent. Create a new plugin only for a distinct group of related commands.
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 28,693 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 repositoryOne other file it gives its agents.
- .cursor/rules/idiomatic-go.mdcCursor rule
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
Reviews can't be read right now.
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.