terum-skills
AGENTS.md28 starsChanged 58 days agoApache-2.0View on GitHub
You do not run this repo's Claude hooks and nothing auto-loads CLAUDE.md for you. Read this file first, then ./CLAUDE.md, then the document that owns what you are touching. The planning and harness repo for terum-skills, an open-source CLI (npm terum-skills, Apache-2.0) that lets a team share private Claude Code skills through one private git repo, with no server. There is no product source yet. When implementation starts, code lands under src/ in the layout the build spec §3 defines.…
- Commits and pushes
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 33,315 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 repository9 other files it gives its agents.
- desktop/AGENTS.mdAGENTS.md
- eval-reportSkill
- evalSkill
- list-skillsSkill
- search-skillsSkill
- skill-infoSkill
- skill-statusSkill
- sync-skillsSkill
- terum-skillsSkill
The file
We split this AGENTS.md into the rules it gives an agent
6 rules. About 0 are common, 2 are distinctive, and 4 are 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.
4
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 21
Nothing runs anywhere but laptops and the git host: No HTTP client, no server, no daemon, no third-party CLI on the install path.
- Very specific: line 38
Never infer ownership from what happens to be on disk.
- Distinctive: line 54
One active path per behavior: Before writing a function, grep for one that already does the job and extend or replace it in the same change.
- Very specific: line 59
Run with --sandbox workspace-write.
- Distinctive: line 60
Never git push --no-verify.
- Very specific: line 76
Use absolute paths in shell commands.
≈ “Common” is an estimate: at least 1 in 5 of the 42,283 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.
Files
AGENTS.md — loader for non-Claude agents (Codex)
You do not run this repo's Claude hooks and nothing auto-loads CLAUDE.md for you. Read this
file first, then ./CLAUDE.md, then the document that owns what you are touching.
What this repo is
The planning and harness repo for terum-skills, an open-source CLI (npm terum-skills,
Apache-2.0) that lets a team share private Claude Code skills through one private git repo, with
no server. There is no product source yet. When implementation starts, code lands under
src/ in the layout the build spec §3 defines. Until then, "the code" means the spec.
Which document wins
The build spec and decision ledger that drove the original implementation are not tracked in the working tree; they remain in this repository's git history. The invariants below are the rules that hold for code written here, and this file wins over any comment or doc that contradicts it.
Invariants you must hold when you write code here
- Nothing runs anywhere but laptops and the git host. No HTTP client, no server, no daemon,
no third-party CLI on the install path. Shell out only to
gitandgh. One recorded exception:terum-skills appandterum-skills app-updatealso run the platform's own tools to unpack, install and open the desktop app (tar,open, the NSIS installer they downloaded throughgh), andapp-update --applyre-runs this same CLI (process.execPath) as a detached process so the install outlives the app that asked for it — all through theExecseam insrc/lib/runner.ts. No new tool and no network client enters the product. - Every write to the team repo goes through
safeWrite()(build spec §6.0): fetch, hard-reset the clone toorigin/main, re-run a pure mutation, commit, push, retry to a 30-second deadline. A mutation that does I/O, mints an ID, or prompts is a bug. - The guard is the authorization model (§6.0 table): a diff may touch only the paths the caller owns. Do not add a write path that bypasses it.
- Consent is a predicate on the normalized
allowed-toolsset (§5.4approvals). A changed grant hash is no approval.sync --hooknever places an unapproved grant; it announces on stderr and prints nothing else but the reload directive on stdout. - Provenance is the
placementsledger (§5.4). It is the only source of deletable paths. Never infer ownership from what happens to be on disk; never write a marker inside a placed folder; never delete outside~/.terum/skills/quarantine/. - Placement is native and explicit (§7): copy into a temp sibling, rename into place, under
the per-target lock, into the directory the agent path table names for the agent the caller
passed. Never auto-detect agents, never prompt for scope, never write
.agents/skillsin phase 1. - Vendored code keeps its provenance.
src/lib/placer/vendor/skillhub/holds two files copied from iflytek/skillhubcli/src/services/(Apache-2.0):skill-fingerprint.tsandskill-target-lock.ts. Upstream carries no per-file copyright header, so each copy gets an attribution header naming the source path, the pinned commit, the license, and whether it was modified, plus a NOTICE entry (build spec §3). The Claude Code path row is derived from skillhub's profile (both paths are.claude/skills), not copied — its profile factory bundles auto-detect, which is not vendored. Do not vendor its auto-detect, prompt, or in-folder metadata code. - Frontmatter is Agent-Skills-legal (§5.3): top-level
name/description/licenseonly; everything custom nests undermetadata. Skill folder name equals frontmattername. - One active path per behavior. Before writing a function, grep for one that already does the job and extend or replace it in the same change. Never leave two paths doing the same thing.
Gates and sandbox
- Run with
--sandbox workspace-write.--dangerously-bypass-approvals-and-sandboxis banned. - Never
git push --no-verify. Never push at all unless the task says so. - Once
src/exists:npm run lint,npm run typecheck,npm test(vitest, collocated undersrc/**/__tests__/, bare-repo fixtures, no network). Report their real output; a self-reported green gate is a hypothesis the reviewer re-runs. - CI runs the suite on Linux. On Windows some tests skip rather than fail, each with its reason in
the source: anything that creates a symlink is gated on
SYMLINKS_SUPPORTED(src/lib/__tests__/fixtures.ts, a probe that needs Developer Mode or an elevated shell); POSIX mode assertions (0600/0700, executable bits) are guarded byprocess.platform !== 'win32'; and the eval engine's setup hooks, requirement probes andcommand_succeedschecks run under the POSIX shellposixShell()resolves (Git for Windows'sh.exeon Windows), so those cases skip only on a Windows host without Git, and tests that also lean on exec bits or POSIX errno values stay POSIX-only; tests that make an entry unreadable withchmodskip on win32 too, since Windows ignores POSIX mode bits. Repo-relative paths a plan reports (copies,entries[].to) come frompath.relative, so expectations spell them withjoin(...), never a literal/. A skip is not a pass: report the skipped count next to the passed count, and never add a skip to hide a failure that a Linux run would show. - Use absolute paths in shell commands; do not
cd.
Things that look wrong and are not
safeWritehard-resets the clone. Deliberate: no local commit is ever carried forward, so there is nothing to rebase or conflict.publishunder the"pr"policy pushes a branch and exits whenghis missing. Deliberate: a missing tool never downgrades a review gate to a direct push.- A hand-edited placed copy is overwritten on
syncand moved to quarantine. Deliberate: placed copies are generated output, not an authoring surface; the source is what you edit. - The session hook is async and promises no same-session reload. Deliberate: a network pull must never sit in front of session start.
- Handles are per team, not global. Deliberate: it is the only shape in which a second-team collision is recoverable.
metadata.authorisName <email>, never the handle. Deliberate: SkillEvaluator's schema.- The hidden
readmeverb writesREADME.mdin the current clone directly, not throughsafeWrite. Deliberate: it is the GitHub Action's entry point on the host's compute, where there is no~/.terumconfig and the Action itself commits; on a laptop, README regeneration for non-GitHub remotes still happens insidesafeWrite(§9). guard.tsaccepts apreviousAuthorforsynconly, and only for a write that touchesSKILL.mdalone with canonical content unchanged. Deliberate: it is the §5.3 managed-field refresh after a config email or license change; it can never carry a content change.safeWriterunsgit update-index --chmodafter everygit add. Deliberate:git addcopies the on-disk mode only wherecore.filemodeis on, which it is not on Windows, so without it an executable bit set by the mutation never reaches the commit and a mode-only change stages nothing. On POSIX it restates whatgit addalready recorded.remote.tsaccepts a Windows drive path (C:\Users\me\team.git,C:/…,file:///C:/…) as a local remote on every platform and normalizes it tofile:C:/…. Deliberate: a Windows user's local bare repo is a remote like any other, and the one parser must spell it one way.placer.tstreats EPERM from a rename as "destination exists" only after probing the destination. Deliberate: Windows reports EPERM both for a rename onto an existing directory and for a locked one; the probe tells them apart, and without it every replace on Windows failed.
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
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.

