Agents
What a coding agent may run on its own, what waits for you, the dot skill for agents in other projects, and Claude Code hooks.
dot is built to be used by coding agents as well as people. The repo’s
AGENTS.md tells an agent the rules; these are the ones that matter to you.
What an agent may do on its own
dot check,dot explain,dot doctorand every--help: they never change anything, and never need a password or Touch ID.- Read the repo and these docs. The site publishes
llms.txt, the whole docs as one file (llms-full.txt), and every page as raw Markdown.
What waits for you
dot apply, and anything else that changes the Mac, includingdot cloneanddot fork.- Anything with
sudo. git push, since your fork is public.- Creating or changing a secret’s value. An agent never reads or prints a
private key, token or secret value; a project secret only travels through
pipes (
dot secret).
Touch ID
Commands that reach an account through 1Password (gh, vercel,
dot auth status, dot fork, dot secret, dot conf) ask you to authorize
the app the agent runs in, such as a terminal or the Claude app. The approval
covers that app for a while, not one command, so agents batch those commands
into one shell call instead of counting on a prompt per call;
Accounts compares what each login
costs.
Agents and their scripts run gh and vercel as those tools’ docs say.
The shims from op shim come first on PATH and run them through 1Password’s
shell plugin, so any process gets the token, only for that command; the zsh
functions 1Password generates would only reach an interactive shell. A token
in the environment that 1Password didn’t set, such as one a cloned repo’s
.env loads, is ignored with a message, so a repo can’t change who gh acts
as; and gh auth login or vercel login answers
that the login lives in 1Password.
With an agent token set up (GitHub),
an agent’s gh gets a token limited to the repos it works on, one per
GitHub owner, picked by the repo the command targets. It never gets yours,
unless you set an owner to personal: then each of the agent’s calls for
that owner uses your token and asks for your approval.
A 1Password service account that can only read the Agents vault fetches it,
so the agent’s calls ask you nothing; if that fails, the command fails.
vercel, which has no agent token, fails for agents and works only from
your terminal.
An agent never puts a token in its own shell, because its output is kept on
disk. A project’s secrets reach it through the project’s .env.schema
(dot secret attach); for a one-off script that needs a secret outside it,
the agent passes a 1Password reference through op run, which injects the
value into that process only and masks it in the output.
On a clean Mac, an agent runs the installer with --yes --no-apply: it
installs, stops after dot check, and shows you what apply would change.
The dot skill
AGENTS.md only reaches an agent working inside this repo. The dot skill,
in skills/dot/, carries the same rules to agents working anywhere else: how
to find dot, which commands they may run on their own, which task maps to
which command (dot clone instead of git clone, dot secret instead of a
token in a file, a config/ line instead of brew install), and how to
batch the commands that ask for Touch ID.
It’s a standard Agent Skill, so the skills CLI installs it for Claude Code, Codex, Cursor and the other agents it supports, straight from GitHub:
npx skills add rbadillap/dotfiles --skill dot --global
It asks which agents to install it for. npx skills update brings in a newer
version after you change the skill.
As an Agent Plugin
The repo root is also an Agent Plugin:
plugin.json names it dot and the spec finds the skill in skills/dot/
(§6.1, §7.1). A client that installs Agent Plugins can load it from the
repo directly.
A workflow, .github/workflows/agent-plugins.yml, checks plugin.json
against the spec with
agent-plugins-validate
on every pull request and every push to main. When a manifest that was
valid breaks on main, it opens an issue, and closes it once fixed.
Claude Code hooks
Claude Code (the CLI and the desktop app’s Code tab) reads
~/.claude/settings.json. Claude Code writes its own settings there, so dot
only adds hooks to that file and never touches the rest. To add one, put
the script in config/home/.claude/hooks/ and a claude hook line in
config/claude.conf; the script is linked into ~/.claude/hooks/.
dot check claude # which hooks are missing
dot apply claude # add them
A new or changed hook takes effect in the next Claude Code session.