# Customizing agents

> Configuring an agent for a project with instructions, skills, tools and permissions.

Page: https://schubergphilis.github.io/ai-training/customizing-agents/
License: CC BY-SA 4.0, https://creativecommons.org/licenses/by-sa/4.0/

This course is about the layer between you and the agent. Instructions, skills, tools and permissions turn a general-purpose coding agent into one that works well in your project.

## Project instructions

- [Project instructions: AGENTS.md](https://schubergphilis.github.io/ai-training/customizing-agents/instructions/): Write the one file a coding agent reads before it touches your project, and keep it short enough that it keeps working.
- [Load it, point at it, or cut it](https://schubergphilis.github.io/ai-training/customizing-agents/load-point-prune/): Take a long instruction file and make it short: keep what nearly every task needs, move what only some tasks need behind a one-line pointer, and delete the lines the agent would not miss.

## Agent skills

- [Instruction, skill or tool?](https://schubergphilis.github.io/ai-training/customizing-agents/skill-or-tool-or-instruction/): Three ways to change what an agent does, the question to ask before choosing one, and what each costs in context and access.
- [Writing your first skill](https://schubergphilis.github.io/ai-training/customizing-agents/first-skill/): Build a release skill for a small package step by step, in the open skill format: the description that triggers it, the steps in order with exact commands, the check that says the result is right, and what to do when a step fails.
- [Who invokes a skill, and where it lives](https://schubergphilis.github.io/ai-training/customizing-agents/who-invokes-a-skill/): Decide whether the agent may start a skill on its own or only a person may, what each choice costs in context, and whether the skill belongs in the project, in your own configuration or with the organization, including which one runs when two share a name.
- [Testing a skill from a fresh session](https://schubergphilis.github.io/ai-training/customizing-agents/testing-a-skill/): Run the release skill from the first-skill lesson in a clean clone and a new session, read the transcript for where the agent hesitated, asked or guessed, turn each place into a check, a failure step or a sharper success test, and run it again.
- [Loading only what the skill needs](https://schubergphilis.github.io/ai-training/customizing-agents/progressive-disclosure/): Measure what the release skill costs at each loading stage, move its rollback procedure into a reference file the skill points to, and measure again, so the common path stays small.
- [Reading a plugin before you install it](https://schubergphilis.github.io/ai-training/customizing-agents/plugins/): Read an invented release plugin part by part, name what each skill, hook, subagent and server does in your sessions, and decide whether to install it, copy one skill out of it, or leave it.
- [Adopting a published skill set](https://schubergphilis.github.io/ai-training/customizing-agents/adopting-a-skill-set/): Vet an invented skill set skill by skill for license, maintenance, scripts and pre-approved tools, take two of its skills, and check what they change in a session against what they add to the context.

## Connecting tools with MCP

- [Connecting an agent to your systems with MCP](https://schubergphilis.github.io/ai-training/customizing-agents/mcp/): The operator's view of a remote tool server, from the identity the agent acts under to the point where a CLI is the better connection.
- [Connecting your first tool server](https://schubergphilis.github.io/ai-training/customizing-agents/mcp-first-server/): Connect a local file-system server scoped to one copied directory, give the agent a list-and-summarize test task, and read the transcript for every tool call and its arguments before the server touches real work.
- [Logging from a stdio server](https://schubergphilis.github.io/ai-training/customizing-agents/logging-from-a-stdio-server/): Break a stdio tool server with one debug line on standard output, watch the client fail to parse the first line, move the line to standard error, and read the reference file-system server's log while an agent calls it.
- [Measuring what a tool server costs](https://schubergphilis.github.io/ai-training/customizing-agents/mcp-tool-cost/): Count what a twenty-tool server's definitions take from the context window, run one query through the server and through a CLI, and decide which tools and servers stay connected.
- [Hardening a tool connection](https://schubergphilis.github.io/ai-training/customizing-agents/mcp-hardening/): Give a notes server a read-only token that expires in an hour, turn on its tool-call log, plant an instruction in one note, and read in the log which control stopped the send it asked for.

## Inspecting the agent

- [Seeing what the agent sends](https://schubergphilis.github.io/ai-training/customizing-agents/seeing-what-the-agent-sends/): Watch the context meter while you connect one more tool, find the session in its record on disk, and log the requests on your own machine to see what the tool definitions add to each one.

## Hooks, permissions, settings

- [Choosing a permission mode per task](https://schubergphilis.github.io/ai-training/customizing-agents/permission-modes/): Run one small task with a coding agent in a mode that asks before everything and in one that accepts edits, count the prompts, and choose the mode by what a mistake would cost.
- [Allowing the commands the task needs](https://schubergphilis.github.io/ai-training/customizing-agents/allowlists/): Run one small task with a coding agent twice, first with nothing pre-approved and then with an allowlist for the test command and the files it edits, then prune every rule the run never used.
- [Where a setting comes from](https://schubergphilis.github.io/ai-training/customizing-agents/settings-layering/): Why a coding agent's setting seems ignored: the settings files in override order, one worked example where four layers disagree and the effective permission set is derived entry by entry, and what a team commits versus what each person keeps local.
- [Writing a hook that blocks a mistake](https://schubergphilis.github.io/ai-training/customizing-agents/first-hook/): Write a Claude Code hook that runs before each commit and blocks it when the lockfile changed and the manifest did not, test it by hand, then make the mistake on purpose and read what the agent does with the message.
- [Keeping the project in charge](https://schubergphilis.github.io/ai-training/customizing-agents/project-stays-in-charge/): When an installed skill asks for a push the project forbids, remove the conflict from your copy of the skill, refuse the push with a PreToolUse hook whose reason names the open route, and see why a bare refusal leaves other spellings of the same command open.
- [Delegating to a subagent with narrower permissions](https://schubergphilis.github.io/ai-training/customizing-agents/subagents/): Define a read-only reviewer subagent with its own instructions and tool list, have a coding agent delegate a review of a small diff to it, and compare what the main context holds before and after.

## Memory and session context

- [Reading what the agent remembers](https://schubergphilis.github.io/ai-training/customizing-agents/memory-review/): Read the auto-memory notes a coding agent keeps for a project, delete the two that have gone stale, and move a team fact into a context file that the instruction file imports.
- [Notes that go stale](https://schubergphilis.github.io/ai-training/customizing-agents/notes-that-go-stale/): Tell a primary source from a secondary one, name the source each memory note summarizes, and decide whether to trust, check or delete each note.
- [Directing the summary before compaction](https://schubergphilis.github.io/ai-training/customizing-agents/compaction/): Load a session log with three planted facts, compact it on command with instructions that name decisions, open items and rules, and check which facts the summary kept.
- [Handing work to the next session](https://schubergphilis.github.io/ai-training/customizing-agents/session-handoff/): End a session that stopped halfway with a handoff file that names the state, the decisions and what was ruled out, and count the turns a fresh session needs with and without it.
- [Turning repeated work into something the agent keeps](https://schubergphilis.github.io/ai-training/customizing-agents/repeated-work/): Read three coding sessions that each work out how to regenerate an API client, place each repeated explanation in the instructions, a skill, a hook or a context file, and cut the instruction lines that a hook and a skill now cover.