tjmustardtjmustard/eta-skills/AGENTS.md

eta-skills

AGENTS.md1 starsChanged 30 days agoMITView on GitHub

Conventions for any agent or human working in this repo. Do not set version in .claude-plugin/marketplace.json entries or in any plugin.json. Claude Code caches plugins by version; with an explicit version, users receive nothing until the string changes. With no version, every commit is a new version, so /plugin marketplace update eta-skills always delivers changes. make validate fails if a bundle sets version. Do not add a plugin.json (bundles use strict: false, which conflicts with component fields declared alongside one).

Reads credentials

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,542 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 repository13 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- adversarial-agent-hardeningSkill
- article-interviewerSkill
- article-outlinerSkill
- build-walkthroughSkill
- cross-model-judge-evalSkill
- narrated-explainerSkill
- narration-handoffSkill
- page-to-videoSkill
- prompt-engineerSkill
- render-page-to-videoSkill
- tts-narration-buildSkill
- {{name}}Skill

The file

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

3 rules. About 0 are common, 0 are distinctive, and 3 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.
3
Very specific
Tied to their project's names, files or tools. Probably skip.

Common
Distinctive
Very specific

Very specific:
Write the skill. Put long reference material in references/ (linked one level deep from SKILL.md), runnable code in scripts/, fill-in …
line 8
Very specific:
Add ./skills/<skill-name> to a bundle's skills list in .claude-plugin/marketplace.json.
line 9
Very specific:
No credentials or .env files.
line 24

≈ “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

Conventions for any agent or human working in this repo.

Adding a skill

make new name=<skill-name> creates skills/<skill-name>/SKILL.md from template/SKILL.md and prints the bundle entry.
Write the skill. Put long reference material in references/ (linked one level deep from SKILL.md), runnable code in scripts/, fill-in templates in assets/, regression cases and test fixtures in evals/. Create these dirs only when needed. Keep SKILL.md under 500 lines.
Add ./skills/<skill-name> to a bundle's skills list in .claude-plugin/marketplace.json. Every skill must be in at least one bundle.
make validate
make catalog and commit the README change.

Naming

Skill name: lowercase a-z, 0-9, single hyphens, no leading or trailing hyphen, max 64 characters.
Folder name equals the frontmatter name.
description states what the skill does and when to use it, max 1024 characters.
Bundle names: short, lowercase, hyphenated; they are the <bundle> in /plugin install <bundle>@eta-skills.

Personal data and employer material

This repo distributes skills only. Outputs a skill generates (taste-master.md, Living Master Plan files, status reports, drafts) never go here. tools/denylist.txt and .gitignore enforce this; add new patterns to both.
Nothing derived from employer work (Terray Therapeutics, SandboxAQ) goes in this repo, including as examples. Use neutral placeholders.
No credentials or .env files.

Versioning rule

Do not set version in .claude-plugin/marketplace.json entries or in any plugin.json. Claude Code caches plugins by version; with an explicit version, users receive nothing until the string changes. With no version, every commit is a new version, so /plugin marketplace update eta-skills always delivers changes. make validate fails if a bundle sets version. Do not add a plugin.json (bundles use strict: false, which conflicts with component fields declared alongside one).

Tooling

Python 3.11+ via uv. skills-ref is installed from a pinned commit of agentskills/agentskills (no PyPI release; its README says demonstration only).

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