# Agent setup

> For the agent setting itself up: connect, verify, read the docs, write yourself a skill.

Kind: guide · ~3 min · Verified v0.171.0 · Next: [Create artifacts](https://pr-1778-stg.superartifacts.app/docs/create.md)

You are the agent the person asked to set up Super Artifacts. They will describe what they are making, rarely a feature, so learn what the platform can do and offer it. Do these four steps once, in order, in short messages. Connecting builds nothing: publish only when asked.

## Step 1: Connect

Already see `super_whoami` among your tools? Go to step 2.

1. Add the remote MCP server `https://superartifacts.app/mcp`, named `super-artifacts`, however your harness adds one. [Connect your agent](https://pr-1778-stg.superartifacts.app/docs/connect.md) lists each harness.
2. Sign in over OAuth: the person signs up or signs in with their browser and clicks Allow. No key, client ID or secret.
3. Only if your harness cannot do OAuth, ask the person once for an API key from `/settings/api-keys`, send it as a Bearer token and never print it back.

Stop only for what needs their hands, say so once, and wait. Never register a client, build an authorize URL or write a token file by hand. If the tools need a restart to show up, say so and ask them to paste the prompt again.

## Step 2: Verify

Call the `super_whoami` tool itself; an HTTP call does not count.

- It answers: say "Connected as" and the handle.
- `401`: sign-in did not finish. Ask them to click Connect again.
- Tool not found: redo step 1 once, then say in one line what is missing.

Every result carries `fix` when refused and `next` when it succeeds: read both.

## Step 3: Read the documentation

`/llms.txt` is the index. Add `.md` to any page's address for its markdown. Read, in order:

1. [Create artifacts](https://pr-1778-stg.superartifacts.app/docs/create.md), [Versions](https://pr-1778-stg.superartifacts.app/docs/concepts/versions.md), [Access and sharing](https://pr-1778-stg.superartifacts.app/docs/access-and-sharing.md).
2. [Collect responses](https://pr-1778-stg.superartifacts.app/docs/collect-data.md), [Three shapes of data](https://pr-1778-stg.superartifacts.app/docs/concepts/data.md), [Collections, insights and dashboards](https://pr-1778-stg.superartifacts.app/docs/workspace-data.md).
3. [Shared and live pages](https://pr-1778-stg.superartifacts.app/docs/shared-pages.md), [Live rooms](https://pr-1778-stg.superartifacts.app/docs/concepts/live-rooms.md).
4. [Get feedback](https://pr-1778-stg.superartifacts.app/docs/comments.md), [Put them in a project](https://pr-1778-stg.superartifacts.app/docs/projects.md), [Rules and the report](https://pr-1778-stg.superartifacts.app/docs/project-rules.md), [Use a template](https://pr-1778-stg.superartifacts.app/docs/templates.md).
5. [MCP tools](https://pr-1778-stg.superartifacts.app/docs/reference/mcp.md), [Limits](https://pr-1778-stg.superartifacts.app/docs/reference/limits.md), [Error codes](https://pr-1778-stg.superartifacts.app/docs/reference/errors.md), [Troubleshooting](https://pr-1778-stg.superartifacts.app/docs/troubleshooting.md), [Recipes](https://pr-1778-stg.superartifacts.app/docs/recipes.md).

`/skill/SKILL.md` is the HTTP contract, including how a page saves what a visitor types. Copy what you need into your skill.

## Step 4: Write yourself a skill

Write it where your harness keeps durable instructions: a skill folder (`super-artifacts/SKILL.md`), otherwise your instructions, memory or `AGENTS.md`. Name it `super-artifacts`, short, in your own words.

### What to reach for without being asked

| The person describes | Offer | Tools |
| --- | --- | --- |
| A form, survey, RSVP, sign-up, quiz, vote or feedback box | Saving the answers: a data `policy` at publish | `super_publish`, then `super_data` |
| A list someone keeps and edits: clients, a catalogue, a menu, inventory | A collection with entries, which the page edits through `policy.collections` | `super_data_schema`, `super_entries` |
| A board, plan or roster several people edit together | A shared document that updates on every open screen | `super_help` topic `live` |
| A dashboard or summary of what was collected | Aggregates, or a series joining several artifacts' answers | `super_data_schema`, `super_data_query` |
| Something people should review | Naming them as Commenters, then working through the threads | `super_share`, `super_comments` |
| A page that repeats: weekly, per client, per release | The same slug for each new version, or a project whose rule gathers each one | `super_project` |
| Several pages that belong together | A project, in reading order, with its own audience | `super_project` |
| A design to start from or reuse | An installed or marketplace template | `super_templates`, `super_template_action` |
| An agreement to sign | A signature request on one version | `super_signatures` |
| A call to an API that needs a key | A `pii: secret` collection field; the person approves each host, and you never see the value | `super_entries`, `super_secret_use` |
| Images or video | Staging the files, then publishing with them | `super_upload` |

### The outline your skill must follow

```markdown
---
name: super-artifacts
description: <one line: when to reach for Super Artifacts>
---

## When to use it
<What the person might be making that belongs here, in their words.>

## Reach for without being asked
<The table above, one row per capability.>

## Ask first, then build
When a request implies a row of that table the person did not mention, ask one
short question offering it, and wait for the answer before building:
- "This has form fields. Should I save the answers so you can read them back?"
- "You will keep adding clients. Should they live in a collection you can edit?"
- "Who should review this? I can name them so they can leave comments."
- "Who should be able to open it: just you, or the people you send it to?" Ask this whenever the page is meant for other people, such as a form friends fill in.

## Defaults
- First publish: `visibility: "private"`. Left out, it takes the workspace default.
- Widen access (public, the workspace, a project, a named person) only when asked.
- Give the URL from every publish result, updates included, on its own line.
- To see a private artifact, `super_artifacts` with `open: true`; never change
  its visibility to look.
- The same slug is a new version at the same URL; nothing earlier is deleted.

## Data rules
- A page stores only what its publish-time `policy` declares. Without one,
  nothing is stored; a page using localStorage saves in that browser only. Say so.
- Decide what a row is first: one person's answers, one event, or one item
  everybody edits.
- A policy is additive: a field keeps its type for good. Add a field to change one.
- `super_data_schema` define replaces a whole collection; a field left out is gone.
- Mark fields about a person: `contact` masks it for others, `sensitive` encrypts it.

## Limits and errors
- On `ok: false`, read `code`, `fix` and `accepts`, change the call, then retry.
- `plan_limit`: storage is full and nothing was deleted. Ask what to remove.
- `rate_limited`: wait as long as the message says.
- `mcp_timeout`: a change may have happened. Check before repeating it.
- `approval_required`: give the person `approvalUrl`, then repeat the call.
- Sizes and counts: Limits page. Every code: Error codes page.

## Never
- Build or publish because you connected. Publish only when the person asks.
- Share, or widen an audience, without being asked.
```

Then tell the person, in one line, what you can build for them, and wait.

## Keep it fresh

On a code, field or tool you do not recognise, re-read `/llms.txt`, then correct your skill.

Next: [Create artifacts](https://pr-1778-stg.superartifacts.app/docs/create.md).