agentleFS
youdotcom-ossyoudotcom-oss/agent-skills/AGENTS.md

agent-skills

AGENTS.md105 starsChanged 3 days agoMITView on GitHub

This repo packages You.com skills and plugin manifests for multiple coding-agent surfaces. Keep changes small, verified, and tied to the requested surface. Before writing code, resolve the task at the FIRST step that holds: NON-NEGOTIABLE FLOOR: none of the steps above may remove any of these, and "minimal" is never a reason to drop them: If a step would require cutting one of these, that step does not apply. Leave exactly one runnable check behind for any non-trivial logic. Mark…

  • 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 32,671 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 repository8 other files it gives its agents.

The file

Show its rules and text

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

14 rules. About 0 are common, 7 are distinctive, and 7 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈7

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 7

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Prefer Bun for TypeScript, scripts, orchestration, and running checks.

    line 8
  2. Very specific:

    Before choosing commands, scan package.json, biome.json, and relevant packages/*/package.json scripts.

    line 10
  3. Distinctive:

    Before writing code, resolve the task at the FIRST step that holds:

    line 16
  4. Distinctive:

    If a step would require cutting one of these, that step does not apply.

    line 32
  5. Very specific:

    Leave exactly one runnable check behind for any non-trivial logic.

    line 34
  6. Distinctive:

    Read these config files before changing style rules.

    line 40
  7. Very specific:

    Read existing code before editing.

    line 44
  8. Distinctive:

    Treat generated or copied skill/package files as release artifacts unless the task is explicitly about them.

    line 45
  9. Distinctive:

    Do not inline MCP configs into shared manifests unless the host specifically requires it.

    line 46
  10. Very specific:

    Keep marketplace plugins[].version pegged to the paired plugin.json version.

    line 47
  11. Very specific:

    Run again with apply_versions=true and publish_artifacts=false to commit version bumps.

    line 58
  12. Very specific:

    After the version-bump commit lands on the branch, run publish-only with apply_versions=false and publish_artifacts=true.

    line 59
  13. Very specific:

    If a registry already succeeded and a retry should skip it, disable the matching publish toggle: publish_npm or publish_clawhub.

    line 60
  14. Distinctive:

    Before final handoff after edits, run the smallest relevant checks plus any requested full checks.

    line 68

≈ “Common” is an estimate: at least 1 in 5 of the 41,581 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

Agent Instructions

This repo packages You.com skills and plugin manifests for multiple coding-agent surfaces. Keep changes small, verified, and tied to the requested surface.

Tooling discovery

  • Prefer Bun for TypeScript, scripts, orchestration, and running checks. Use Bun to trigger Python and TypeScript tooling unless an existing script says otherwise.
  • Bun MCP docs: https://bun.com/docs/mcp
  • Before choosing commands, scan package.json, biome.json, and relevant packages/*/package.json scripts. Do not guess command names.
  • Root checks currently flow through Bun: bun test, bun run check, bun run check:types, bun run check:ts, bun run check:package.
  • Package checks often differ. Use the package script in packages/<name>/package.json for package-scoped work.

Minimal-implementation directive

Before writing code, resolve the task at the FIRST step that holds:

  1. Does this capability need to exist for the stated task? If it is speculative, do not build it. Say so in one sentence and stop.
  2. Does something already in THIS codebase do it? Reuse it. Read before you write; re-implementing a helper that lives three files over is the most common waste.
  3. Does the standard library or the runtime/platform already do it? (<input type="date">, a DB unique constraint, a CSS rule.) Use it.
  4. Does an already-installed dependency do it? Use it. Do not add a new dependency for something a few lines cover.
  5. Can it be one clear expression? Write the one expression.
  6. Otherwise: the smallest code that fully handles the task.

NON-NEGOTIABLE FLOOR: none of the steps above may remove any of these, and "minimal" is never a reason to drop them:

  • input validation at trust boundaries (anything crossing a process, network, file, or user edge),
  • error handling that prevents data loss or silent corruption,
  • authn/authz and other security checks,
  • accessibility for anything a human interacts with.

If a step would require cutting one of these, that step does not apply.

Leave exactly one runnable check behind for any non-trivial logic. Mark deliberate shortcuts with a MINIMAL: comment naming the ceiling and the upgrade path, so "later" is greppable instead of forgotten.

Style enforcement

  • TypeScript, JSON, and Markdown formatting/linting are governed by biome.json plus tsc.
  • Read these config files before changing style rules. Keep only conventions not enforced by tools in this file.

Workflow

  • Read existing code before editing. Prefer Read, Grep, and Glob for exploration.
  • Treat generated or copied skill/package files as release artifacts unless the task is explicitly about them.
  • Do not inline MCP configs into shared manifests unless the host specifically requires it; users choose keyless, API-key, OAuth, MPP, or x402 setup by need.
  • Keep marketplace plugins[].version pegged to the paired plugin.json version.
  • For PR review work, use gh when available and check PR comments, reviews, code scanning alerts, and inline comments.
  • Conventional commits only: feat:, fix:, refactor:, docs:, chore:, test:, ci:.

Release workflow

The GitHub Actions UI runs Semantic Release manually:

  1. Open Actions -> Semantic Release -> Run workflow.
  2. First run with apply_versions=false and publish_artifacts=false; inspect the release-plan artifact.
  3. Set base_ref to the intended comparison point. HEAD~1 only sees the last commit; an older base may bump every changed skill, plugin, npm package, and ClawHub package since that ref.
  4. Run again with apply_versions=true and publish_artifacts=false to commit version bumps.
  5. After the version-bump commit lands on the branch, run publish-only with apply_versions=false and publish_artifacts=true.
  6. If a registry already succeeded and a retry should skip it, disable the matching publish toggle: publish_npm or publish_clawhub.
  7. A publish run ends with a dated GitHub release: tag v<UTC date>-<short sha> (for example v2026.09.16-411b7af) at the release commit, with auto-generated notes. GitHub Releases use this dated format; the semver bumps remain internal to npm/ClawHub package versions.

Verification

  • Non-trivial TypeScript/script change: at least bun test <target> and bun run check:types.
  • Formatting/linting: bun run check:ts for Biome, bun run check:package for package manifests.
  • Skill content: bun test tests/validate-skills.spec.ts.
  • Before final handoff after edits, run the smallest relevant checks plus any requested full checks. Report known pre-existing warnings separately.

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.