Choose Studio, Arch, or a coding assistant
Studio is the visual workspace for configuring and testing agents. Arch MCP gives coding assistants access to supported platform tools. A task can use one surface or combine them.
Arch proposes a plan, then shows each agent change as a before-and-after diff. Choose Approve or Do not approve. An approved change compiles into the working copy. Arch never publishes or deploys on its own.
Connect a coding assistant to Arch MCP
Install the Arch MCP server and connect your assistant as described in Install and configure MCP server. Afterplatform_connect signs you in, confirm the active workspace before you start.
Install the guidance skills for your assistant and scope. For a project-level Codex install:
--client claude for Claude Code, or --scope user to install the skills for all projects. Start a task with the arch-agent-guide skill. Keep an AGENTS.md file in the project folder with the project ID, environment, topology, test data, and the actions that need your approval.
Skills add reusable task guidance. They don’t add tools or grant permissions. For all 13 skills, see Arch MCP tools and skills. For the tool catalog, see Build with Arch using MCP.
Build a customer skill
Create a team skill for a recurring task that combines platform procedures with your policies, project context, or acceptance criteria.- Name the task and the trigger. State which request activates the skill, and when it doesn’t apply.
- Set the context. Point to project facts in
AGENTS.mdor team standards. Include the environment, data, and assumptions the task needs. - Choose platform references. For example, a release skill can follow
arch-release-check, then add your release thresholds, approvers, and required evidence. - Write the workflow and boundaries. Order the investigation, tool calls, validation, and reporting. Name read-only actions, actions that need approval, stop conditions, and how to handle an unknown outcome.
- Define proof and maintain it. Specify the answer format and evidence. Try the skill on representative requests and edge cases, then store it in version control for review.
.codex/skills/<team-skill>/SKILL.md or .claude/skills/<team-skill>/SKILL.md. Give it an organization prefix so it stays distinct from the platform’s arch-* skills. Build on the platform skills by naming and following them; don’t edit their installed arch-* folders, because the installer manages them.
What the assistant does and what you decide
Give the assistant context
Don’t ask the assistant to infer the project from one agent file. Give it the smallest set of references that lets it understand the task and verify the result.
Point to authoritative sources. A project instruction file can describe conventions and test data. A task prompt names the current goal. A trace, schema, or policy stays the source for runtime facts.
The assistant’s context and the agent’s context are different things. The assistant’s context is the guidance, files, tools, and conversation it reads during development. The deployed agent’s context is the information assembled for a user conversation at runtime. They need separate budgets, controls, and debugging methods.
Skills, house standards, and project guidance
Keep project guidance stable: naming, source-of-truth files, test commands, approval boundaries, and how to report evidence. Don’t put a one-off fix in it, or copy a whole platform manual into it.- Platform skills: the 13
arch-*skills that ship with Arch MCP. Never edit them. - House standards: your team’s skills and templates, kept in their own Git repository.
- Project context:
AGENTS.mdand the targets sheet in the project folder.
Write a request
A good request states the job and the answer you need. It gives enough context to avoid guesswork, but doesn’t prescribe a fix before the evidence is known. For implementation, add the allowed change surface and the exact checks. Ask for the plan first when the work may affect shared behavior or data. Give the source, scope, limits, and proof in the first request.Set limits on actions and data
Name the operations that stay read only. Say whether edits are allowed, which test data the assistant can use, and whether publishing or deployment is out of scope. Secrets live in Studio auth profiles; tools and requests refer to the profile by name.
For voice work, don’t include unredacted recordings, names, phone numbers, or account IDs in general prompts. Use approved examples, and remove identifiers before you share transcripts.
When sources disagree
Assistants combine instructions, task text, retrieved files, tool results, and earlier messages, and these can disagree. Policy decides what to build, the current agent decides what is defined, and the trace decides what happened. Tell the assistant to report conflicts. An old session note may disagree with the current definition: the assistant names the mismatch and uses the approved source for that decision. Don’t ask it to silently reconcile policy, runtime facts, and code comments.Use task modes
Don’t combine “find out what happened,” “fix it,” and “release it” in one vague request. Each step produces an artifact that gives you a reason to continue.
For a small typo, a short plan can be enough. For a routing, identity, voice, or write-path change, ask for a diagnosis and a reviewable plan first. When the evidence reveals an unknown requirement, stop and get the policy decision. Don’t ask the assistant to invent it.
Know which copy you change. Edits change the working copy, which Studio test chats, working-copy eval runs, and channels bound to None use. Publishing freezes a version, and a deployment runs a version in an environment. A conversation keeps the version it started with, so test every change in a new one. If a save is refused because the source changed after the assistant read it, reopen the current definition, reconcile the change, then apply and validate it again. See How guarded edits work.
Match each question to its evidence
A repository search can’t prove what happened in a live conversation. A trace can’t prove that a policy document is current. Use each source for the question it can answer.
Read the action as well as the tool name.
platform_eval_runs cases only reads results, but start runs conversations that can write rows. Keep the returned IDs and versions with the findings.
Review the assistant’s work
A concise answer can still hide a wrong assumption. Review the trail from evidence to decision to change, in the order described in Diagnose and review a change. If the assistant reports success but can’t point to a completed check, treat the work as unverified. If the result differs from the plan, inspect the difference before you accept it. Stop when the requested behavior is demonstrated and the relevant regression cases pass. New scope becomes a new task.Example: a cancelled-flight call that went wrong
A traveler phoned about a Denver flight that Voyager had cancelled, and wanted another flight. The call ended with the booking cancelled and a 75 USD fee, which policy forbids for a cancelled flight. A vague request, “The rebooking call failed. Fix the Disruption agent”, produces an instructions edit that can’t fix the call. A read-only request in the debugging request format found four causes:
Only one of the four causes was in Disruption. When a policy is unclear, the assistant returns the question to the policy owner.
Common assistant mistakes
A correction must change the working context or the next action. When the assistant repeats the same error, narrow the scope, point it to the authoritative source, and ask for one verifiable step.
Decide what the assistant may do on its own
“Work autonomously” leaves too much open. State which steps the assistant performs on its own and where it must stop.- It may read the project guide, inspect named sources, and draft a plan.
- It may edit the allowed working copy after the plan fits the task.
- It may run the named validator and eval sets that have no write scenarios.
- It must stop before it changes shared state, real customer data, permissions, or a deployment.
- It must return for a decision when a policy, product target, or data owner is missing.
Keep session notes between sessions
A long project can outlive one assistant session. Keep the result of the work in a short session note that points to durable sources. The next session then resumes without repeating the investigation or inheriting stale assumptions. Link to traces or eval runs instead of copying sensitive details into the note.Session note template