skills
AGENTS.md0 starsChanged 17 days agoMITView on GitHub
Project conventions and standards for AI-assisted development. This is a public, third-party Claude Code plugin marketplace providing language-agnostic AI / agentic workflow plugins for DX efficiency. Hosted on GitHub (tony/skills), not affiliated with or endorsed by Anthropic or OpenAI. - Commit messages, pull request descriptions, Markdown, docstrings, and source comments: .github/WRITING.md - Python in plugin scripts, shared/, and scripts/: .github/PYTHON.md - The gates, plugin layout, skills, and manifests: this file Each is the single home for its subject. Where a…
- Commits and pushes
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 33,315 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 repository113 other files it gives its agents.
- action-worktreeSkill
- action-worktreesSkill
- agent-messaging-session-relaySkill
- business-case-study-internalSkill
- business-case-study-publicSkill
- business-pr-releaseSkill
- business-report-leadershipSkill
- business-report-org-wideSkill
- business-researchSkill
- changelog-refreshSkill
- changelog-rewrite-aggressivelySkill
- changelogSkill
- commitSkill
- disk-reclaimSkill
- diskSkill
- disk-usageSkill
- double-check-alignSkill
- double-checkSkill
- gh-create-issueSkill
- gh-rendered-markdownSkill
- git-branch-redo-from-scratchSkill
- git-branch-soft-reset-and-recommitSkill
- github-actions-bumping-github-actionsSkill
- github-actions-update-actionSkill
- github-actions-update-actionsSkill
- goal-planner-auditSkill
- goal-planner-printSkill
- goal-planner-profileSkill
- goal-planner-synthesizeSkill
- lean-tightenSkill
- lean-trim-commentsSkill
- lean-writingSkill
- merge-pr-merge-manySkill
- merge-pr-merge-oneSkill
- model-cli-agySkill
- model-cli-codexSkill
- model-cli-cursorSkill
- package-updater-update-packageSkill
- package-updater-updateSkill
- package-updater-update-toolchainSkill
- package-updater-updating-packagesSkill
- pr-merge-commitSkill
- pr-refreshSkill
- pr-review-prSkill
- pr-rewriteSkill
- prSkill
- pytest-optimizer-00-scanSkill
- pytest-optimizer-01-benchmarkSkill
- pytest-optimizer-02-planSkill
- pytest-optimizer-03-executeSkill
- pytest-optimizerSkill
- rebaseSkill
- release-bumpSkill
- release-cutSkill
- release-update-downstream-packagesSkill
- repo-skills-deriveSkill
- research-assessSkill
- research-continueSkill
- research-foraySkill
- research-releaseSkill
- The first 60 shown.
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, 8 are distinctive, and 11 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈8
Distinctive · estimate
This author's own choices. Worth a look.
11
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 14
Commit messages, pull request descriptions, Markdown, docstrings, and source comments: .github/WRITING.md
- Distinctive: line 103
Run it on the marketplace directly:
- Distinctive: line 147
Keep new APIs private until a caller outside the module needs them.
- Distinctive: line 148
Add a file only for a durable boundary — a distinct responsibility, independent reuse, or splitting an oversized high-touch module — not …
- Distinctive: line 154
Treat this file like code and prune it.
- Distinctive: line 156
Delete a line whose removal would not cause a mistake.
- Distinctive: line 159
Keep only non-obvious, broadly applicable defaults here.
- Very specific: line 167
Every SKILL.md must have YAML frontmatter with at least name and description
- Very specific: line 173
Never use ! context expansion.
- Distinctive: line 176
Never link outside the plugin.
- Very specific: line 177
Every step that writes human-facing prose links ../../references/prose-rules.md.
- Very specific: line 178
Put deterministic machinery (argument parsing, process control, git plumbing) in a tested script under the plugin's scripts/.
- Very specific: line 183
Never git push unless the user passed --push or asked to push.
- Very specific: line 199
Every plugin directory under plugins/ has this shape:
- Very specific: line 237
Every workflow is a skill.
- Very specific: line 288
Must reference every plugin under plugins/ with a valid source path
- Very specific: line 334
Check before splitting a command in two.
- Very specific: line 339
When a command is genuinely single-platform — WSL virtual disks, findmnt, systemctl — say so in the surrounding prose instead of inventing …
- Very specific: line 367
After the prescribed sections, end with an interactive next-step panel (via AskUserQuestion) where the user can act on the result without …
≈ “Common” is an estimate: at least 1 in 5 of the 42,283 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 — skills
Project conventions and standards for AI-assisted development.
Project Identity
This is a public, third-party Claude Code plugin marketplace providing language-agnostic AI / agentic workflow plugins for DX efficiency. Hosted on GitHub (tony/skills), not affiliated with or endorsed by Anthropic or OpenAI.
Which Policy Applies
- Commit messages, pull request descriptions, Markdown, docstrings, and source comments: .github/WRITING.md
- Python in plugin scripts,
shared/, andscripts/: .github/PYTHON.md - The gates, plugin layout, skills, and manifests: this file
Each is the single home for its subject. Where a rule seems to be stated twice, the file listed above is the one that governs.
Official Documentation References
These docs are the canonical references for the two plugin systems this marketplace targets. Consult them when authoring or reviewing plugin components.
Codex:
- Package your plugin — plugin packaging, marketplace format, local and repo marketplaces, bundled MCP servers and hooks
- Build skills — SKILL.md authoring for Codex
Claude Code:
- Plugins overview — plugin lifecycle, installation, discovery
- Plugin reference — component types, frontmatter schemas, directory structure
- Plugin marketplaces — creating and distributing a marketplace
- Marketplace reference — marketplace.json schema, plugin sources, reserved names
- Skills — skill authoring, SKILL.md format,
$ARGUMENTS - Settings — plugin settings, permissions, scopes
- Sub-agents — agent frontmatter, delegation patterns, tool restrictions
Quality gates
CI runs each check below on every pull request (ruff format as --check);
run them before committing.
Format
CI fails on unformatted files. Drop --check to rewrite them:
$ uv run ruff format --checkLint
$ uv run ruff checkType check
$ uv run ty checkPlugin scripts and shared/ also check against their Python 3.14 floor
(PYTHON.md):
$ uv run ty check \
--python-version 3.14 \
plugins \
sharedTest
Mid loop: unit tests and doctests, then plugin lint, manifest sync, generated-file drift, and description-routing checks. Integration tests exercise owned Git repositories and CLI subprocess workflows in the outer loop.
$ uv run pytest -q \
-m 'not integration' \
&& uv run scripts/marketplace.py lint \
&& uv run scripts/marketplace.py sync --check \
&& uv run scripts/marketplace.py portable --check \
&& uv run scripts/skill_evals.py checkOuter loop and CI: run every test, including integration tests:
$ uv run pytest -qmarketplace.py lint already runs claude plugin validate --strict over the
marketplace and each plugin when the CLI is on PATH (an error under CI).
Run it on the marketplace directly:
$ claude plugin validate \
--strict \
.Then on every plugin:
$ for p in plugins/*/; do claude plugin validate --strict "$p" || exit 1; donePlugin scripts and their tests use only the standard library, so the tests also run on 3.14 with nothing installed but pytest:
$ uv run \
--no-project \
--isolated \
--python 3.14 \
--with pytest \
pytest -q pluginsEnd-to-end install
Installs every plugin into both hosts under a throwaway HOME; needs
claude and codex on PATH. Outer loop only:
$ uv run scripts/e2e.py \
--source local \
--host bothChange Discipline
- Make the smallest coherent change that solves the verified problem; keep unrelated cleanup out of it.
- Reuse an existing file, component, helper, API, or test before adding a new one. Modify in place when the change fits the file's responsibility.
- Keep new APIs private until a caller outside the module needs them.
- Add a file only for a durable boundary — a distinct responsibility, independent reuse, or splitting an oversized high-touch module — not for a single-use helper or a one-line re-export.
Keep Instructions Lean
Treat this file like code and prune it.
- Delete a line whose removal would not cause a mistake.
- Move multi-step procedures into skills, path-specific rules into nested AGENTS.md files, and hard limits into hooks or CI.
- Keep only non-obvious, broadly applicable defaults here. Anything a reader can infer from the code, a manifest, or a linter does not belong.
Plugin Quality Standards
Skill Files
- Every
SKILL.mdmust have YAML frontmatter with at leastnameanddescription - Skills must not hardcode language-specific tool commands (e.g.,
uv run pytest,npm test,cargo test). Instead, reference "the project's test suite / quality checks as defined in AGENTS.md/CLAUDE.md" - Frontmatter
allowed-toolsshould use bare tool names (e.g.,Bash) rather than language-specific patterns (e.g.,Bash(uv run:*)) so skills work across any project - Never use
!context expansion. Codex never expands it, and on Claude Code a command that fails or lacks a grant empties the whole skill without an error. Gather context in a numbered step instead. - Never link outside the plugin; each plugin installs alone.
- Every step that writes human-facing prose links
../../references/prose-rules.md. - Put deterministic machinery (argument parsing, process control, git
plumbing) in a tested script under the plugin's
scripts/; keep judgment in prose. A skill that runs one says its../../scripts/path resolves from the skill's directory (a reference writes../scripts/, from its own directory) to an absolute path written literally in each command. - Never
git pushunless the user passed--pushor asked to push; otherwise finish local and print the push command.--prmeans "open a pull request"; a pull request to act on is a positional argument. A force-push is--force-with-lease --force-if-includes, or--force-with-lease=<ref>:<sha>alone when the expected tip is known: git-push documents--force-if-includesas a no-op beside an explicit<expect>.
scripts/marketplace.py lint enforces the ! and plugin-boundary rules, the plugin layout below, a
500-line ceiling on skill bodies, a contents list on any resource over 100
lines, that every resource is named by some file in its plugin, and that a
Bash grader naming a bundled script also matches it called through a shell
variable (python3 $G sub).
Plugin Directory Structure
Every plugin directory under plugins/ has this shape:
plugins/<name>/
├── .claude-plugin/
│ └── plugin.json # name, description (required)
├── .codex-plugin/
│ └── plugin.json # generated
├── README.md # usage docs, prerequisites, component reference
├── skills/ # skills (skill-name/SKILL.md)
├── references/ # files skills read on demand
├── scripts/ # tested scripts skills run
├── templates/ # files a skill copies into a project (optional)
└── evals/ # eval cases for `claude plugin eval`Hosts also accept agents/, hooks/, .mcp.json, and .lsp.json; no plugin
here ships them, and the plugin reference linked above holds their schemas.
The Codex page linked above documents a root plugin.json as the preferred
entry point. This repo keeps generating .codex-plugin/plugin.json, the
compatibility layout Codex still loads.
.codex-plugin/plugin.json and every skill's agents/openai.yaml (Codex's
presentation and allow_implicit_invocation policy) are written by
scripts/marketplace.py portable and verified by portable --check. Never
hand-edit them; change .claude-plugin/plugin.json or the skill's SKILL.md
and regenerate.
Shared Files
A file several plugins ship lives once in shared/, and shared/vendor.yml
lists the plugins that ship it. portable copies it into each plugin's
references/ under a one-line banner, and portable --check fails when a copy
differs. Edit the file in shared/, never a copy.
Skills Are the Only Workflow Component
Every workflow is a skill; no plugin ships commands/. Codex reads only
skills/, and a skill is invoked the same way from either host:
/slop:deslop in Claude Code, slop:deslop in Codex. A skill's directory
name and its frontmatter name match, or the two hosts invoke it by
different names.
A skill carrying a workflow that only makes sense when the user asks for it by
name, and that nobody chains into a prompt, a goal, or another skill's next
step, sets disable-model-invocation: true; portable mirrors it into Codex's
agents/openai.yaml. That keeps it invocable by name only and never routed to
on the model's initiative, and keeps it out of a routing corpus where it would
crowd skills meant to be discovered.
Claude Code reliably runs a flagged skill only from a slash command that opens
the prompt. It refuses one reached in a follow-up or /goal turn, named in
another command's arguments, or offered by another skill's next-step panel. A
skill users chain that way stays model-invocable, and its description makes an
explicit request the trigger: "Use when a user explicitly wants to …".
Address bundled files by climbing out of the skill directory
(../../references/x.md), never through ${CLAUDE_PLUGIN_ROOT}. Codex performs
no substitution on that variable.
Skill Frontmatter
name(required here) — skill display name; upstream it defaults to the directory name, but this repo's gates expect it written outdescription(required here) — when and how to invoke the skillargument-hint(required when the body consumes$ARGUMENTS) — placeholder Claude shows when the user invokes the skillallowed-tools(optional) — tools usable without a permission prompt; space- or comma-separated string, or a YAML listdisallowed-tools(optional) — tools removed while the skill is activecontext(optional) — set toforkto run in a subagentdisable-model-invocation(optional) — see Skills Are the Only Workflow Componentuser-invocable— defaults to true; never writeuser-invocable: true- Content can reference
$ARGUMENTSto access arguments passed to the skill
allowed-tools grants pre-approval rather than sandboxing: every tool
stays callable either way, so listing tools only skips the permission
prompt for those. Only disallowed-tools removes a tool from the pool.
Marketplace Manifest
Two manifests describe the same marketplace. .claude-plugin/marketplace.json
is hand-maintained and authoritative; .agents/plugins/marketplace.json is
generated from it. Codex prefers the generated one and accepts the Claude
manifest only as a legacy fallback, so both ship and neither host depends on
the other's spelling.
- Must reference every plugin under
plugins/with a validsourcepath - Beyond the Marketplace reference
(schema, plugin sources, reserved names;
claude plugin validateenforces it), every entry needsdescription,version,author, andcategory - Valid categories:
development,productivity,testing,security,design,database,deployment,monitoring,learning
Plugin Versions
A pull request that changes anything under plugins/<name>/ changes that
plugin's version in .claude-plugin/plugin.json. marketplace.py sync
--write copies it into the marketplace entry, and sync --check fails when
they differ. CI runs marketplace.py versions --base <ref>, which names every
plugin whose files changed while its version did not. Generated files under
.agents/ and plugins/*/.codex-plugin/ do not count as a change.
Language-Agnostic Design
A plugin not named for a tool works with any language or framework. Its skills discover project tooling by reading AGENTS.md / CLAUDE.md at run time rather than assuming an ecosystem, and name tools only as examples. Plugins named for a tool (pytest-optimizer, ruff, tailwind, terraform) target that tool and still read the project's own gates.
Portable Shell Examples
A shell command shipped in a skill or reference runs on whatever machine the user has. Either use a spelling that works on both GNU coreutils and BSD/Darwin, or show both forms and label them.
The differences that matter here:
sed -itakes an optional suffix on GNU and a mandatory one on BSD/Darwin, and the two spellings are mutually exclusive. Shipsed -ifor GNU andsed -i ''for BSD/Darwin.- In
sedbasic regular expressions,\+,\?, and\|are GNU extensions. Write-Ewith a bare+,?, or|— that spelling is identical on both. du --files0-from,find -printf,numfmt,tac,nproc,shuf,base64 -w,readlink -f,stat -c, anddate -dare GNU-only with no BSD/Darwin flag to swap in. Reach for a different construct, not a different flag.- macOS ships bash 3.2, so
mapfile,readarray,declare -A, and${var,,}are unavailable there regardless of which coreutils are installed.
Check before splitting a command in two. xargs -r, xargs -0,
sort -V, du -sch, find -print0, head -c, and POSIX date
format specifiers all work on BSD/Darwin, so a second variant for
those is noise. xargs -a and xargs -d are the GNU-only ones.
When a command is genuinely single-platform — WSL virtual disks,
findmnt, systemctl — say so in the surrounding prose instead of
inventing an equivalent.
Orchestration Plan Convention
Skills with analysis-then-execute phases should include a portable "Orchestration Plan" section before execution begins. This section:
- Opens with this prelude, verbatim: "Enter plan mode before the first
edit. In Claude Code call
EnterPlanMode; in Cursor, Codex, or Gemini use/planorShift+Tab. Where plan mode is unavailable, present the plan as text." - Defines what the orchestration plan should contain (skill-specific checklist)
- Requires presenting the plan and waiting for user approval
- Instructs exiting plan mode before execution
Output Contract Convention
Skills that produce structured output for users declare their sections in a fixed order. When several skills in a plugin share the output pattern, the template lives in one reference file.
- A hero block is allowed at the top (1–4 lines,
⚠/✓prefix or short summary; no prose paragraphs). - Body sections appear in a declared fixed order with verbatim level-2 headings. No invented sections.
- After the prescribed sections, end with an interactive next-step panel
(via
AskUserQuestion) where the user can act on the result without composing a follow-up command. Skip the panel only when the skill is already running inside plan mode. Where no question tool exists (Codex, headless runs), print the options as a plain list and stop. - A halted run prints one result sentence, then what the user must do.
Completed goal-planner handoffs may omit empty sections and end after the
artifact, compact status, and material gaps. They need no next-step panel;
ask only for a decision needed to finish the requested handoff.
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
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.

