turen-context
Audits, places and maintains the AGENTS.md files that coding agents load while developing TurenOS, the one-line CLAUDE.md shims beside them that let Claude Code read them, and the frontmatter of repository skills. Every rule is checked by reading the code it describes (symbols, commands, flags, invariants and "not wired"/"only" claims), and a small checker proves what a script can, such as load budget, parent pointers, cited paths and scripts, the CLAUDE.md shims and skill frontmatter. Covers how Codex, Claude Code, OpenCode and TurenOS load instruction files, what belongs in one, and when an area deserves its own. Use it when adding, editing, splitting or moving any AGENTS.md, CLAUDE.md or skill, when an agent keeps missing a repo convention, when a package gains its own commands or gotchas, or for a periodic audit. Not for docs/ (use turen-documentation), and not for how the TurenOS product loads its users' instruction files.
- License 许可
- MIT
- 最近更新
- 2026-11-13
- Stars
- ★ 8
- Forks
- 0
01 前言 Front Matter
- name
- turen-context
- description
- Audits, places and maintains the AGENTS.md files that coding agents load while developing TurenOS, the one-line CLAUDE.md shims beside them that let Claude Code read them, and the frontmatter of repository skills. Every rule is checked by reading the code it describes (symbols, commands, flags, invariants and "not wired"/"only" claims), and a small checker proves what a script can, such as load budget, parent pointers, cited paths and scripts, the CLAUDE.md shims and skill frontmatter. Covers how Codex, Claude Code, OpenCode and TurenOS load instruction files, what belongs in one, and when an area deserves its own. Use it when adding, editing, splitting or moving any AGENTS.md, CLAUDE.md or skill, when an agent keeps missing a repo convention, when a package gains its own commands or gotchas, or for a periodic audit. Not for docs/ (use turen-documentation), and not for how the TurenOS product loads its users' instruction files.
02 资源文件 11
- 脚本scripts/check.test.ts5.7 KB
- 脚本scripts/check.ts2.7 KB
- 脚本scripts/lib/claude.ts2.4 KB
- 脚本scripts/lib/commands.ts2.9 KB
- 脚本scripts/lib/findings.ts538 B
- 脚本scripts/lib/git.ts354 B
- 脚本scripts/lib/instructions.ts3.0 KB
- 脚本scripts/lib/markdown.ts980 B
- 脚本scripts/lib/paths.ts3.9 KB
- 脚本scripts/lib/repo.ts3.1 KB
- 脚本scripts/lib/skills.ts3.3 KB
03 SKILL.md 正文
turen-context
AGENTS.md files are instructions for the coding agents (Codex, OpenCode, Claude Code, TurenOS and others) that developers use to build TurenOS. They are harness configuration: loaded into every session, paid for in context, and followed as rules. They are not documentation. AGENTS.md is the one format every agent shares, so rules are written only there; each CLAUDE.md exists only to import the AGENTS.md beside it. Run commands from the repository root; Bun is the only prerequisite.
A rule an agent follows but the code contradicts does more harm than no rule, so every rule is verified against the code. The default is diagnose, then propose, then edit only after the user approves.
How agents load AGENTS.md
As of 2026-09-25, from each tool's documentation:
| Agent | Loads at session start | Loads deeper files | Limit |
|---|---|---|---|
| Codex | AGENTS.md from the root down to the working directory, concatenated, deeper files last |
never | stops adding files once the chain reaches 32 KiB (project_doc_max_bytes default) |
| Claude Code | CLAUDE.md (never AGENTS.md) in the working directory and every folder above it, plus its @ imports |
CLAUDE.md when it reads a file in that subtree |
about 200 lines per file for good adherence |
| OpenCode | AGENTS.md, walking up from the working directory; CLAUDE.md only as a fallback |
not documented | none documented |
TurenOS's own loaders, inherited from OpenCode, stack every AGENTS.md from the working directory up to the project root and read CLAUDE.md only when no AGENTS.md exists anywhere in that chain, so the shim never loads twice (packages/forge/src/session/instruction.ts, packages/core/src/instruction-context.ts). The legacy loader also attaches deeper files when a file is read. If a tool's behavior matters to a decision, re-check its current docs.
What follows:
- Rules every change must follow go in the root file. It's the only file every agent loads wherever a session starts.
- A nested file holds only what is true in its subtree and not above it. Restating the root costs budget twice and lets copies drift. A convention that differs between packages lives in each package's file, never as a root rule one package silently breaks.
- Every nested file is named by an ancestor, normally its parent, with a line like "follow
tools/AGENTS.mdwhen working intools/". Codex sessions started above the folder learn it exists only from that line. A pointer is prose: no agent loads a file because a line names it. - Each root-to-file chain stays under 32 KiB, ideally about 26 KiB. Past the budget, Codex drops the deepest, most specific instructions.
- Every
AGENTS.mdhas a siblingCLAUDE.mdwhose only line is@AGENTS.md, the root included. Claude Code loads onlyCLAUDE.mdfiles and their@imports, so without the root shim it sees none of the rules, and without a nested shim it never loads that folder'sAGENTS.md, whatever rule 3's pointer says. With the shim, Claude Code loads the nested file when it reads a file in that subtree. Don't add rules to aCLAUDE.md, where only Claude Code sees them. Codex ignoresCLAUDE.md, and TurenOS and OpenCode read it only where noAGENTS.mdexists, so the shims never load twice. - Wrap
@mentions in backticks. Claude Code treats a bare@pathor@scope/packageas a file import.
Repository skills live in .agents/skills/<name>/SKILL.md, which Codex and OpenCode discover natively. Claude Code never looks there and finds a skill only through a pointer line in the root AGENTS.md, so every skill needs one. A skill's frontmatter follows the Agent Skills specification: name matches the folder and uses only lowercase letters, digits and single hyphens (at most 64 characters), and description says in the third person what the skill does and when to use it (at most 1024 characters). Keep the frontmatter valid YAML. An unquoted value can't contain : , so reword it or quote the value; Codex, OpenCode and TurenOS retry such a value quoted, but stricter parsers reject the skill. Vendored AGENTS.md files (for example under tools/*/vendor/) belong to upstream projects: they load for agents in those folders, but don't grade or edit them.
What belongs in an AGENTS.md
Keep:
- Commands agents run repeatedly: build, test, typecheck, lint, codegen, with the exact string and the folder it runs from, for example: run
bun run generatefrompackages/client. - Conventions the code doesn't show: "don't extract single-use helpers", "tests run from the package folder, never the root".
- Gotchas that bit before: "shells inside another Electron app inherit
ELECTRON_RUN_AS_NODE=1". - Local scope rules: what is generated, vendored or legacy in this subtree, and how to change it instead.
- One-line pointers to the docs page, spec or nested
AGENTS.mdwith the detail.
Leave out:
- General programming advice, and anything
ls, the formatter or the linter already shows. - Documentation: architecture explanations, "current gaps", design backlogs. Link the
docs/page instead; if the page doesn't exist, the explanation belongs indocs/, not here. - History ("we switched because...", "formerly", "was removed"). State the current rule.
- Rules tooling can enforce. A lint rule, test or CI check beats a sentence; keep one line saying why the check exists.
- Personal preferences and secrets.
Verifying a file
Read each file line by line and check every claim against the code, the way the turen-documentation skill checks a page:
- Symbols, types and APIs: grep for them and read the definition. A renamed service or helper (
makeRuntime,Effect.forkDetach) makes the rule wrong even if the file still reads well. - Commands: confirm the script exists in the
package.jsonof the folder the rule says to run it from, and that the flags it passes still exist. - Flags, env vars and config keys: find where they're read and what their default is.
- Invariants and "how it works" claims: read the code path and its tests.
- "Not yet wired", "only", "never", "all": grep for registrations and callers across the repository. "Every module does X" is usually false; say "new modules do X".
- Pointers: open the linked docs page or nested file and confirm it still says what the rule relies on.
Prefer fixing a stale claim to deleting it when the rule still applies. Record a code bug found along the way separately; don't encode the bug as a rule.
Then run the checker for what a script can prove:
bun .agents/skills/turen-context/scripts/check.ts
It reports each AGENTS.md with its lines, bytes and chain bytes, and flags: chains over or near the 32 KiB budget, files over 200 lines, nested files no ancestor names, bare @ mentions, backticked paths that don't exist, package-script commands no package.json defines (or defines elsewhere), broken links, a missing or extended CLAUDE.md shim beside any AGENTS.md, and skills whose frontmatter isn't valid YAML, breaks the name or description rules, or that the root AGENTS.md doesn't name. Errors mean a file doesn't load or cites something that doesn't exist. Notes are tokens that may not be paths (package names, routes, repo slugs); judge each one.
Grading a file
Give each graded file a verdict: keep, edit (list the lines), split (move subtree content into a nested file), consolidate (merge into the parent and delete), or delete.
- It loads. The load rules hold and the chain fits the budget.
- Every claim is true, verified against the code as above.
- It's concrete and terse. Bullets, real paths and commands, no filler. Save
NEVER/MUSTfor the few rules whose violation is expensive. - It's the only copy. Each rule lives in the deepest file where it is true; grep the other
AGENTS.mdfiles for repeats. A contradiction between files is a bug even when both read well. - It fits. Root under 200 lines; nested files aim for under 80. Use headings such as
## Commands,## Conventionsand## Gotchas.
Placing new files
Read the area first: its package.json scripts, build setup, generated or vendored code, and recent history (git log --oneline --since="6 months ago" -- <folder>, looking for repeated fix or revert commits). Propose a nested file only when the area has at least one of:
- commands or tooling that differ from the root (its own scripts, a different language, a separate build);
- generated, vendored-adjacent or legacy code with rules for changing it;
- a gotcha that repeated fix or revert commits show agents keep hitting;
- conventions a new agent couldn't derive from the code.
Size and churn alone are not enough. Moving content deeper frees budget in every other chain, but Codex sessions started above the folder then see only the parent's pointer. Move a section down when it applies to one area; keep it in the root when changes elsewhere must obey it.
For each proposal, give the path, a 3 to 6 bullet draft, why the parent can't hold it, the parent pointer line, and the resulting chain size. Every new AGENTS.md gets a sibling CLAUDE.md containing only @AGENTS.md.
Workflow
- Read and verify each file against the code, then run the checker.
- Report in the format below, and stop. Offer to apply the edits.
- After approval, make targeted edits (never a wholesale rewrite), create approved files with their parent pointer line and
CLAUDE.mdshim, and confirm before deleting any file (and its shim). Re-run the checker until it reports no errors.
Report format
# AGENTS.md audit
## Load problems (<n>)
- <file>: <what doesn't load and for which agent>. Fix: <one line>
## Files (<n> graded, <m> claims checked)
### <path> - <verdict>
- <line>: <what it says> — <what the code shows, path:line>
- Suggested change: <one line>
## Proposed files (<n>)
### <path>
Why: <what the parent can't hold>
Parent pointer: "<line to add>"
Chain after: <bytes> B
Draft:
- <bullet>
## Across files
- <repeats, contradictions, missing parent pointers>
## Next step
<"Apply these edits?" / "Create the proposed files?">
Keep the report terse. A file with no findings gets one line: "keep: no issues".
04 同仓库更多 Skills
vigil-skill
暂无简介
effect
Work with Effect v4 / effect-smol TypeScript code in this repo
turen-documentation
Writes, updates, moves or audits TurenOS documentation by reading the code it describes. Every claim on a page (defaults, limits, flags, paths, behavior, failure modes) comes from the implementing source, its registrations and tests, never from memory or another page. Documentation is centralized in docs/ sections (architecture, systems, providers, operations, development, experimental, assets); READMEs are short entry points, AGENTS.md files point into docs/, contracts stay in specs/, prototypes in mockups/, and the systems catalog indexes every system page. Covers TurenOS branding, where a page goes, page conventions, a code-first audit method for wrong claims, contradictions and undocumented systems, a link checker and a link-preserving page mover. Use it whenever a change adds, edits, moves or reorganizes documentation, documents a system, package or feature, follows a code change that docs describe, or audits the docs.
turen-diff-documentation
Checks TurenOS documentation against one branch or pull request diff. A script maps the diff to the Markdown it can make wrong (docs/ pages, specs, READMEs and AGENTS.md files that cite a changed, deleted or renamed file, or name an env var, CLI option, export or constant the diff removed or changed) and lists new env vars and CLI options nothing documents; the agent then reads the diff for behavior changes no name reveals and verifies each affected page, and every docs edit in the diff, against the new code. Use it before opening or merging a PR, when reviewing someone else's PR, or when asked whether a change needs docs. Writing and placing the fixes follows turen-documentation; AGENTS.md fixes follow turen-context.