Skip to main content
A coding assistant connected through Arch MCP can orient itself in a project, investigate a failure, make a bounded change, and gather evidence for your review. Agent developers still own the outcome: you set the intended behavior and the risk boundaries, then review the changes and the evidence before you authorize consequential actions.

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. After platform_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:
Use --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.
In the assistant’s settings, auto-approve only tools that just read. Some tools, such as platform_agents, mix read and write actions in one tool. Require approval for them and for any tool that changes the platform.

Build a customer skill

Create a team skill for a recurring task that combines platform procedures with your policies, project context, or acceptance criteria.
  1. Name the task and the trigger. State which request activates the skill, and when it doesn’t apply.
  2. Set the context. Point to project facts in AGENTS.md or team standards. Include the environment, data, and assumptions the task needs.
  3. Choose platform references. For example, a release skill can follow arch-release-check, then add your release thresholds, approvers, and required evidence.
  4. 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.
  5. 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.
Put the skill in the project skills folder for your assistant, such as .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

Start with an explicit mode. For an investigation, say “read only.” For implementation, name which files or agents may change and which actions need approval.

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.md and the targets sheet in the project folder.
The task request sits on top of these. It names the goal, the evidence, the limits, the acceptance criteria, and the output you want.
Keep guidance testable. “Use safe test data for write scenarios” is actionable. “Be careful” isn’t. Tell the assistant which check proves that it followed the rule.

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.
For example, let the assistant edit the Disruption agent’s working copy and run an eval set with no write scenarios, while the project owner approves the publish. Keep these permissions distinct in the request and in the tool setup. Keep publishing, import, deployment, and live-data changes behind your project’s approval process.

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
Update the note when a material decision changes. Date it, and mark a hypothesis as a hypothesis. At the start of a new session, ask the assistant to compare the note with the current sources before it continues.

Request templates

Replace the brackets, and say whether the assistant may edit or act.

Read-only orientation request

Small change request

Debugging request

Verification request