Using agents & skills
Pick the right agent for a task, shape your own, and give them reusable skills — so the work fits how your team actually operates.
An agent is the persona a session runs as — its instructions, the model it uses, and the skills and tools it can reach. Every project ships with sensible defaults, so it works out of the box. Shaping your own is how you make Machine fit your team.
Pick an agent for a session
When you start a session, the agent and model are what determine how it behaves:
- Agent — choose which persona runs, from the session's settings. A "reviewer" agent and a "builder" agent approach the same project differently.
- Model — the model selector in the session header picks which Claude model powers the run: a faster one for quick edits, a more capable one for harder reasoning.
You can set these before you start, or switch mid-run.
Browse the project's agents
Open Customize → Agents to see every agent available in the project. Open one to read its full instructions — the system prompt and guidance that define how it works. This is the quickest way to understand what each persona is for before you run it.
Shape your own agent
Agents are defined as code in your project (under the agent configuration directory), which means they're versioned and travel with the repo. To make one your own, you give it:
- Instructions — the system prompt that sets its role, voice, and how it should approach work.
- Skills and tools — which skills and connected tools it's allowed to use.
Because it's code, every change to an agent is reviewable and reversible, and the whole team gets the same behavior.
Start from the defaults and adjust. A small, clear instruction set usually beats a long one — give the agent the role and the guardrails, and let the model do the rest.
Skills
A skill packages a workflow you repeat into a reusable shortcut an agent can invoke — so instead of re-explaining a multi-step process every time, the agent just uses the skill.
- Browse them under Customize → Skills. Open one to read what it does and how it's used.
- Agents use them automatically when a task calls for it, within the skills you've made available to that agent.
- Create your own by capturing a workflow you do often as a skill in the project — once it's there, every agent that's allowed to use it can.
Like agents, skills live in the project as code: versioned, shared across the team, and compounding over time as you add more.
Putting it together
The pattern that scales: shape a couple of agents around the roles your team has, give them the skills for the work you repeat, connect the tools they act in, and run sessions against them. Each piece is code in your project, so your setup gets better week over week instead of living in people's heads.
Related: Agents concept · Customizing your project · Running a session.