Agent Skills 100: Telling the Agent How You Work

Your global instructions file

Every time an agent starts a session, it reads an instructions file in the root of your repo: CLAUDE.md for Claude Code, AGENTS.md for Antigravity. This is where you tell the agent about this project — how to build it, what the architecture looks like.

There’s also a global instructions file in your home directory. It applies to every repo you work in. It’s where you define your personal workflow — the phrases you use, what they mean, and what the agent should do when it hears them.

Think of it as training the agent to work the way you work.

Set it up with a prompt

You don’t need to write the file by hand, or even know where it goes. Start your agent and give it this prompt. It works in Claude Code and Antigravity: the agent works out which file it reads.

NoteCopy-paste this prompt into your agent

Create my global instructions file, the one you read in every project, with my workflow preferences. If you are Claude Code, it is $CLAUDE_CONFIG_DIR/CLAUDE.md when CLAUDE_CONFIG_DIR is set, and ~/.claude/CLAUDE.md otherwise. If you are Antigravity, it is ~/.gemini/config/AGENTS.md. Tell me the path you used.

Here is how I work:

“I am starting a new task” means:

  1. Create a GitHub issue for the task
  2. Create a branch for the task
  3. Work on the branch

“Task is done” or “Let’s finish up the task” means:

  1. Commit the work on the task’s branch, push the branch, and open a PR
  2. Tell me what the PR changes and ask me before merging it
  3. Merge the PR once I say yes
  4. Ask me before deleting the branch

Note: this assumes I’m working on my own. For collaborative work, I’ll open the PR and assign a reviewer instead of merging.

“I am about to clear” or “Get ready to clear” means:

  1. Close any loose ends (pending edits, uncommitted changes). Commit on the task’s branch, never on main; if we are on main, ask me what to do
  2. Review memories for outdated information and update them
  3. Update the handoff note, notes/handoff.md
  4. Keep the handoff concise — move detailed info to separate topic files in notes/ if it’s getting long
  5. Ask me what my next task will be when I return and put that in the handoff

“Initialize this repo” means:

  1. Add an open license if one is missing
  2. Add a reuse statement to the repo
  3. Check the README for basic reproducibility (instructions to run, dependencies listed, clear entry point)

Git rules:

  • Never push to main. Work on a branch and open a PR
  • Never use destructive git actions: no --force pushes, no git reset --hard, no git clean -f, no deleting branches that haven’t been merged
  • Always create new commits rather than amending
  • Ask before any action that could lose work

The agent will create the file for you. Review it, tweak anything you want, and you’re done.

The GitHub steps (issues, pushing, pull requests) need the GitHub access you set up in Setup. With Token for one repository they work only in that repository. With No access, the agent can still make branches and commits on the hub, but the issue, push and PR steps will fail; tell it to skip them.

Over time, add more shortcuts as you develop habits. The file grows with you.

TipExpect it to stop and ask

When you say “Task is done”, the agent opens the PR and then stops to ask before merging and before deleting the branch. That is on purpose: you decide when work goes into main. With Antigravity, the guardrails enforce this even if the instructions are missing, and Antigravity may show its own approval prompt after you say yes.

If you start working without “I am starting a new task”, the agent is on main. Antigravity’s guard will not let it push there; Claude Code’s auto mode will, unless your instructions stop it. Either way, ask the agent to move the work to a new branch.

Global vs. project instructions

Global Project (CLAUDE.md or AGENTS.md)
Where Your home directory; the agent knows the exact place The root of your repo
Applies to Every repo This repo only
Contains Your personal workflow and conventions Project-specific build commands, architecture, coding style
Examples “Starting a new task” means create issue + branch “Run quarto render to build”
Persists Tied to the machine Committed to the repo, travels with it

Both are loaded at session start. The project file adds context specific to the codebase. The global file carries your workflow everywhere.

Because the global file stays on the machine, it is lost if the hub is rebuilt. If you like what you set up, ask the agent where it is and keep a copy.

Customize it

The prompt above is a starting point. Here are some things you might add over time:

  • Code style preferences — “Use snake_case for Python, camelCase for JavaScript”
  • Commit message format — “Start commit messages with a verb: Add, Fix, Update, Remove”
  • Language — “I work primarily in R and Python”
  • Review habits — “Always show me a diff summary before committing”

Start simple. Add more when you find yourself repeating the same instruction across sessions.