# Agent setup

> For the agent that just connected: read the docs, then write yourself a skill.

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

This page is for you, the agent the person just connected. They will rarely name a Super Artifacts feature; they will describe what they are making. Your job is to know what the platform can do and offer the right part of it before you build. Do the three steps below once, then stop: connecting never builds anything.

## Check the connection

Call `super_whoami` and tell the person the workspace and email it names. Then call `super_help` with `topic: "tools"`, one line per tool, and with `topic: "data"`, which store a page needs. Every result carries `fix` when it is refused and `next` when it succeeds: read both.

## Read the documentation

`/llms.txt` is the index. Every page in it has a markdown twin at its address with `.md` added; read the twins, in this order:

1. [Create artifacts](https://pr-1744-stg.superartifacts.app/docs/create.md) and [Access and sharing](https://pr-1744-stg.superartifacts.app/docs/access-and-sharing.md): what a publish sends, and who can open the result.
2. [Collect responses](https://pr-1744-stg.superartifacts.app/docs/collect-data.md), [Three shapes of data](https://pr-1744-stg.superartifacts.app/docs/concepts/data.md) and [Collections, insights and dashboards](https://pr-1744-stg.superartifacts.app/docs/workspace-data.md): the data a page keeps.
3. [Shared and live pages](https://pr-1744-stg.superartifacts.app/docs/shared-pages.md) and [Live rooms](https://pr-1744-stg.superartifacts.app/docs/concepts/live-rooms.md).
4. [Get feedback](https://pr-1744-stg.superartifacts.app/docs/comments.md), [Put them in a project](https://pr-1744-stg.superartifacts.app/docs/projects.md), [Rules and the report](https://pr-1744-stg.superartifacts.app/docs/project-rules.md) and [Use a template](https://pr-1744-stg.superartifacts.app/docs/templates.md).
5. [MCP tools](https://pr-1744-stg.superartifacts.app/docs/reference/mcp.md), [Limits](https://pr-1744-stg.superartifacts.app/docs/reference/limits.md), [Error codes](https://pr-1744-stg.superartifacts.app/docs/reference/errors.md) and [Troubleshooting](https://pr-1744-stg.superartifacts.app/docs/troubleshooting.md).
6. [Recipes](https://pr-1744-stg.superartifacts.app/docs/recipes.md): one worked prompt per situation.

`/skill/SKILL.md` complements these pages: it is the HTTP contract, including how a page saves what a visitor types. Copy what you need from it into your skill rather than keeping it as a second skill with the same name.

## Write yourself a skill

Write it where your harness keeps durable instructions: a skill folder if you have one (`super-artifacts/SKILL.md`), otherwise your instructions, memory or project rules file, such as `AGENTS.md`. Name it `super-artifacts`. Write it from what you read, 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, that you are set up and what you can build for them.

## Keep it fresh

When a call answers with a code, field or tool you do not recognise, `unknown_tool` included, re-read `/llms.txt` or `/docs/manifest.json`, then correct your skill.

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