agents md

AI Community

Skill notes

The Cost Model — Why Every Line Matters

AGENTS.md is auto-injected into the agent's context window on every interaction. Unlike docs or skills that load on demand, AGENTS.md permanently occupies context for every task the agent works on in that repo. A bloated AGENTS.md directly degrades agent performance on everything — less room for code, conversation, and reasoning. This means: Prioritize by frequency × impact. Every line must earn its permanent context cost.

Phase 1: Investigate the Project

Before writing anything, understand the codebase. Use focused investigation — don't guess. Mandatory checks: Language & framework — ls the root, read package.json, pyproject.toml, Cargo.toml, go.mod, Gemfile, build.gradle, pom.xml, or equivalent Build & dev commands — Look for Makefile, justfile, Taskfile, CI configs (.github/workflows/, .gitlab-ci.yml), scripts/ directory

Phase 2: Draft the AGENTS.md

Write in imperative, agent-directed prose. Every instruction should be actionable. See references/examples.md for full examples across Rust, Python, TypeScript, Go, and Java projects. Core principle: Be specific and actionable. Don't say "run tests" — say pnpm test --filter <package>. Don't say "follow the style guide" — say "use single quotes, no semicolons, 2-space indent." Sections to Include

Phase 3: Validate Commands

Before presenting the draft, verify that the commands actually work. This catches stale instructions, wrong flags, and missing setup steps. For each command in the AGENTS.md: Try running it (or a dry-run equivalent) in the project directory If it fails, investigate why — wrong tool version? Missing dependency? Wrong working directory? Fix the command or add a prerequisite note

Phase 4: Review & Refine

After validating, check the file against these criteria: Every command is copy-pasteable. No placeholders unless explicitly labeled (like <package-name>). No obvious gaps. If the project has tests, there's a testing section. If it has a linter, there's a lint command. No fluff. Remove anything an agent already knows (what TypeScript is, how npm install works). Only project-specific context. Architecture boundaries are explicit. If modules have import restrictions, say so.

Fluxly profile Runtime and permissions are inferred by Fluxly static checks, not author declarations or runtime test results.
Domain
AI
Author-declared agents
No explicit declaration found; this is not inferred or tested compatibility
Static check
88 / 100 · heuristic scan, not runtime safety proof
Runtime evidence
Not run; no isolated runtime test evidence is currently recorded
Author / version / license
@tomevault-io · no license declared
Token usage
Lean
Setup complexity
Manual integration
External API key
Not required
Operating systems
Docker
Runtime requirements
Python · Docker
Detected file/system behavior
  • Read-only
  • Write / modify
Network behavior
Local-only
Install commands
None (reference only)

Heads up: Tool permissions are not declared; actual access depends on the runtime.

01
Phase 1: Investigate the Project

Before writing anything, understand the codebase. Use focused investigation — don't guess. Mandatory checks: Language & framework — `ls` the root, read `package.json`, `pyproject.toml`, `Cargo.toml`, `go.mod`, `Gemfile`, `build.gradle`, `pom.xml`, or equivalent Build & dev commands — Look for `Makefile`, `justfile`, `Taskfile`, CI configs (`.github/workflows/`, `.gitlab-ci.yml`), `scripts/` directory

02
Phase 2: Draft the AGENTS.md

Write in imperative, agent-directed prose. Every instruction should be actionable. See `references/examples.md` for full examples across Rust, Python, TypeScript, Go, and Java projects. Core principle: Be specific and actionable. Don't say "run tests" — say `pnpm test --filter <package>`. Don't say "follow the style guide" — say "use single quotes, no semicolons, 2-space indent." Sections to Include

03
Phase 3: Validate Commands

Before presenting the draft, verify that the commands actually work. This catches stale instructions, wrong flags, and missing setup steps. For each command in the AGENTS.md: Try running it (or a dry-run equivalent) in the project directory If it fails, investigate why — wrong tool version? Missing dependency? Wrong working directory? Fix the command or add a prerequisite note

04
Phase 4: Review & Refine

After validating, check the file against these criteria: Every command is copy-pasteable. No placeholders unless explicitly labeled (like `<package-name>`). No obvious gaps. If the project has tests, there's a testing section. If it has a linter, there's a lint command. No fluff. Remove anything an agent already knows (what TypeScript is, how `npm install` works). Only project-specific context. Architecture boundaries are explicit. If modules have import restrictions, say so.

05
Phase 5: Improving an Existing AGENTS.md

When improving rather than creating from scratch: Read the existing file first. Understand what's already there before changing anything. Run the investigation phase anyway. The existing AGENTS.md may be stale — compare what it says against actual config files, CI configs, and project structure. Check for staleness. Look for: Commands that reference tools or scripts that no longer exist

06
Phase 6: Nested AGENTS.md for Monorepos

Nested files matter for context efficiency — agents load the nearest AGENTS.md to the file being edited. In a monorepo with 10 packages, a single root file forces every agent interaction to load instructions for all 10 packages. Nested files scope the context to what's relevant. Root — workspace-level commands, shared code style, cross-package rules. Keep it to what applies everywhere. Package — package-specific build/test/lint, conventions unique to this package. Agent editing `packages/web/` gets root + web, not instructions for api or shared.

Discussion

Powered by GitHub Discussions. Sign in with GitHub to comment, react, or subscribe.