DEV Community: DotcomJack

How to pin an agent skill to an exact version

DotcomJack — Thu, 08 Oct 2026 00:01:19 +0000

Pin a skill by a fingerprint of its exact contents, not just by where it lives. Install it at an exact version with a tool that checks the files and records that fingerprint in a lockfile you commit. Then check for changes on purpose, and read what changed before you update. With the mdr tool that is mdr add, mdr outdated and mdr diff.

It matters because these files change. In the registry's own crawl, of 47,724 agent markdown files watched for at least 14 days, at least 19.9% changed on GitHub within 14 days of being collected (19.4% of SKILL.md files). We also looked at five Anthropic skills (skills chosen because they change often): of 75 byte-exact copies of them found in other repositories, 47 (62.7%) were an older version. An agent that loads a skill by its path reads whatever the file says today. The figures and how we measured them are in State of agent markdown, September 2026.

Kind	Watched 14+ days	Changed within 14 days	Share
SKILL.md	42,581	8,272	19.4%
AGENTS.md	2,623	730	27.8%
CLAUDE.md	1,333	309	23.2%
DESIGN.md	634	34	5.4%
Cursor rules	296	36	12.2%
llms.txt	257	106	41.2%

How often agent markdown changed upstream within 14 days of being indexed, by kind (lower bounds; only files watched for at least 14 days count). Registry crawl, data frozen September 27, 2026; method and downloads in the report.

Every command below was run against the live registry on September 27, 2026, and the output is shown as it printed. Install the CLI from the mdr CLI page.

How do I pin an agent skill to an exact version?

Install it at an exact version, and record a fingerprint of its contents (a content hash), not just its path. With mdr, run mdr add owner/repo/skill@version. It installs that version's files from their source commit on GitHub and checks every file against its published fingerprint before writing anything. It records the version, the SHA-256 of SKILL.md and the source commit in mdr.lock. A skill with more than 200 files is refused, and nothing is written. Public skills the registry has indexed, each with its versions, are listed on the SKILL.md page.

$ mdr add anthropics/skills/skill-creator@git:20260225.3d59511 --dir skills/skill-creator
installed anthropics/skills/skill-creator@git:20260225.3d59511  18 files (18 hash-verified)  audit A  to skills/skill-creator

This example installs into skills/skill-creator so every path below is easy to read. Without --dir, mdr installs where your agent loads skills: .claude/skills/<name> by default, or the matching directory for --agent codex, cursor or opencode.

A version label is the version (or metadata.version) in the skill's frontmatter, with a v added when it starts with a digit, or, when it declares none, the commit date and short hash, as here. A declared version can repeat across commits, so when two versions share a label, pin by content hash instead: mdr add owner/repo/skill@sha256:<prefix>. mdr info owner/repo/skill lists the recent versions with their date, commit and audit grade.

Is there a lockfile for agent skills like package-lock.json?

Yes. mdr writes mdr.lock, a small JSON file in the folder you run it from. It records each skill's version label, SHA-256 fingerprint, source commit and install path. Commit it to your repository. mdr install then downloads exactly those contents again and checks them, so it installs them exactly or fails. GitHub's gh skill works differently: it pins to a tag or commit and records a git tree SHA inside each SKILL.md, not in a separate lockfile.

{
  "version": 1,
  "registry": "https://markdownregistry.com",
  "entries": {
    "anthropics/skills/skill-creator": {
      "artifact": "art_hl7wjhua3foziup4",
      "kind": "skill",
      "label": "git:20260225.3d59511",
      "sha256": "ba8bebb2c085444120743af8dc859dd7c2592d6290e93aa5e1c08403109bdce7",
      "commit": "3d59511518591fa82e6cfcf0438d68dd5dad3e76",
      "path": "skills/skill-creator",
      "files": 18,
      "verified": 18,
      "installed_at": "2026-09-27T20:33:01.483Z"
    }
  }
}

The sha256 is the hash of the skill's SKILL.md at that version, and verified counts the files whose bytes were checked before anything was written. If any file does not match, nothing is written at all.

How do I check whether my installed agent skills are outdated?

Run mdr outdated. It lists every pinned skill whose SKILL.md changed on GitHub, with the new version and its audit grade. It exits with status 2 when one did, or when one was removed from GitHub, so an automated build can fail on it. For a public skill, a change to another file that leaves SKILL.md untouched is not detected. mdr verify --min-grade A fails when the registry can no longer find a pinned version or its grade is below the minimum. To see a file's grade before you pin it, paste its GitHub link into the checker.

$ mdr outdated
anthropics/skills/skill-creator  git:20260225.3d59511 to git:20260306.b0cbd3d  audit A  (2026-03-06)  mdr diff anthropics/skills/skill-creator
$ echo $?
2

$ mdr verify --min-grade A
✓ anthropics/skills/skill-creator  git:20260225.3d59511  audit A (>= A)  sha256:ba8bebb2c085

all 1 pinned entry verified at grade A or better

How do I see what changed in an agent skill before I update it?

Run mdr diff owner/repo/skill. It shows the lines that changed in the skill's SKILL.md, from the version you pinned to the latest one, when you are behind. Add two version labels to compare any pair. It does not show the skill's other files, such as scripts. To see those, compare the two source commits: mdr.lock records yours, and mdr info owner/repo/skill lists the short commit hash of each recent version.

$ mdr diff anthropics/skills/skill-creator
anthropics/skills/skill-creator: git:20260225.3d59511 to git:20260306.b0cbd3d  +8 -2
- description: Create new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, update or optimize an existing skill, ...
+ description: Create new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, ...

The long description lines are cut short here; the real output prints them whole, followed by the other changed lines of SKILL.md. Between these two versions, two of the skill's Python scripts also changed upstream (improve_description.py by 51 lines added and 52 removed, run_loop.py by 4 removed), and mdr diff does not show them: run git diff 3d59511 b0cbd3d -- skills/skill-creator in a clone of the skill's repository to see them.

How do I update an installed skill without losing my local edits?

mdr does not merge local edits. mdr update overwrites every file the new version ships, so an edit inside one of them is lost, and it does not delete files, so a file removed upstream stays until you remove it. The safest course is not to edit an installed skill: if you need changes, copy it to a directory you own, under a new name, and maintain that copy. If you have already edited one, move the skill directory aside before updating (remove last time's backup first), run mdr update, then compare the two with git diff --no-index and carry your changes across by hand. mdr install overwrites local edits the same way.

$ rm -rf skill-creator.mine && mv skills/skill-creator skill-creator.mine
$ mdr update anthropics/skills/skill-creator
installed anthropics/skills/skill-creator@git:20260306.b0cbd3d  18 files (18 hash-verified)  audit A  to skills/skill-creator
$ git diff --no-index --stat skill-creator.mine skills/skill-creator
 .../skill-creator}/LICENSE.txt                     |   3 +-
 .../skill-creator}/SKILL.md                        |  12 ++-
 .../skill-creator}/scripts/improve_description.py  | 103 ++++++++++-----------
 .../skill-creator}/scripts/run_loop.py             |   4 -
 4 files changed, 60 insertions(+), 62 deletions(-)

We ran this on September 27, 2026 twice in a row (from 1ed29a0 to 3d59511, then the update shown here to the latest), with an edit to LICENSE.txt carried across after the first and a new edit to SKILL.md before the second: both edits were in skill-creator.mine afterwards and the new install was clean. If mdr update fails, move the directory back. Move the directory rather than copy it: a copy nests inside last time's backup on the next update, and it hides files that upstream removed, which a move lets the comparison show. The comparison lists your edits and every upstream change, including the two scripts mdr diff does not show; drop --stat to see the lines. A file that appears only in skill-creator.mine is either one you added or one upstream removed; mdr info and the source commits tell you which. git diff --no-index exits with status 1 when the two differ, which here is expected. We also tried carrying edits across automatically with a patch made from git history; it lost the edit in several ordinary histories (a second update, a shared lockfile, a squash merge), so we do not recommend it.

mdr, gh skill, or copying the files

GitHub's CLI added gh skill in April 2026, in public preview, with its own pinning, described in GitHub's changelog. Copying a skill's files into your repository is the third option. How they differ:

	mdr	gh skill	Copying the files
Pin to an exact version	Yes: a version label, checked against a SHA-256	Yes: --pin to a tag or a commit	Only by never touching the copy
Where the pin is recorded	mdr.lock, one file for the project	Tracking fields in each SKILL.md	Nowhere
Integrity	Every file checked against its published hash before anything is written	Records the source's git tree SHA and compares it on update	None
See that upstream moved	mdr outdated, when SKILL.md changes (exit 2 for CI)	gh skill update (--dry-run to only check), from the whole directory's tree SHA; pinned skills are skipped	No signal
Read the change first	mdr diff of SKILL.md between any two versions	gh skill preview before installing	Compare by hand
Audit grade on each version	Yes, deterministic checks	Not described	No
Agents it installs for	Claude, Codex, Cursor, opencode	Many, including Copilot, Claude Code, Cursor, Codex and Gemini CLI	Any

Use whichever fits how your team already works. What matters is that the pin records the exact bytes and that an update is a decision you make after reading the change.

Sources

GitHub changelog: manage agent skills with GitHub CLI

Last checked September 27, 2026. The page: https://markdownregistry.com/guides/pin-agent-skills

First published on markdownregistry. The other guides, on AGENTS.md, CLAUDE.md, skill security and where to find skills, are at markdownregistry.com/guides.

DESIGN.md files against the official linter: 1,162 checked

DotcomJack — Wed, 07 Oct 2026 00:03:10 +0000

Most DESIGN.md files keep their design values in the markdown body, not in tokens a tool can check. Of 1,162 DESIGN.md files in public GitHub repositories, 78.1% have no YAML design tokens, which the format leaves optional, though 747 of those still spell out three or more hex colors in their text. Of the 254 with tokens, 88.6% pass the format's own linter with no errors, and only 8.3% with no warnings either.

Linter result	Files	Share of files with tokens
No errors	225	88.6%
No errors and no warnings	21	8.3%
Defines a color that no component refers to	103	40.6%
Writes a typography token as one string, not an object	81	31.9%
A component's text and background fall below 4.5:1 contrast	66	26.0%
A component uses a sub-token the format does not define	47	18.5%
Defines colors, but none named primary	43	16.9%
Has a value that is not a valid dimension (an error)	22	8.7%

The 254 of 1,162 DESIGN.md files in public GitHub repositories that carry design tokens, each read at its latest version in the registry and run through the format's own linter, version 0.4.0, on October 4, 2026. A file can show more than one result. How each was counted is under How we counted.

Counted from the registry's own crawl of public GitHub and checked with the linter from the format's repository, pinned at version 0.4.0, on October 4, 2026.

Two kinds of DESIGN.md

The format published by Google Labs, which marks itself alpha, describes a DESIGN.md in two parts: optional YAML front matter holding exact design tokens (colors, typography, rounded corners, spacing and components), and a markdown body explaining them. When the tokens are there, its repository says they are the normative values and the prose gives the context for applying them.

Most files with the name use only the body. 908 of the 1,162 files (78.1%) hold no YAML at all, as front matter or in a fenced YAML block, which the linter also reads, and its only finding for each is that no YAML content was found. That is allowed, but it moves the values into the markdown body: 747 of those 908 files (82.3%) name three or more hex colors there, in sentences, palette tables or inline code. A model reading the file can use those colors; the linter cannot check them, and the format's export command, which turns tokens into CSS or Tailwind settings, cannot carry them. Many files are also shared templates: the 1,162 files hold only 715 distinct contents, so 447 of them are byte-for-byte copies of another file counted here.

What the linter flags in files with tokens

The 254 files with tokens mostly parse: 225 (88.6%) have no errors. Warnings are another matter, and only 21 files have none. The commonest, by file:

A color no component refers to, in 103 files (40.6%). The rule applies only to files that define components, and skips the standard color families such as primary and surface, so it flags extra colors the components never use.
A typography token written as one string, such as "Inter 48px bold", in 81 files (31.9%). The format's typography type is an object with properties such as fontFamily, fontSize and lineHeight. Version 0.4.0 of the linter reports a string like this one warning per character, so these files can carry dozens of warnings for one mistake; counted by file, it is one.
Low contrast, in 66 files (26.0%): a component whose text color on its background falls below 4.5:1, the WCAG AA minimum the linter checks.
A component sub-token the format does not define, in 47 files (18.5%).
No color named primary, in 43 files (16.9%). The linter's message says an agent will then generate key colors itself, which leaves less of the palette in the file's hands.

The errors

29 files with tokens (11.4%) have at least one error. The commonest is a dimension the format does not accept, in 22 files: the format's dimensions are a number with a px, em or rem unit, and values such as normal for a line height or a bare 0 fail that test. 9 files have a color the linter cannot read as a CSS color, 4 have a reference to a token that does not exist, and 1 has a font weight that is not a number.

Lint your own DESIGN.md

The linter runs with npx and prints its findings as JSON, each with a severity and a message. This is the output, cut to those two fields, from a scratch DESIGN.md with two colors, neither named primary, and a typography token whose line height is normal:

$ npx @google/design.md@0.4.0 lint DESIGN.md | grep -E '"(severity|message)"'
      "severity": "error",
      "message": "'normal' is not a valid dimension."
      "severity": "warning",
      "message": "No 'primary' color defined. The agent will auto-generate key colors, reducing your control over the palette.",
      "severity": "info",
      "message": "Design system defines 2 colors, 1 typography scale.",
      "severity": "info",
      "message": "No 'spacing' section defined. Layout spacing will fall back to agent defaults.",
      "severity": "info",
      "message": "No 'rounded' section defined. Corner rounding will fall back to agent defaults.",

The command exits with status 1 when there is an error, which makes it usable as a check in CI. Pin the version, as here: the format is alpha, and its rules can change between releases. Real DESIGN.md files from other projects are on the DESIGN.md page, and what the file is for is in what DESIGN.md is and how agents use it. To see whether a DESIGN.md on GitHub is already in the registry and how its audit grades it, paste its link into the checker. To start a new one from a file that passes every check the registry runs, use the DESIGN.md starter on mdpantry, which says what to change in it.

How we counted

The registry collects agent markdown from public GitHub repositories and stores every version of each file by the SHA-256 of its content, the same hash a pinned install checks. We took every file named DESIGN.md it holds, read each one's latest stored version, checked its bytes against its hash, and ran the format's linter, the @google/design.md package at version 0.4.0, on a copy of it. A file has no tokens when the linter reports that no YAML content was found, and names hex colors in its text when three or more distinct six- or three-digit hex codes appear anywhere in it. Results are counted by file: a file is counted once for a rule however many findings that rule gives it. Some findings in version 0.4.0 carry no rule name; they are named here by their message, and a typography finding whose property is a number, which is what a token written as a string produces, is counted as a string token. The registry crawls the public repositories it has found that hold agent files, not all of GitHub, so read the shares as describing those repositories.

Sources

Last checked October 4, 2026. The page: https://markdownregistry.com/blog/design-md-files-against-the-official-linter

First published on markdownregistry, where the counts are kept current and the data behind them is public in dotcomjack/state-of-agent-markdown, and the monthly counts are in the registry's reports.

How llms.txt files follow the format: 438 files counted

DotcomJack — Tue, 06 Oct 2026 00:01:16 +0000

Most llms.txt files get the top of the format right and drift below it. Of 438 files named llms.txt in public GitHub repositories, 96.6% open with an H1 and 85.2% follow it with a summary blockquote. But only 30.6% follow the whole structure the llms.txt proposal sets out: in 52.7% of files, at least one section under an H2 heading holds prose, not the list of links the proposal describes.

Rule from the llms.txt proposal	Files	Share
Opens with an H1, the only required section	423	96.6%
Has exactly one H1	394	90.0%
Has a summary blockquote before the first H2	373	85.2%
Uses no headings but the H1 and its H2s	354	80.8%
Keeps every H2 section a list of links	143	32.6%
Follows every structural rule above but the blockquote	134	30.6%

438 files named llms.txt in 331 public GitHub repositories, each read at its latest version in the registry on October 4, 2026, and checked against the format in the llms.txt proposal, v2. How each rule was checked is under How we counted.

Counted from the registry's own crawl of public GitHub, read on October 4, 2026, against the llms.txt proposal as it read that day.

What 438 llms.txt files look like

159 of the files sit at the root of their repository; the rest live in folders such as a documentation site's public directory, where a build publishes them. Almost all of them have structure: 419 (95.7%) divide their content under H2 headings. The median file holds 13 links, and 102 files (23.3%) hold none at all.

The H1 and the blockquote, the part of the format every guide shows first, are where files agree: 96.6% open with the H1 the proposal requires, and 85.2% carry the one-paragraph summary it describes next. 89 files (20.3%) keep a section named Optional.

Where files drift from the format

The proposal describes everything after the summary in two parts: sections of any kind except headings, then sections under H2 headers that are each a "file list", a markdown list whose items are a [name](url) link with optional notes after a colon. Files part ways with it in the second part. Only 143 files (32.6%) keep every H2 section a list of links, 19 of them because they have no H2 sections at all. In 231 (52.7%), at least one H2 section holds paragraphs of prose, which makes the file read like a document with chapters more than a map of links. 84 files (19.2%) also use H3 or deeper headings, or a second H1, which the format does not describe.

None of this stops an agent reading the file: it is markdown either way, and the proposal expects agents to view or search the file and follow its links. What drifts is the predictability the format promises, that a program can find the links by reading the H2 lists alone.

Where the links point

The proposal asks that the links point to content a language model can read easily, and suggests offering a markdown version of each page at the same address with .md appended, or with its extension replaced by .md. Of the 56,557 full web addresses in these files, 6,170 (10.9%) point straight at a .md, .mdx or .txt file. That understates how many reach markdown, because v2 also lets a page point to its markdown version with a link relation, which a count of addresses cannot see.

119 files (27.2%) link mostly by relative path rather than by full address. A relative link is read against wherever the file is fetched from, so it works when the file is served from the site it describes.

Check your own llms.txt

To find H2 sections that are not pure link lists, print the first line in each one that is not a list item opening with a link, skipping indented lines, which continue the item above them. This is the output from a scratch llms.txt with a Docs list (one note wrapped onto a second line, a nested item and an H3), a Pricing section written as prose, and an Optional list:

$ awk '/^#/{s=($0 ~ /^## /)?$0:""; next} s && NF && !/^[-*+] \[/ && !/^[ \t]/{print NR": "s": "$0; s=""}' llms.txt
18: ## Pricing: Acme charges per request, billed monthly.

Each line it prints is a section to turn into a list of links, or to move above the first H2, where the format allows any content but headings. It reads every line as text, so a ## line inside a fenced code block also counts as a heading. Real llms.txt files from other projects are on the llms.txt page, most starred first, and how to add one to a site is in how to add an llms.txt file. To start a new one from a file that passes every check the registry runs, use the llms.txt starter on mdpantry, which says what to change in it.

How we counted

The registry collects agent markdown from public GitHub repositories and stores every version of each file by the SHA-256 of its content, the same hash a pinned install checks. We took every file named exactly llms.txt it holds, leaving out llms-full.txt and other names, read each one's latest stored version, and checked its bytes against its hash; 4 files with no stored version yet were left out. The proposal is written for files served on websites; these are the files as committed to repositories, many of which a build publishes to a site.

A leading byte-order mark was dropped and headings inside fenced code blocks were ignored. A file opens with an H1 when its first non-blank line is a level-one heading. The blockquote counts when a line beginning with > appears before the first H2. An H2 section runs to the next heading of any level. An indented line in it is read as part of the list item above it, and skipped when no item comes before it. The section is a list of links when every other non-blank line is a list item made of a [name](url) link, optionally followed by a colon and notes; it holds prose when a line of text, outside any code block, is not a list item. A code block fails the list test without counting as prose, and a file with no H2 sections counts as keeping every H2 section a list. A file follows the whole structure when it opens with its only H1, uses no other headings but H2s, and keeps every H2 section a list of links; the blockquote is left out of that test because the proposal requires only the H1. A link ends in markdown when its path ends in .md, .mdx or .txt. The registry crawls the public repositories it has found that hold agent files, not all of GitHub, so read the shares as describing those repositories.

Sources

Last checked October 4, 2026. The page: https://markdownregistry.com/blog/how-llms-txt-files-follow-the-format

How projects write Cursor rules: 557 files counted

DotcomJack — Mon, 05 Oct 2026 00:09:36 +0000

Most projects now write Cursor rules as .mdc files in .cursor/rules: 510 of the 557 rule files the registry has collected, against 47 legacy .cursorrules files. Of the .mdc rules, 32.7% load in every chat, 32.2% attach to matching files and 28.8% let the agent decide. And 46 set a narrow file pattern that Cursor ignores, because they also say alwaysApply: true.

Rule type	What the frontmatter says	.mdc files	Share
Always Apply	alwaysApply: true	167	32.7%
Apply to Specific Files	globs set, alwaysApply false or missing	164	32.2%
Apply Intelligently	a description, no globs	147	28.8%
No frontmatter at all	none of the three fields	29	5.7%
Apply Manually	frontmatter with none of the three set	3	0.6%

510 .mdc rule files in 102 public GitHub repositories, each read at its latest version in the registry on October 3, 2026, and sorted by the rule-type table in Cursor's documentation. How each was decided is under How we counted.

Counted from the registry's own crawl of public GitHub, read on October 3, 2026. How Cursor applies each rule type is from its rules documentation, read the same day.

What 557 rule files look like

The single .cursorrules file at a project's root is the older way to give Cursor instructions, and Cursor's rules documentation does not describe it. It is still in 38 of the 127 repositories with Cursor rules here, and 13 of those keep it beside a .cursor/rules folder. The rest write rules as .mdc files, one rule per file.

File counts lean on a few busy repositories: the median repository holds 1 .mdc rule, and the largest holds 52, 10.2% of all of them. Counted by repository instead, the pattern is plainer. 76 of the 102 repositories with .mdc rules (74.5%) have at least one rule that loads in every chat, and 49 (48.0%) have no other kind.

How Cursor decides when a rule applies

Each .mdc rule has three frontmatter fields, and Cursor's documentation gives the result of each combination:

Always Apply: alwaysApply: true. The rule is in every chat, and its globs and description are ignored.
Apply to Specific Files: alwaysApply: false with globs set. The rule attaches when a matching file is in context.
Apply Intelligently: alwaysApply: false, a description, no globs. The agent reads the description and pulls the rule in when it judges it relevant.
Apply Manually: none of the three. The rule is used only when you @-mention it in chat.

The documentation adds that rules in .cursor/rules must use the .mdc extension, and that a plain .md file there is ignored because it has no frontmatter to say how to apply it. 29 of the .mdc files counted here (5.7%) have no frontmatter either, so by that table they apply only when @-mentioned.

The rule that looks scoped but loads everywhere

46 rules, 9.0% of the .mdc files and spread across 11 repositories, set a pattern that names some files, such as apps/web/**, and also set alwaysApply: true. Cursor ignores the pattern when the rule always applies, so instructions written for one part of the code reach every chat. If the rule is meant for those files only, set alwaysApply to false:

---
description: Rules for the web app
globs: apps/web/**
alwaysApply: false
---

To find these rules in your own project, list the always rules and print any pattern they set. The pattern skips an empty globs: line, which Cursor's editor writes and which scopes nothing. This is the output from a scratch folder holding four rules, one of them the case above and one an always rule with an empty globs::

$ grep -l '^alwaysApply: true' .cursor/rules/*.mdc | xargs grep -HE '^globs:[[:space:]]*[^[:space:]]'
.cursor/rules/web.mdc:globs: apps/web/**

A pattern that matches every file, such as **/*, loses nothing when it is ignored, so those are not counted here.

Cursor rules or AGENTS.md

Cursor's documentation lists AGENTS.md as a simple alternative to .cursor/rules: agent instructions in plain markdown, and the place to put them if you prefer plain markdown to frontmatter. Most projects here use both. 110 of the 127 repositories with Cursor rules (86.6%) also hold an AGENTS.md somewhere, though the registry finds repositories by their agent files, so a project with both is likelier to be in it. Which to choose for your own repository is in Cursor rules vs AGENTS.md, and every Cursor rule the registry has collected is on the Cursor rules page, most starred first. To start a new one from a file that passes every check the registry runs, use the Cursor rule starter on mdpantry, which says what to change in it.

How we counted

The registry collects agent markdown from public GitHub repositories and stores every version of each file by the SHA-256 of its content, the same hash a pinned install checks. We took every Cursor rule file it holds, read each one's latest stored version, and checked its bytes against its hash; 1 file with no stored version yet was left out. A file named .cursorrules counts as legacy, and a file ending in .mdc as a rule file. Each .mdc file's frontmatter, the block between the first two --- lines, was read for alwaysApply, globs and description. A field with nothing after it, as Cursor's editor writes, counts as not set unless the lines under it give a value, a missing alwaysApply counts as false, and a quoted "true" counts as true; an inline comment is not part of a value, and an empty frontmatter block reads as Apply Manually. Each file was then sorted by the documentation's table. A pattern of *, **, **/*, *.* or **/*.* counts as matching every file. The registry crawls the public repositories it has found that hold agent files, not all of GitHub, so read the shares as describing those repositories.

Sources

Last checked October 3, 2026. The page: https://markdownregistry.com/blog/how-projects-write-cursor-rules

AGENTS.md and CLAUDE.md in one repo: what 1,203 folders do

DotcomJack — Sun, 04 Oct 2026 17:54:30 +0000

Keep the instructions in AGENTS.md and start CLAUDE.md with an @AGENTS.md line. That is what Claude Code's docs show, and the most common single setup in the 1,203 folders the registry has collected from public GitHub that hold both files: 28.8% use the import, 23.8% a symlink and 3.2% identical copies. Another 8.8% only mention the other file in words, and 35.4% keep two separate files.

How the two files relate	Folders	Share
CLAUDE.md imports AGENTS.md with an @AGENTS.md line	347	28.8%
One file is a symlink to the other	286	23.8%
The two files are byte for byte identical	38	3.2%
One file names the other without an @AGENTS.md import	106	8.8%
Two files that share 80% or more of their lines	51	4.2%
Two files that share 30% to 80% of their lines	60	5.0%
Two files that share under 30% of their lines	315	26.2%

1,203 folders in 869 public GitHub repositories that hold both an AGENTS.md and a CLAUDE.md, each file read at its latest version in the registry on October 3, 2026. How each setup was decided is under How we counted.

Counted from the registry's own crawl of public GitHub, read on October 3, 2026. What Claude Code does with each setup is from its documentation, read the same day.

What the 1,203 folders do

The most common setup, in 28.8% of folders, is the one Claude Code's documentation shows: the instructions live in AGENTS.md, and CLAUDE.md starts with an @AGENTS.md line that pulls them in. 120 of those 347 CLAUDE.md files hold other lines as well, such as instructions for Claude Code only; the other 227 hold the import and nothing else. The two most starred repositories with a folder that uses the import are nexu-io/open-design and bytedance/deer-flow.

A symlink is next, in 23.8% of folders: one file is a link to the other, so both names open the same text. In 228 of those 286 folders CLAUDE.md points to AGENTS.md; in the rest AGENTS.md points to CLAUDE.md. The two most starred with a CLAUDE.md linked to AGENTS.md are code-yeongyu/oh-my-openagent and coreyhaines31/marketingskills. Only 3.2% keep two byte for byte identical copies, which stay identical only until someone edits one of them.

Then come the folders that keep two files. 51 hold two files that share most of their lines, the usual sign of a copy that has started to drift. 315, more than a quarter, hold two files that share under 30% of their lines. 807 of the 1,203 folders are the repository root; the rest sit inside packages and subdirectories. By a repository's stars when it was crawled, the import or a symlink is used about equally below 1,000 stars (51.3% of 811 folders in repositories with under 100 stars; 52.8% of 229 folders in repositories with 100 to 999 stars) and somewhat more often at 1,000 or more (58.9% of 163 folders in repositories with 1,000 stars or more).

What Claude Code reads in each setup

By default, Claude Code reads AGENTS.md only when there is no CLAUDE.md in the working directory or above it, according to When Claude Code reads AGENTS.md. In every folder counted here a CLAUDE.md exists, so by default CLAUDE.md is what Claude Code loads, and AGENTS.md reaches it only through that file, unless the Project instructions setting is changed to read both.

An import. The imported file is expanded and loaded at launch with the CLAUDE.md that names it, and the docs say keeping the import never makes Claude read AGENTS.md twice. Claude Code reads AGENTS.md on its own from version 2.1.277, so the docs say a CLAUDE.md that holds nothing but the import can be removed, or kept if some of your sessions cannot load AGENTS.md directly. 227 of the CLAUDE.md files here hold only the import; before removing one, check that no other CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md sits in the same folder or any folder above it, since that file would then be read instead of AGENTS.md.
A symlink. The docs say to leave it or delete it; either way Claude reads the content once.
A mention in words. A CLAUDE.md that tells Claude to read AGENTS.md works only if Claude decides to open the file. For that file the docs advise deleting it, with the same version and folder caveats as the import, or replacing the sentence with an @AGENTS.md import. 106 folders, 8.8%, fall in this group, which also counts an AGENTS.md that names CLAUDE.md, where that advice does not apply.
Two separate files. Claude Code follows CLAUDE.md, and an agent that reads AGENTS.md follows that file. The AGENTS.md site adds that the AGENTS.md closest to the edited file wins, so a package's own AGENTS.md beats the root one for those agents. In 315 folders the two files share under 30% of their lines.

When a symlink is the wrong choice

On macOS and Linux a symlink works, and Claude reads the instructions once. Claude Code's documentation names two limits on it, in Share one file with other coding tools. Its Edit and Write tools refuse to write through a symlink and send Claude to edit the target instead. And on Windows, creating one needs Administrator rights or Developer Mode, while a clone made without symlink support gets a one-line text file in place of the instructions. Git's own core.symlinks documentation says the same: with the setting false, symbolic links are checked out as small plain files that contain the link text.

So if anyone who clones the repository works on Windows, the docs recommend the import over the symlink. 286 of the folders counted here, 23.8%, depend on a symlink. In the 58 where AGENTS.md is the link, a clone without symlinks gives every agent that reads AGENTS.md a file holding only the link's target path.

Check which setup your repository uses

Git records a symlink with the mode 120000 and a regular file with 100644 (100755 when it is executable), so git ls-files -s shows which you have. grep -n '@' lists every line of a CLAUDE.md that may hold an import, since an import can sit anywhere in a line; one inside a code span or a code block does not count. This is the output from a scratch repository with a symlinked CLAUDE.md at the root and an importing one in web/:

$ git ls-files -s AGENTS.md CLAUDE.md web/CLAUDE.md
100644 c210dd0e847e27d735268681eea5d9f7f922dc99 0   AGENTS.md
120000 47dc3e3d863cfb5727b87d785d09abf9743c0a72 0   CLAUDE.md
100644 6324e0d711ec068444d8cd34b915543eac643443 0   web/CLAUDE.md
$ grep -n '@' web/CLAUDE.md
1:@AGENTS.md

To confirm what Claude Code loaded, the docs suggest running /context in your next session and checking that CLAUDE.md appears under Memory files. To see the files other repositories use, every CLAUDE.md the registry has collected is on the CLAUDE.md page and every AGENTS.md on the AGENTS.md page, most starred first. To start a new one from a file that passes every check the registry runs, use the AGENTS.md starter on mdpantry, which says what to change in it.

How we counted

The registry collects agent markdown from public GitHub repositories and stores every version of each file by the SHA-256 of its content. We took every folder where one repository holds both an AGENTS.md and a CLAUDE.md in the same directory, read each file's latest stored version, and checked its bytes against its hash. 18 more folders were left out because one of the two files had no stored version yet; every file in the folders counted was read and matched its hash. A CLAUDE.md inside .claude/ counts only against an AGENTS.md in that same folder.

Each folder was put in the first group it matched, in this order: identical bytes; a symlink, meaning one file's whole content is a path ending in the other file's name, which is how GitHub serves a symlink's contents; an import, meaning an @AGENTS.md reference in CLAUDE.md (this count does not leave out one written inside a code block); a mention in words, meaning a file under 600 bytes that names the other file, or an AGENTS.md that refers to @CLAUDE.md; and otherwise two separate files, compared by the share of their distinct non-blank lines that appear in both. Two edge cases fall where these rules put them: a CLAUDE.md that imports a different path such as @docs/AGENTS.md counts as a mention in words when it is short and is compared as two separate files when it is longer, and a symlink to an AGENTS.md in another folder counts as a symlink. The registry crawls the public repositories it has found that hold agent files, not all of GitHub, so read the shares as describing those repositories. The full method for the registry's data is in State of agent markdown, September 2026.

Sources

Last checked October 3, 2026. The page: https://markdownregistry.com/blog/agents-md-and-claude-md-in-one-repo

First published on markdownregistry, where the counts are kept current and the data behind them is public in dotcomjack/state-of-agent-markdown.