Amdahl onboarding skill
First-run setup for Amdahl. Connects over MCP or an API key, checks the setup in one call, finds the people the user is about to write to and what is known about them (a sequencer or SDR tool, a CRM, a spreadsheet, a Drive or Notion folder, or the code that sends outbound), then gives every user a first result that needs no data (a few messages Amdahl writes from that context, in the user's own voice). If the workspace has synced conversations, it goes on to one use case end to end (a Search for real customer quotes, then a grade of a message against the workspace's conversations, line by line). Use when a user says "set me up on Amdahl", asks to have their outbound emails written or optimized, pastes an amdhl_ key, or names a use case such as grounded outbound or a positioning check.
Seven steps, in order. Stop and tell the user at any step that fails; do not skip ahead.
- Connect
- Check the workspace has data (this decides step 5 onward; it does not gate steps 3 and 4)
- Find the recipients and gather the context
- First win: have the optimizer write a few messages (no data needed)
- Once conversations are synced: pick the use case
- First Search: real customer quotes
- First grade: grade a message against the customers' conversations, then close the loop
The Message Optimizer and Search are the two primitives Amdahl is built on. The optimizer writes and grades outbound; Search reads the workspace's own customer conversations, and so does the optimizer when a call sends "evidence": "workspace". Writing a message is the on-ramp: the fastest result, for any workspace, before any data has synced.
The rules
- Show a grade line by line: each rubric line with its verdict and its
reason, as returned. Do not summarise the lines into one sentence of your own. If you quote a number, quote the fraction (for example "2 of 5 lines passed"), not only the score. A line withpass: nullwas not graded: say "not graded", never "failed". - Never write to the user's systems without asking. Do not edit a sequence, update a CRM record, change a file, commit code or send a message until the user has approved that specific batch. Showing a message is always safe; applying it is the user's call.
- The optimizer writes from context. Send what you know about the recipient in the
factsofcontext. Send a draft inmessageonly when the user wrote it: the optimizer keeps that draft as the base and takes what it states as the user's own word. Never write a draft yourself for the optimizer. - Show the optimizer's
messageexactly as returned. Do not edit, polish or merge it with your own version before the user sees it: the checks that kept their facts exact ran on that text. If the user wants it changed, re-run the optimizer with their wish as one of therulesincontext(or a fact they confirm infacts), or let them edit it themselves. Never layer your own rewrite on top.
1. Connect
If the Amdahl tools are available (optimize_message, search_customers, optimize_prompt, get_setup_status and the rest), use them and skip to the health check below. Otherwise connect once. In Claude Code, Codex or Cursor, run npx amdahl and tell the user the last step it prints: run /mcp once in Claude Code, run codex mcp login amdahl for Codex, and Cursor asks on first use. If you can run shell commands and the user agrees, you may run it yourself: run by an agent, it shows no menu and opens no browser. The sign-in is always the user's. In Claude or ChatGPT, add a connector with the URL https://app.amdahl.ai/mcp and sign in with your work email. No workspace yet? Try the optimizer at console.amdahl.ai/try, which also joins the beta waitlist. An admin of an existing workspace at their company can add them instead. On a server or in CI, use an API key in AMDAHL_KEY and REST:
- Base URL:
https://app.amdahl.ai/api/platform/v1 - Header:
X-API-Key: amdhl_…(Authorization: Bearer amdhl_…works the same) - Every successful JSON response is wrapped: read
.data.
Over MCP there is no key: signing in is the connection. Clients such as Claude ask the user to allow each Amdahl tool the first time it is called ("Allow once" or "Always allow"). Tell the user to expect that prompt.
The user creates a key in their own terminal with npx @amdahl/cli login, then npx @amdahl/cli keys create --name "Onboarding" --preset agent, and approves it in the console. Or in the console: Settings, then API keys, then Create key, with Access kept at Customer agent (the default). Customer agent carries messages:execute for steps 4 and 7. A Read only key can search but cannot run the optimizer, so it can neither write nor grade a message. A coding agent or a script reads the key from the environment as AMDAHL_KEY, not from the chat. In a private chat with an assistant such as Claude or ChatGPT, a key the user pasted can be used for that session. If the user shares or exports that chat, they revoke the key in the console under Settings, then API keys.
Health check. Before step 2, check the setup. MCP: the get_setup_status tool. REST: GET /setup/status. It names the workspace and the caller's role, and optimize.allowed says whether step 4 will work. When it is false, optimize.blocker says why:
missing_scope: the key is Read only or predates the Message Optimizer, or the connector was authorized before it existed. Ask for a new Customer agent key, or have the user disconnect and reconnect the connector.role_too_low: the user is a Viewer. Ask a workspace admin to raise their role to Editor or above.quota_exhausted: the workspace used this month's optimizations. It resets atoptimize.quota.resets_at. Steps 2, 5 and 6 still work.
The same read reports connections: how many sources are connected, how many are healthy, and which need attention. Mention any that need attention; they are why data can look thin in step 2.
Other failures at this step:
401: the key is missing, wrong, revoked or expired. Ask for a new one.
2. Check the workspace has data
REST: GET /search/overview. MCP: read the resource search-overview://current; if the client cannot read resources, call the search_customers tool with {"mode": "filter", "surface": "interactions", "metrics": [{"fn": "count"}]}.
The overview returns one entry per surface (interactions, deals, deal_qualification) with row_count, earliest_at, latest_at and time_field.
- Every
row_countis0: the workspace is empty. Say so, run steps 3 and 4, and do not run steps 5 to 7, even when the user's first request was to "grade" their copy. Tell them a grade reads their customer conversations, so it needs a connected source first, and offer the optimizer's style pass now: search returns empty results that look successful, and a grade's four evidence lines abstain withcorpus_empty, so only the ask is graded. - A
row_countisnull: that read failed. It is not zero. Retry once before saying anything about the data. - Otherwise report: how many conversation rows, how many deals, and the newest conversation date (
latest_atoninteractions). Then run step 3.
3. Find the recipients and gather the context
The optimizer writes each message from the context you send. A draft is optional. So the work in this step is finding who the user is about to write to, and what is known about each one. Thin context gives a generic message: see https://docs.amdahl.ai/concepts/context.
Look first, in this order:
- Your own tools. List the MCP servers, connectors and tools connected in this session besides Amdahl. A sequencer or SDR tool (anything that holds sequences, campaigns, steps or scheduled emails) is the best source of who is next. A CRM (HubSpot, Salesforce) holds the contact, the company, the deal and the notes. Google Drive, Notion or a file system may hold a lead list, a one-pager or a style guide.
- The conversation and your memory. The user may have already named a person, a campaign, their product or a style guide.
- A repo, if you have one open. Search it for where outbound is sent and what the code knows about each recipient at that point (for example a sequencer's, SendGrid's or Resend's send call).
Then ask only what you could not work out, at most three short questions, in one message. For example:
- "Who should I write to first?" (only if you found no source, or found several)
- "What is the reason to write to them now?"
- "What do you sell, in one line, and what proof can I cite?"
If you find nothing and the user has no system, ask them to name one person and why they are writing, and go on to step 4 with that.
The user may point you at a whole campaign: a table, a sequence with dozens of steps, a list of rows. Do not run it through the chat. Say so before you start: more than 10 messages belong on the campaign script at https://docs.amdahl.ai/cookbooks/optimize-a-campaign, which builds the context for each row and runs the whole list with an API key. Offer 10 of them here as a sample.
If the user asks for copy that is not an email or a LinkedIn message, such as a call script, say Amdahl does not write it. Do not ask for it as an email.
Pull a batch: 10 real recipients who are due a message (the next sequence step, a follow-up due, the newest rows of a sheet). Read only. Keep a note of where each one came from (sequence and step, row, record) so you can show it and, if the user asks, put the message back in the same place.
For each recipient, gather facts, one per entry, up to 10:
- Who they are: name, title, company.
- A reason to write now: a hire, a launch, a funding round, a post, something they said, the step of the sequence.
- What the user offers, and the proof they may cite, stated exactly as the source states it.
- Anything else known: CRM notes, the last conversation, the deal stage.
Never write a fact yourself. A fact licenses a claim, so an invented one puts an invented claim in the message and makes it look checked. Every fact comes from a tool, a document or the user.
Collect these too, once for the batch, when they exist:
rules: hard constraints from a style guide or the user's instructions ("never mention pricing", "under 80 words"), and the ask ("ask for a 15-minute call"). Up to 20.voice_examples: emails the user wrote themselves and liked, such as past sends with good replies. Up to 5. The message matches their voice and does not copy their words.
When a fact comes only from the user's memory (a meeting, something the recipient said in person or on a call), ask the user to confirm it in one question before step 4, for example: "Your notes say you met Priya at the GTM dinner and she said her SDRs spend hours rewriting drafts. Is that right?" If they confirm, record it as one fact, in their words, for that recipient only. Do not add detail they did not give. If they do not confirm, leave it out.
If the outbound is sent from code
When you have repo access and outbound comes out of code (a job that reads a CRM, a prompt that writes the email, a call to a send API), run step 4 on a few real recipients first. Then show the user where an optimize call would go: where the code knows the recipient, before the message is queued or sent.
- REST:
POST https://app.amdahl.ai/api/platform/v1/messages/optimizewith headerX-API-Key, body{"channel": "email", "context": {"facts": [...], "rules": [...]}}, and read the message from themessagefield insidedata. Use it as returned. Leaveinclude_triesout of this path: it is for showing a person how a message took shape, and a send pipeline only needsmessage. - MCP: the
optimize_messagetool, for code that already talks to an MCP client.
Write the change as a diff and show it. Handle the failure path in the diff: when ok is false or there is no message, send the code's own fallback (or hold the send) and log the reason. Each call usually takes 1 to 2 minutes and can take up to 300 seconds, so it belongs in a background job, not a request a user waits on. Do not commit, push or open a pull request until the user approves the diff. Full code: https://docs.amdahl.ai/cookbooks/optimize-before-you-send
4. First win: have the optimizer write a few messages
Every user gets this first, with or without data. Use the batch from step 3. One call per recipient. Send one, wait for the answer, then send the next: never more than 3 at once.
REST: POST /messages/optimize. MCP: the optimize_message tool. Send "channel" ("email" or "linkedin"; a sequencer step usually says), "include_tries": true, and "context" with that recipient's facts and the batch's rules and voice_examples. Do not send message. include_tries adds tries, every version the optimizer scored, so the user can watch the message take shape. If step 2 found conversation rows (an interactions row_count above 0), add "evidence": "workspace" and tell the user what it does: it also checks each message against what their own customers said in those conversations, and it makes each call slower. On an empty workspace leave evidence out; the default is a fast style pass. Tell the user each one usually takes 1 to 2 minutes, longer with evidence; allow up to 310 seconds per call. It returns on the same call; there is nothing to poll.
One recipient (the same body over MCP and REST):
{
"include_tries": true,
"channel": "email",
"context": {
"facts": [
"Priya Shah is VP Sales at Northwind Labs.",
"Met Priya at the GTM dinner last week; she said her SDR team spends hours rewriting AI drafts.",
"We sell Relay, which drafts first-touch emails from CRM notes."
],
"rules": ["Ask for a 15-minute call next week."]
}
}For each recipient, show who it is for and where they came from, then message from the result exactly as returned (the optimizer's choice comes first, before anything you say about it), then summary, then the facts it was written from, then every entry in tries.
Show tries in round order, after the optimizer's choice:
- Label them "Try 1", "Try 2" and so on.
- Give its Message Optimizer score (
score) and Human tone (human_tone), both out of 5. Write "not scored" fornull, never 0. - Say in plain words what it aimed at (
aimed_at), for example "a clearer ask and a shorter email". - Mark the one with
returned: trueas what came back.
Then add one honest line: "These scores are the optimizer's own grading during the search. They show the path, not proof." Never quote the first try's score against the last as an improvement. If tries is null or missing, show message only. Details: https://docs.amdahl.ai/endpoints/message-optimizer#reading-tries
Then say plainly:
-
This message is judged on how it reads and how clearly it asks. If
evidence.usedistrue, it was also graded against their customers' conversations, and the claims nothing in them backs are listed inunsupported_claims(below); otherwise it was judged on style only, and ifevidence.reasonisevidence_unavailableorcorpus_empty, say no conversations could be read for it. The grade in step 7 rules on each rubric line, with a reason for each. -
If the message closes on a question rather than a meeting request, say so: by default the optimizer prefers a close the reader can answer in one line. To get a meeting ask, re-run with it as one of the
rules, for example "End by asking for a 15-minute call." or "Close by offering to send detail; never ask for a call." -
If the message is generic, the context was thin. Check the
factscount in the result'scontext: with 0 or 1 facts, say so, ask the user for a reason to write now or what they offer, and run it again with the answer. Do not run the same context again unchanged: it returns the same result. -
Read
omitted. Each row is something the message left out because the context could not back it, withwhywritten for the user. Show eachwhybeside the message, and offer to run it again with the missing fact. -
If
outcomeisneeds_input(only when the call senton_missing_input: "ask"), nothing was written. Put eachasksquestion inaskto the user as written, then run it again with their answers added as facts. -
Read
unsupported_claims. It is produced only when you passed"evidence": "workspace"andevidence.usedistrue; otherwise it isnull, which means claims were not checked (so passevidencewhenever step 2 found conversation rows). Each entry is a claim in the message that nothing in the workspace's conversations backs and no fact states. While any entry has a status other thanremoved, do not call the message ready to send. Go through them with the user one claim at a time, quotingspanandwhy, and ask:- Is it true, and do they know it? Re-run with it added to
factsinsidecontext, in their words. - Does it have a source? Add what the source states to
facts, in its words, and cite the source in the message. - Neither? Offer to re-run with
"on_unsupported": "remove", which lets the optimizer soften or cut it.
Never remove a claim without asking, and never re-run with
removeon your own: the claim may be something the user knows that the conversations do not. - Is it true, and do they know it? Re-run with it added to
-
Relay each note whose
audienceissender, repeating itssaystext as written. Never show adevelopernote. If you seedraft_improved_no_context, you sent amessagewith no facts and no rules: send the facts too.
If ok is false, nothing was written. Read reason (or error.code) to the user. rate_limited means the workspace has too many optimizes running or just started: wait error.details.retry_after_seconds, then send the same request again. optimizer_error or optimizer_timeout means the Message Optimizer may be down: stop the batch, tell the user, and try one request after retry_after_seconds (one minute when the response gives none). Do not send the next one and do not retry in a loop. quota_exceeded (429 over REST) means the workspace used this month's 1,000 optimizer calls for API and OAuth keys. Stop the batch there.
After the batch, ask what to do with the messages. Offer to put the ones they approve back where they came from (the same sequence step, row or record). Write back only what they approved, only in the place you read it from, and send nothing. If you have no tool that can write there, give them the text to paste.
Then frame the next step:
- The workspace has data: offer the deeper, grounded check. Steps 5 to 7 grade a message against what their customers actually said, pass or fail per rubric line, with a reason for each. Continue if the user wants it.
- The workspace is empty: stop here. Tell the user to connect a CRM or call recorder (over MCP, the
list_connectorstool lists what can be connected). Once conversations sync, come back to step 2 and run steps 5 to 7.
5. Once conversations are synced: pick the use case
If the user already named one, use it. Otherwise offer:
- Grounded outbound: ground a first-touch message in your buyers' own words, have the optimizer write it, then grade it.
- Message check: grade an email or LinkedIn message the user already wrote against what customers say.
Ask for the one missing input: the persona they sell to (use case A), or the message to check (use case B). Use cases A and B below give the exact calls.
6. First Search
Always send mode: "semantic", hydrate: true (so rows carry quotable text) and an explicit limit.
REST: POST /search/query. MCP: the search_customers tool with the same fields.
Show the user 5 to 10 quotes with the company and date for each. Then one line from the response's corpus block: which store answered and how many rows.
corpus.empty_reasonisread_failed: an error. Retry; do not report "nothing found".weak_matches_only: rephrase the query once, then carry on.no_match: nothing in the corpus matches. Say so, and carry on to step 7 anyway.
The semantic lane holds customer-side speech only, so these are your buyers' words, not your reps'. A query containing a phrase in double quotes runs a different lane (exact-term matching); leave quotes out of this query.
7. First grade
REST: POST /messages/optimize. MCP: the optimize_message tool. Send "mode": "grade", "evidence": "workspace", "channel", and the message from use case A or B in "message". Pass the same "context": {"facts": [...]} you gathered in step 3 when the message leans on what the user knows in person: a fact backs only the claim it states, and it is never counted as a customer quote. Do not send include_tries or on_missing_input: "ask": a grade refuses both.
A grade writes nothing and returns on the same call; there is nothing to poll. Allow up to 310 seconds. The result has no message field: outcome is graded, and the grade is in grade.
Show the user, in this order:
evidence.used. Say the message was graded against their customers only when it istrue. When it isfalse, readevidence.reason: the four evidence lines were not graded, and onlycta_claritywas.- The fraction:
grade.passedofgrade.totallines passed, thengrade.score(1 to 5) and whether it reached the bar (grade.passes_bar, bar 4.2). - Every entry in
grade.lines, in order: the line (relevant_positioning,grounding,verified_specifics,differentiation,cta_clarity), pass, fail or "not graded" forpass: null, and itsreasonas returned. For a line that was not graded, give itsnot_applicable_reason.
Say these out loud after the lines:
- The grade measures the message against your evidence and this rubric; it does not predict replies.
- One grade is one reading. The same message can grade differently on another call (
disclosures.single_run). To compare two versions, grade each several times and compare the fractions. - If
grade.scoreisnull, nothing was graded. Readgrade.not_applicable_reasonto the user; it is not a failing grade.
To fix a failed line, change the message from its reason (or re-run the optimizer in its default mode with a new fact or rule), then grade the new version.
Close the loop
Ask what the user did with a message the optimizer wrote, then record it.
REST: POST /messages/optimize/runs/{run_id}/feedback, with the run_id from the optimize result. MCP: the record_message_feedback tool, {"run_id": "…", "evidence": "…", "outcome": "…"}.
evidence(required):reported_to_mewhen the user told you,did_it_myselfonly if you applied the change yourself in this session,inferredif you are guessing. Aninferrededit is stored but does not train the sender's preferences.- At least one of:
outcome(used,used_with_edits,not_usedorunsure),sent_text(the message as actually sent, edits included) andcomment(what the user said about it, in their words).
Each call stores one more event, so a retry stores it twice. Send it once.
Then offer the next steps:
- Grade the prompt behind the drafts:
optimize_prompt(RESTPOST /messages/optimize_prompt) with the prompt the user or their agent writes from. It writes one email per sample recipient and grades each one. In the defaultimprovemode it returns a revised prompt only when the revision wrote better email on held-out recipients. A run takes minutes: read it withget_prompt_run(RESTGET /messages/optimize_prompt/{run_id}?wait_ms=30000), repeated untilstatusiscompleteorfailed. Quoteliftonly whenlift_reportableistrue; thetrainscores are never lift. - Put a grade in front of the user's send queue: grade each message, hold it when
grade.passes_barisfalse, and pass it through to a person when it isnull.
A. Grounded outbound
Search, with the persona's pain in plain words:
{
"mode": "semantic",
"query": "what slows RevOps teams down when headcount grows fast",
"hydrate": true,
"limit": 10
}Have the optimizer write the message: call optimize_message (REST POST /messages/optimize) with "evidence": "workspace" (so it reads the customers' words itself), the recipient, the trigger and the offer in the facts of context, and the ask in the rules of context. Do not put a customer quote in a fact: a fact is graded as the user's, not a customer's. Then grade the returned message:
{
"mode": "grade",
"channel": "email",
"evidence": "workspace",
"message": "<the message the optimizer returned>"
}B. Message check
Search for what customers say about the problem the message is about:
{
"mode": "semantic",
"query": "why we chose them and what problem we were trying to solve",
"hydrate": true,
"limit": 10
}Grade the user's message exactly as they gave it:
{
"mode": "grade",
"channel": "email",
"evidence": "workspace",
"message": "<the user's message, verbatim>"
}Point out each line that failed grounding or verified_specifics, with its reason: it is where the message and the customers disagree, or where nothing the customers said backs it. A grade covers outbound email and LinkedIn messages; Amdahl does not grade homepage or pitch copy.
Reference
- Search: https://docs.amdahl.ai/endpoints/search
- Message Optimizer: https://docs.amdahl.ai/endpoints/message-optimizer
- Grade a message: https://docs.amdahl.ai/endpoints/message-optimizer/grade-a-message
- Improve a prompt: https://docs.amdahl.ai/endpoints/message-optimizer/improve-a-prompt
- Errors: https://docs.amdahl.ai/api-reference/errors
- What else Amdahl can do, and which tool does each job: https://docs.amdahl.ai/skills/amdahl/SKILL.md. Answer "what else can I do?" from it; do not call tools to find out.