galicia
AGENTS.md1 starsChanged 7 days agoMITView on GitHub
Keep each skill in a descriptive directory, with its instructions in SKILL.md. Galicia has five root skill directories, shared src/ installer/checker code, templates/ context starters, scripts/ download/measurement utilities, tests/ deterministic checks, eval/ model scenarios and assets/ branding. Read context.md for navigation. Skill prose uses caveman style, exact conditions, no emojis. Generated experiments belong in ignored .scratch/. Keep generated output and temporary experiments out of committed source. Document any new directory convention when introducing it. Galicia requires Node >=22.18. Run pnpm…
- Installs packages
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,439 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 repository17 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- breakdownSkill
- find-rcSkill
- rubberduckSkill
- specSkill
- terseSkill
- breakdownSkill
- breakdownSkill
- find-rcSkill
- rubberduckSkill
- specSkill
- terseSkill
- find-rcSkill
- mobile-web-fixesSkill
- rubberduckSkill
- specSkill
- terseSkill
The file
We split this AGENTS.md into the rules it gives an agent
8 rules. About 1 is common, 3 are distinctive, and 4 are very specific to this project.
≈1
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
- Distinctive: line 7
Keep generated output and temporary experiments out of committed source.
- Very specific: line 13
When adding executable TypeScript, document its exact invocation and prerequisites in the relevant skill.
- Distinctive: line 19
Write code in TypeScript. Use British spelling in documentation and user-facing text.
- Very specific: line 21
Use descriptive kebab-case directory and file names.
- Distinctive: line 25
Use Node's built-in test runner.
- Very specific: line 29
No historical commit convention is prescribed.
- Common: line 35
Read the relevant skill before changing it.
- Very specific: line 41
Read context.md first; load relevant domain context only.
≈ “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.
Files
Repository Guidelines
Project structure and module organisation
Keep each skill in a descriptive directory, with its instructions in SKILL.md. Galicia has five root skill directories, shared src/ installer/checker code, templates/ context starters, scripts/ download/measurement utilities, tests/ deterministic checks, eval/ model scenarios and assets/ branding. Read context.md for navigation. Skill prose uses caveman style, exact conditions, no emojis. Generated experiments belong in ignored .scratch/.
Keep generated output and temporary experiments out of committed source. Document any new directory convention when introducing it.
Build, test and development commands
Galicia requires Node >=22.18. Run pnpm install --frozen-lockfile, pnpm run check for TypeScript, pnpm test for installer/checker behaviour, and pnpm run measure for named-encoding instruction counts. node src/cli.ts init --project PATH starts setup; node scripts/download.ts --help documents pinned downloads. Runtime needs no install/build. pnpm dev starts the Astro marketing site; pnpm build produces website/dist/; pnpm check:website checks Astro types. Website development requires pnpm 12.10.1 and Node >=22.23.4. Root installer runtime stays dependency-free. website/ is a separate pnpm workspace package; its source lives under website/src/, static assets under website/public/. Static checks do not prove cross-model behaviour. Native compiler checks and optional GALICIA_NATIVE_CLI parity test: see native validation. Compiler requires Node >=24 plus platform linker/SDK; generated binaries stay under ignored .scratch/.
When adding executable TypeScript, document its exact invocation and prerequisites in the relevant skill. If package scripts become necessary, define them in package.json and explain their purpose here. For Markdown changes, check links, paths and command examples before submitting.
Homebrew packaging: node scripts/release.ts --tag v0.1.0 --output .scratch/release. Requires Node >=22.18 and tar; tag must match package.json, output must be empty. Generates runtime archive, checksum and formula. Formula/ holds the published formula, generated by the tag release workflow. See distribution guide. CLI init/check perform a bounded public-release lookup; GALICIA_NO_UPDATE_CHECK=1 disables it.
Coding style and naming conventions
Write code in TypeScript. Use British spelling in documentation and user-facing text. Use two spaces for indentation in new TypeScript files, and follow any formatter configuration introduced later.
Use descriptive kebab-case directory and file names. Preserve recognised instruction filenames such as SKILL.md and AGENTS.md. Keep instructions direct, with concrete commands and explicit paths.
Testing guidelines
Use Node's built-in test runner. No coverage threshold established. Add a small test or assert-based self-check for non-trivial executable logic. Cover invalid input and failure handling where relevant. Document how contributors can run each check.
Commit and pull request guidelines
No historical commit convention is prescribed. Use short, imperative messages such as Add skill validation instructions.
Pull requests should explain the change, identify affected skills and report validation performed. Link a related issue when available. Include screenshots only when a visual result needs review.
Agent-specific instructions
Read the relevant skill before changing it. Use the unslop skill when drafting prose. Treat references to "emails" as Apple Mail unless explicitly stated otherwise. Never commit credentials or private user data.
<!-- galicia:start -->Galicia
Read context.md first; load relevant domain context only. Domain terms: docs/Language.md. Decisions: docs/adr/. Specs/tickets: docs/specs/. Local Markdown only. No emojis. Preserve checks, exact contracts and uncertainty. Before consequential ADR work, recommend scoped small-model research/review; spawn only when authorised.
Startup review fallback: run node .galicia/check.ts once per session if no startup hook ran. Metadata flags are review candidates; never delete without explicit user approval. Follow relevant specs to compare implementation when needed; age alone proves nothing. Grilling cadence: read .galicia/config.json, ask user if unset.
<!-- galicia:end -->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.