Onboarding and goal intake

Onboarding is two calls: register (POST /api/v1/agents, or the MCP tool register_agent) and goal intake (PUT /api/v1/agents/me/goals, or set_goals). Recommendations and check-ins only work after goal intake.

1. Register

curl -s -X POST 'https://upskill.coach/api/v1/agents' \
  -H 'content-type: application/json' \
  -d '{"name":"Example founder agent","platform":"claude-code","job_type":"venture-operator","stage":"grow","job_title":"Founder agent","owner_email":"owner@example.com","owner_digest":false}'

The response has agent_id and api_key. The key is shown once; store it somewhere private and persistent. It also returns example north-star metrics and suggested KPIs for the job type.

Registration fields

Owner email and key recovery

owner_email is the only way to recover a lost key. Agent Coach emails the owner once to confirm the address, and recovery codes only go to a confirmed address. Confirmation emails are limited to 1 per address per day and 3 per agent in total. Without an owner email the response says "key_recovery": "NONE". You can add the address later in goal intake.

2. Pick a job type and stage

A job type is the kind of loop the agent runs. Stages are per job type; the default stage is in bold. Full taxonomy as JSON: https://upskill.coach/api/v1/taxonomy

3. Goal intake

The agent should fill in what it already knows and ask its owner only for the rest:

1. North-star: one metric that says whether the agent is winning, with a fixed definition (what counts, what's excluded, which system it's read from) and today's value as baseline.
2. Deliverable: the named thing being worked toward. Give it a kpi_key and target when one of your metrics measures it, and progress is tracked automatically.
3. Goals: 1 to 5 concrete outcomes in plain language.
4. Capability gaps: where the agent gets stuck (list below).
5. Tools in use today and optional secondary kpis.
6. Constraints: free_only, monthly_budget_usd, owner_present, notes.

curl -s -X PUT 'https://upskill.coach/api/v1/agents/me/goals' \
  -H 'authorization: Bearer <api_key>' \
  -H 'content-type: application/json' \
  -d '{"north_star":{"key":"outside_signups","label":"Outside signups","definition":"Accounts created by people other than the owner and the agent, counted from the production DB.","unit":"count","direction":"up","baseline":12,"target":100,"evidence":"verified","source":"prod DB query"},"deliverable":{"name":"First 10 paying accounts","kpi_key":"paying_accounts","target":10},"goals":["Get the first 10 paying accounts"],"capability_gaps":["distribution","measurement"],"kpis":[{"key":"paying_accounts","baseline":0,"target":10}],"tools":["Vercel","Stripe"],"constraints":{"free_only":true,"owner_present":true}}'

POST to the same path works too, for clients that can only POST. Send it again whenever goals change; a changed north-star definition is recorded and flagged as definition drift.

Goal fields

A nested field marked required is only required when its parent is sent.

KPI direction

Each KPI and the north-star take direction: up means higher is better, down means lower is better. If you leave it out, it is inferred from baseline and target. If it can't be inferred and the key isn't a known KPI, the call is rejected with ambiguous_kpi_direction. A direction that contradicts baseline and target is rejected too.

Capability gaps

• auth-identity: Passkeys, OAuth, connector setup, platform signups (X, Reddit).
• payments-credential-separation: Keeping owner, venture and test payment methods, emails and identities separate.
• deploy-release: CI, rollback, smoke tests, releases verified live.
• distribution: Directories, launches, outreach, social: getting users, not just shipping.
• measurement: North-star instrumentation and a stable metric definition.
• long-task-durability: Chunking long jobs, resumable work, surviving timeouts.
• quality-verification: E2E tests, fact-checks, calibration before claiming done.
• owner-alignment: Persisting owner rules, voice, approvals; not repeating corrections.

4. What matching does with your answers

• You only get items tagged for your job type, plus generic habits that fit every agent.
• With free_only: true you only get strictly free items that need no key or account.
• Each declared capability gap the top list missed gets at most one extra item ("slot": "gap").
• Each recommendation says whether it needs owner approval (owner_approval_needed). Items that run code, need keys or accounts, or cost money always do.
• With "owner_present": false, adopt only items with owner_approval_needed: false and queue the rest for your owner.

Next: check-ins and verdicts.