AGENTS.md speaks UNIX, and you should too

As I learned to use and combine these tools, I built a working environment around them. The next step was to keep that setup reproducible, so I could carry it from one machine to the next. That became my (legacy) Ansible-based dotfiles. Dotfiles are the configuration files behind your shell, editor, and other tools, often stored in hidden files or directories, such as Fish’s ~/.config/fish/config.fish. Collected in a repository with setup scripts, they become a recipe for rebuilding your working environment. I spent hours refining those dotfiles, but I could set up a new system in minutes and adapt the configuration to the machine in front of me. The tools and settings I had refined were ready to use wherever I worked. This was years before today’s coding agents: I was building that environment for myself, with human use at the center. My dotfiles acquired new users, and new contributors For years, the users of that environment were me and the scripts I wrote. Every improvement depended on how much time I could put into finding a tool, learning it, and configuring it. Coding agents changed that relationship: they can help do the work of improving the environment, then use the result themselves. I let my agents recommend better and faster tools for themselves and for me. They have introduced me to tools I had never heard of. They can also inspect configuration, propose changes, run checks, and work through failures. Creating useful dotfiles becomes easier when you can ask for help with the parts you do not yet understand. The benefit goes both ways. A repeatable setup saves me work; it also gives an agent a predictable place to operate. A useful validation command lets me check a change; it also lets the agent catch a mistake before handing that change back. Instructions written once can explain the workflow to the next agent. Agents help improve the dotfiles, and better dotfiles help both of us work more productively. My years on the command line gave us a starting point. Unix gives us a common language Imagine asking an agent to change a Neovim setting. The configuration is text in a file. The agent can find it, read it, edit it, and show me the diff using ordinary tools. Git records the change, and another program can check it. The same interfaces I learned to use are available to the agent. That is the useful part of “everything is a file”: much of a Unix environment is accessible through files, streams, and processes. Within its permissions, an agent can inspect configuration, start a test, read its diagnostics and exit status, or stop a server. It has concrete results to work with. Those tools also compose. One finds things, another filters them, another validates the result. For example, from a Git repository: git ls-files | rg '(^|/)AGENTS\.md$' This is tool composition. Git supplies tracked paths; Ripgrep selects the agent instruction files. Two existing programs cooperate without a custom integration. More involved workflows can become small Python programs, with explicit inputs and recovery logic, instead of ever longer shell one-liners. This is why the quality of a command matters to both of us. Useful errors, meaningful exit codes, structured output where appropriate, and predictable non-interactive behavior make a tool easier to use and combine. A command hanging on an invisible prompt leaves the agent stuck just as surely as it would leave a script stuck. My CLI development guidance records those expectations. Agent platforms can add scheduling, isolation, and remote coordination. For work on a local codebase, though, Unix already provides an extraordinary amount of flexibility. Improving one command can benefit every workflow that uses it. But access to a file does not tell an agent whether it is the right file to change. AGENTS.md explains how this environment works My current dotfiles live in fmind/dot, where I now use chezmoi to manage configuration files and templates, and mise to manage tools, environments, and tasks. They are better suited to how I manage the setup today, but they introduce a distinction an agent needs to understand: the installed configuration and its managed source are different files. Return to that Neovim setting. Editing the installed copy might work immediately, then disappear the next time chezmoi applies the source. My project instructions tell agents where the durable edit belongs, how to validate it, and which existing work to preserve. Unix provides access to both files. AGENTS.md explains which one to change. For that task, a short instruction block could look like this: ## Changing Neovim configuration - Edit the chezmoi source under `dot_config/nvim/`, not `~/.config/nvim/`. - Inspect the Git diff first; preserve unrelated edits and staged selections. - Run the relevant configuration checks and preview the chezmoi diff. - Apply the configuration only when deployment is part of the requested task. The commands alone cannot tell the agent which copy I maintain or whether I asked it to deploy. Those are decisions the instructions make explicit. AGENTS.md is an open Markdown format for project context and instructions, stewarded by the Agentic AI Foundation. It fits naturally here: ordinary text beside the code, pointing toward ordinary tools, reviewable in the same diff. It does not require Unix, and each agent host has its own loading behavior. “Speaks Unix” describes that fit. The repository keeps the environment, its tooling, and its working knowledge together: application settings in dot_config/, shared personal instructions in dot_agents/AGENTS.md, reusable procedures in skills/, and the companion Python CLI in dot/. The repository layout covers the rest. Keeping every procedure in AGENTS.md would make it a manual for the entire machine. Agent Skills provide a separate, complementary format: a directory with a SKILL.md entrypoint and supporting references or scripts. My skills catalog explains how to use tools, start and maintain projects, and work with my preferred stacks. For the Neovim change, the project instructions establish where to work and what to preserve; the relevant skill supplies the procedure. An agent building a CLI can instead load the guidance about streams and exit codes. Specialist knowledge stays available without putting every manual into every conversation. Whether a host actually discovers and follows it still needs checking through real tasks. These screenshots were captured in temporary Zellij sessions running real applications against copies of the source files. Here, my shared instructions are open in Neovim beside Antigravity’s CLI. Now an improvement can include both the configuration and the explanation of how to use it. Both stay in Git, where I can review them and future agents can find them. That gives the next task a better starting point. Better tools need useful checks An instruction to check the work needs a useful command behind it. Zizmor audits my GitHub Actions workflows, and Lefthook runs configured checks around commits and pushes. Their diagnostics give the agent something to fix and me something to review. Git-cliff handles release notes. The checks must actually run. Cosign is installed in my setup, but automatic signature and provenance verification for tool installation is disabled. A tool on the machine is not a protection in effect. To support the repository and automate workstation operations, I built a dedicated Python CLI called dot. Built with Typer and Pydantic, it turns system maintenance and agent coordination into predictable, typed commands. The dot doctor subcommand checks local health and tool parity, while dot agent context verifies that instruction files and skill catalogs remain within strict token budgets. Other subcommands manage folder trust across harnesses (dot trust), inject scoped credentials without global exports (dot secret), and aggregate token usage across agent sessions (dot agent stats). When agents and humans share an environment, a robust CLI provides the reliable contracts they both need. With agents helping maintain that foundation, I can delegate more work across projects. The next challenge is keeping track of it.