Onboarding a New Teammate’s Agent in Minutes

Prepare the starter package before the teammate arrives

Choose one day-one job: summarise an onboarding issue, find the owning service and explain how its tests run. That job determines the initial access request. An agent helping a new developer understand the payments repository might need the engineering issue tracker and service runbooks; it does not automatically need production billing records.

Put the non-secret setup in the repository’s onboarding documentation. Include the approved endpoint, supported client, project directory, instruction-file path, skill path, access owner and expected result for a sample issue. Give the sample a stable identifier, such as a deliberately created onboarding ticket, so the buddy can distinguish a successful retrieval from a plausible answer.

Before the first session, the access owner should approve the required sources and arrange individual authentication. If a key is required, issue one for this agent through the team’s approved secret-delivery process. Keep the endpoint and configuration template shareable; keep the credential out of the repository, onboarding ticket and conversation. For multiple agents per teammate, use the ownership pattern in one scoped key per agent.

Connect the client with shareable configuration

For an OAuth-capable team endpoint, Claude Code’s MCP documentation supports this HTTP command. Run it from the intended repository, replacing the example URL with the approved endpoint:

claude mcp add --transport http --scope project team https://mcp.example.com/mcp

Project scope writes the connection to the repository’s .mcp.json. Review that file before committing it. In an interactive Claude Code session, open /mcp, check the server and follow its browser sign-in flow. This example deliberately supplies no authentication header.

For Cursor, its MCP integration documentation places shared project configuration in .cursor/mcp.json and accepts a remote url entry:

{
  "mcpServers": {
    "team": {
      "url": "https://mcp.example.com/mcp"
    }
  }
}

Save the file and restart Cursor, as its documentation instructs. Complete the endpoint’s supported authentication flow. The URL entry describes the connection; it does not itself grant access. If your server requires a bearer credential instead, prepare the client-specific secret setup separately rather than adding a literal token to this shared template.

Give the first session the team’s actual conventions

Include the instructions that make the sample task useful: which repository contains the service, the verified test command, where ownership is recorded and who approves changes. Leave historical incident transcripts out of the starter package. The teammate needs enough context to interpret the first issue, with a clear route to deeper references.

Anthropic documents project instructions in ./CLAUDE.md or ./.claude/CLAUDE.md. It also states that these instructions guide model behaviour rather than enforce configuration. Put the team’s reviewed conventions there when using that arrangement, then ask the agent to identify the instruction file it used and explain the applicable test command.

For teams using several clients, record which instruction file each client actually loads. Do not accept an agent saying it knows the conventions as evidence that the right file was loaded. Ask it to quote the relevant repository rule and identify its location. Keep cross-client maintenance separate from the day-one task; keeping agent instructions in sync covers that continuing work.

Ship one reviewed skill with an observable result

Provide a small triage-handoff skill for the onboarding ticket. The Agent Skills specification requires a directory containing SKILL.md, with YAML frontmatter followed by Markdown. The required name must match its directory name, and description explains what the skill does and when to use it. A minimal example is:

---
name: triage-handoff
description: Summarise an engineering issue for a teammate taking ownership. Use when preparing an issue handoff.
---
Read the issue supplied by the user through an approved tool.
Return its identifier, owning service, open questions and source reference.
Separate facts in the issue from your proposed next actions.
Draft the handoff in the conversation; do not update the issue.

Distribute a reviewed revision and record its path. Skill discovery varies by client, so verify installation against the chosen client’s documentation. For the acceptance task, explicitly ask the agent to read that file if automatic discovery has not been established. Review any bundled scripts before including them. A Markdown instruction to avoid updates helps define the task; the agent’s access grant must independently exclude unwanted writes.

Prove the agent can work within its assigned access

Have the teammate start a fresh session from the repository and supply the sample ticket identifier. Ask: “Read the onboarding ticket through the approved connection, use the triage-handoff skill, and explain which repository test command applies. Return source references and do not update anything.” The buddy should inspect the tool activity as well as the response.

1. Allowed read: confirm the returned identifier and one known fact match the sample ticket. A generic summary without a successful retrieval does not pass.
2. Conventions: confirm the agent cites the correct instruction file and test command. Do not run tests merely to establish that the instruction was loaded.
3. Skill use: check for the owning service, open questions, source reference and a clear distinction between recorded facts and suggested actions.
4. Access boundary: use a harmless, prearranged test fixture outside the assigned source or project. Confirm the tool refuses access or withholds the capability. Never test this by probing real restricted records or attempting a production mutation.
5. Revocation: withdraw a disposable onboarding credential or test grant and repeat the allowed read. Verify denial, then provision the intended ongoing access.

Record the observed results. A verbal promise to avoid writes does not establish that writes are blocked, and an authentication success does not establish that the correct project is reachable.

Fix the failed layer before expanding permissions

If the server is absent, compare the configured file location and client with the starter package. If the server appears but authentication fails, check the teammate’s identity and assigned access with the owner. Do not substitute the buddy’s working credential. If authentication succeeds but the sample ticket cannot be read, check the approved source and project before adding broader permissions.

If retrieval works but the handoff ignores conventions, inspect the instruction and skill paths used in that session. If the denied fixture becomes readable, stop the onboarding test and correct the grant. These outcomes identify different setup defects; granting administrator access would make the test less informative. Record the specific failing check so the next teammate does not repeat the same debugging conversation.

Doing this with SPYN3

SPYN3 provides one MCP endpoint per workspace at https://api.spyn3.com/agent/mcp. An admin can issue a source-scoped key with call:tools; writes require the separate call:write_tools grant. Upstream credentials stay in the workspace and never reach the agent. With opt-in Memory & skills enabled, the agent can read shared context through MCP tools; memory writes require write:memory. Start with the approved onboarding sources and shared skill, then test revocation: revoking the key takes effect on the next call.

Leave a handoff the teammate can repeat

Finish by recording the client version, repository revision, approved endpoint, credential owner, granted sources, instruction and skill revisions, and acceptance results. Store credential identifiers only where appropriate, never their values. The teammate should be able to reopen the project, authenticate as themselves and reproduce the same sourced handoff without borrowing another person’s session.

Measure elapsed time from prepared access to a passing acceptance task. Track approval delays separately from configuration and debugging. Use the first few onboardings to remove missing paths and ambiguous instructions from the starter package. Once the process repeats reliably, the buddy can spend the session explaining the service rather than reconstructing its agent setup.