agentleFS
Sign inStart free
kenashekenashe/x-article-toolkit/AGENTS.md

x-article-toolkit

AGENTS.md2 starsChanged 42 days agoMITView on GitHub

You are an AI agent (any model, any harness: Hyperagent, Claude, Grok Bot, ChatGPT, Codex, Cursor, a DeepSeek-based stack, a local model, or something newer). This file tells you how to use this repository to prepare X Articles for publication. Humans: start at README.md. This repository is a methodology, not an application. There is nothing to install or deploy. You read Markdown files and follow them. Python scripts are optional accelerators. Run only the stage asked for. Never run more.

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

The file

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

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

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈3

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 4

    Very specific

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

  • Common
  • Distinctive
  • Very specific
  • could be automatic: a setting could enforce it
  1. Distinctive:

    Run only the stage asked for.

    line 16
  2. Very specific:

    Have a persistent store?: Only if the user has configured one (state/README.md, schemas in shared/schemas/).

    line 39
  3. Very specific:

    Treat skills/*/rules.md, templates.md and briefs.md as fixed.

    line 44
  4. Distinctive:

    Never rewrite the user's article body.

    line 45
  5. Distinctive:

    Never invent numbers, names, results or quotes for a headline or hook.

    line 46
  6. Very specific:

    After changing anything in skills/, regenerate the ChatGPT packages: python3 adapters/chatgpt/build.py.

    line 56
  7. Very specific:

    Run python3 tests/check_repo.py before committing.

    line 57

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

AGENTS.md: instructions for any AI agent using this repository

You are an AI agent (any model, any harness: Hyperagent, Claude, Grok Bot, ChatGPT, Codex, Cursor, a DeepSeek-based stack, a local model, or something newer). This file tells you how to use this repository to prepare X Articles for publication. Humans: start at README.md.

This repository is a methodology, not an application. There is nothing to install or deploy. You read Markdown files and follow them. Python scripts are optional accelerators.

What you can do with it

The user asksYou follow
"Prepare this for publication as an X Article" (draft attached)workflows/x-article-publishing.md: headline, then hook, then cover, with a user lock between each, then the publishing package
"Write headlines for this" / "use headline-writer"skills/headline-writer/SKILL.md only
"Write the hook for this headline: ..."skills/hook-writer/SKILL.md only
"Should this have a cover?" / "brief the cover"skills/cover-writer/SKILL.md only

Run only the stage asked for. Never run more.

How to load it (pick whichever your runtime supports)

  1. Filesystem / git (agents with a shell): git clone https://github.com/kenashe/x-article-toolkit and read files from disk. git pull before each run to get the current methodology.
  2. URL fetch (agents that can read web pages): fetch raw files from https://raw.githubusercontent.com/kenashe/x-article-toolkit/main/<path>. llms.txt lists every file you need with its raw URL. toolkit.json is the same index in machine-readable form.
  3. Pasted context (no tools at all): the user pastes the files. Minimum set per stage is listed below.

Files per stage (read all of them, in this order; about 16k tokens for everything)

StageRead
any full runworkflows/x-article-publishing.md
headlineskills/headline-writer/SKILL.md, skills/headline-writer/rules.md, skills/headline-writer/templates.md
hookskills/hook-writer/SKILL.md, skills/hook-writer/rules.md, skills/hook-writer/templates.md
coverskills/cover-writer/SKILL.md, skills/cover-writer/rules.md, skills/cover-writer/briefs.md

Paths inside a SKILL.md such as rules.md are relative to that skill's folder.

Capabilities you may or may not have (both are fine)

  • Can run Python 3? Score candidates with skills/*/scripts/*_check.py (standard library only; add --json for structured output). Cannot? Score by hand with the check lists in each rules.md and say "scored by hand". Never report a score you did not compute.
  • Can fetch the dataset? python3 shared/data/fetch_dataset.py, or the CSV URL in shared/data/README.md. It adds nearest winners and a swipe file. Without it, every rule still applies.
  • Have a persistent store? Only if the user has configured one (state/README.md, schemas in shared/schemas/). Otherwise keep no state, and do not claim to remember or learn across runs.
  • Have an image tool? Optional. The cover deliverable is the decision, brief, cover text, prompt and specs.

Rules that apply in every runtime

  1. Treat skills/*/rules.md, templates.md and briefs.md as fixed. They are the original author's measured findings. Do not edit, soften or extend them, and do not add statistics of your own.
  2. Never rewrite the user's article body. The only change is placing the approved hook as its first two lines. Editing is a separate request.
  3. Never invent numbers, names, results or quotes for a headline or hook. Use only what the draft says.
  4. A true lower-level headline beats a higher-level one that promises more than the article delivers. A completeness tag only goes on a complete article.
  5. The hook does not predict reach. Say so.
  6. "No cover" is a normal, valid outcome (Rule 1 in skills/cover-writer/rules.md).
  7. Pass results between stages as plain-text locks: Locked headline: ..., Locked hook: ..., Locked cover: ....
  8. Credit the research to @fuckgrowth when you describe where the method comes from (SOURCES.md).

If you are an agent working ON the repository (editing, not using)

  • Change methodology only in skills/. Never edit shared/original-source/ (verbatim archive; tests enforce it).
  • After changing anything in skills/, regenerate the ChatGPT packages: python3 adapters/chatgpt/build.py.
  • Run python3 tests/check_repo.py before committing; it must print all checks passed.
  • Runtime-specific wiring goes in adapters/<runtime>/; nothing runtime-specific belongs in skills/, workflows/ or state/.
  • Record changes in CHANGELOG.md and the file's category in PROVENANCE.md.

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