agentleFS
Sign inStart free
ajittaajitta/know-your-unknowns/AGENTS.md

know-your-unknowns

AGENTS.md2 starsChanged 15 days agoMITView on GitHub

Know Your Unknowns packages eleven skills and two Claude Code agents. The owner writes in Korean; write repository files in English and preserve existing records and translations. README.md and README.ko.md are the only README languages and must keep matching structure. Run from the repository root: After merging the versioned change with passing CI, an annotated tag unknowns--vX.Y.Z triggers .github/workflows/release.yml. It checks the tag, generated output, tests, and zip manifest versions before attaching both committed zips with release notes from the…

  • 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,774 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 repository12 other files it gives its agents.

The file

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

3 rules. About 0 are common, 2 are distinctive, and 1 is very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈2

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 1

    Very specific

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

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Run from the repository root:

    line 7
  2. Very specific:

    Follow .claude/rules/skill-writing.md for skill and agent prose.

    line 26
  3. Distinctive:

    Keep console messages ASCII.

    line 29

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

Know Your Unknowns packages eleven skills and two Claude Code agents. The owner writes in Korean; write repository files in English and preserve existing records and translations. README.md and README.ko.md are the only README languages and must keep matching structure.

Commands

Run from the repository root:

python3 tools/package.py
python3 tools/package.py --check
python3 -m unittest discover -s tests -v
claude plugin validate --strict plugins/unknowns
claude plugin validate --strict .
python3 scripts/build-skill-zips.py

Layout and editing rules

  • Source skills live in skills/. Each SKILL.md is self-contained: there are no shared reference files. Deliverables are Markdown in the conversation.
  • Claude Code agent sources live in claude-code/agents/. The plugin ships no hooks or executable code. Only Markdown, YAML, JSON, SVG, LICENSE, and NOTICE files are allowed, plus one PNG: .claude-plugin/icon.png, the Claude listing icon. SVG assets are for the OpenAI listing.
  • plugin-manifest.json is the source manifest. packaging/ contains the shipped README, the Claude listing icon (icon.png), and OpenAI interface fields and SVG assets.
  • plugins/unknowns/, releases/know-your-unknowns.zip, releases/know-your-unknowns-openai.zip, and plugin-release.json are generated and committed. Edit sources and run tools/package.py; never edit generated output by hand.
  • .claude-plugin/marketplace.json points only to ./plugins/unknowns. Tests, docs, and evals stay at the repository root and are never installed.
  • At an unchanged plugin version, tools/package.py updates plugin-release.json for changed shipped content only while CHANGELOG.md has a non-empty ## [Unreleased] entry; otherwise bump the version before rebuilding, and always regenerate before running --check.
  • Follow .claude/rules/skill-writing.md for skill and agent prose. Preserve trigger phrases and method steps.
  • Text files use LF. Write UTF-8 bytes or explicitly request LF on Windows. Release zips use ZIP_STORED, fixed timestamps and modes, and Unix create_system for byte reproducibility.
  • CI runs ordinary package tests and strict plugin/marketplace validation. Keep build tools portable to Windows and quote paths containing spaces or dollar signs. Both agents inherit every tool; agent and skill text carries no tool lists, read-only contracts or other guard prose (.claude/rules/skill-writing.md rule 17). Rule 0 of that file is the plugin's purpose: three cells of what the user and the AI know (adapted from the Johari window's Blind, Hidden and Unknown panes; shipped text says them in plain words: what the user does not know and the AI does, what the AI does not know, what neither knows), in any domain, judged by the outcome rather than the output; every skill decision follows it.
  • Keep console messages ASCII; configure stdout and stderr with errors="replace" so legacy Windows consoles cannot crash the packager.

Release

After merging the versioned change with passing CI, an annotated tag unknowns--vX.Y.Z triggers .github/workflows/release.yml. It checks the tag, generated output, tests, and zip manifest versions before attaching both committed zips with release notes from the tag. Never push, tag, or change main unless the user authorizes it.

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.

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.

Check your setup, free