# Aback Skills, full documentation for agents

> A free, verified marketplace for agent skills. Authors publish a `SKILL.md`
> for free. An admin reviews it. Once approved it is publicly available and
> any agent that speaks the Model Context Protocol can install it into a
> project with a single tool call.

This file is the long form of https://abackskills.com/llms.txt. It
contains the same information plus the full tool schemas, the plan limits
and the operational rules.

---

## 1. What a skill is

A skill is a markdown file, `SKILL.md`, that teaches an agent how to do one
specific thing well.

The format is three sections:

    # Instructions
    What the agent does, step by step.

    # Rules
    The constraints that must hold. What the agent must not do.

    # Examples
    Concrete input and output pairs that show the expected behaviour.

A skill is a prompt, a procedure and a set of examples, in a format an agent
can read at the point of use. It is not an executable program. A skill may
describe commands the agent should run, and the review pipeline flags that,
but the platform never executes a skill.

## 2. The lifecycle

    submit  ->  analysed  ->  admin review  ->  published  ->  installed

1. **Submit.** The author uploads a markdown file or a zip archive
   containing one. The author picks a category and a visibility.
2. **Analyse.** The platform parses the file, checks its structure, and
   scores its risk. Nothing that is uploaded is ever executed. The archive
   reader refuses symlinks, path traversal, compression bombs and
   unsupported compression methods.
3. **Review.** An admin reads the skill and the risk signals, and approves
   or rejects it. The riskiest submission is reviewed first.
4. **Publish.** An approved skill appears in the public directory and
   becomes installable over MCP. A private skill is installable by its
   owner but never listed publicly.
5. **Install.** The install is recorded, and the skill's public install
   count goes up.

## 3. The MCP server

    POST https://abackskills.com/mcp

Streamable HTTP, stateless. There is no session id and no handshake beyond
the standard MCP `initialize` call. Responses are `application/json`.

### Authentication

    Authorization: Bearer abk_live_<key>

Or, for clients that cannot set headers:

    POST https://abackskills.com/mcp?api_key=abk_live_<key>

Keys are created at https://abackskills.com/dashboard/mcp. The plaintext key
is shown exactly once. Only a keyed hash is stored, so a database leak
cannot be replayed against the endpoint.

### Initialization

    {
      "jsonrpc": "2.0",
      "id": 1,
      "method": "initialize",
      "params": {
        "protocolVersion": "2025-06-18",
        "capabilities": {},
        "clientInfo": { "name": "your-agent", "version": "1.0.0" }
      }
    }

The server responds with its protocol version, its capabilities
(`tools`, `resources`, `logging`) and its identity:

    {
      "result": {
        "protocolVersion": "2025-06-18",
        "capabilities": { "tools": {}, "resources": {} },
        "serverInfo": { "name": "aback-skills", "version": "1.0.0" }
      }
    }

### Tool schemas

#### search_skills

Search the approved catalogue.

| Argument | Type | Required | Description |
| --- | --- | --- | --- |
| `query` | string | no | Every whitespace-separated token must match the name, the description or the tags |
| `category` | string | no | Restrict to one category |
| `tag` | string | no | Restrict to skills carrying this tag |
| `limit` | integer | no | 1 to 50, default 20 |
| `offset` | integer | no | 0 to 1000, default 0 |

Returns `skills`, a list of summaries, each with `slug`, `name`, `version`,
`description`, `author`, `category`, `tags`, `risk` and `installCount`.

#### get_skill

Read one approved skill.

| Argument | Type | Required | Description |
| --- | --- | --- | --- |
| `slug` | string | yes | The skill slug |
| `version` | string | no | Pin an exact version, default the latest approved |
| `include_content` | boolean | no | Set false for metadata only |

Returns the summary plus `content`, the full `SKILL.md`, and `contentHash`,
the SHA-256 of the normalised content.

#### install_skill

Install a skill into a project.

| Argument | Type | Required | Description |
| --- | --- | --- | --- |
| `slug` | string | yes | The skill to install |
| `version` | string | no | Pin an exact version |
| `project` | string | no | The install target, created on first use |
| `target_dir` | string | no | Defaults to `.agents/skills` |

Returns `files`, an array of `{ path, content }`, plus the resolved
`project` and the `contentHash` of each file. Write the files exactly as
given.

    {
      "files": [
        {
          "path": ".agents/skills/code-review/SKILL.md",
          "content": "# Instructions\n..."
        }
      ]
    }

#### list_installed_skills

List what is installed, optionally scoped to one `project`. Each entry has
`slug`, `version`, `project`, `projectName` and `installedAtIso`.

#### remove_skill

Remove an installation. Takes `slug` and `project`. Returns `removed` and
the `files` to delete.

#### list_projects

List the install targets. Each has `slug`, `name`, `description`, `status`
and `installedSkills`.

#### check_updates

Compare each installed version against the latest approved version.
Returns `checked` and `updates`, each with `slug`, `installedVersion` and
`latestVersion`.

#### get_usage

Report the billing period, the allowance, the resolutions used and the
resolutions remaining, plus the plan limits. This call is never charged.

### Resources

| URI | Contents |
| --- | --- |
| `aback://catalog` | The catalogue index, as JSON |
| `aback://skills/{slug}` | The full `SKILL.md`, as markdown |
| `aback://skills/{slug}/{version}` | The full `SKILL.md` at an exact version |

### Error codes

| Code | Meaning |
| --- | --- |
| -32700 | Parse error. The body was not valid JSON |
| -32600 | Invalid request. The envelope was malformed |
| -32601 | Method not found |
| -32602 | Invalid params |
| -32603 | Internal error |
| -32001 | Unauthorized. The API key is missing, unknown, revoked or expired |
| -32002 | Forbidden. The key does not have the scope the tool needs |
| -32003 | Not found. No approved skill matches the slug |
| -32004 | Quota exceeded. The monthly allowance is exhausted |
| -32005 | Plan required. The account is on a plan that does not include this |
| -32007 | Invalid input. An argument is the wrong type or out of range |

## 4. The public REST API

No key, no quota, unlimited reads.

    GET https://abackskills.com/api/skills?query=code&category=engineering&page=1&pageSize=20&sortBy=created_at_desc
    GET https://abackskills.com/api/skills/{slug}

`sortBy` is one of `created_at_desc`, `created_at_asc` or `risk_score_desc`.

The list response carries the summary fields and a `pagination` object with
`page`, `pageSize`, `totalCount`, `totalPages`, `hasNextPage` and
`hasPreviousPage`.

The detail response carries `description`, `category`, `tags`, `author`,
`installCount`, `contentHash`, `examples`, `codePreviews` and a `riskPanel`
with the risk summary and the review flags.

The public API never returns the raw content of a skill. The content is
served over MCP, which is where the install happens.

## 4a. Publishing a skill over HTTP

Publishing is free. The endpoint is the same one the dashboard form uses.

    POST https://abackskills.com/api/skills/upload
    Content-Type: multipart/form-data
    Cookie: aback_auth_session=<session cookie>

The session comes from the Google sign in. The request body carries the
skill and its metadata:

| Field | Type | Required | Meaning |
| --- | --- | --- | --- |
| `mode` | string | yes | `markdown` or `zip` |
| `markdown` | string | for markdown mode | The `SKILL.md` content |
| `markdownFile` | file | for markdown mode | The same content as a file |
| `zipFile` | file | for zip mode | The archive |
| `name` | string | yes | The display name |
| `description` | string | yes | One or two sentences |
| `version` | string | yes | A semver string. A new version of an existing slug goes through review again |
| `author` | string | no | The author name |
| `category` | string | no | A catalogue category. `general` if it is left out |
| `tags` | string | no | Comma separated, or repeated for each tag |
| `isPrivate` | boolean | no | `true` keeps the skill out of the public directory |

`tags` is split on commas, the same way the dashboard form splits it. A
repeated `tags` field works too: `tags=code&tags=review` and
`tags=code,review` produce the same two tags.

The response is `201` with the submission, its risk summary and the review
flags:

    {
      "status": "success",
      "data": {
        "submission": {
          "id": "01M5G9Q5ADAYB4NHS4GCVKAQJ5",
          "slug": "code-review",
          "name": "Code Review",
          "version": "1.0.0",
          "mode": "markdown",
          "verified": false,
          "createdAtIso": "2026-10-21T22:36:11.469Z",
          "risks": { "hasExternalLinks": false, "hasScripts": false, "hasCommands": false, "riskScore": 0 }
        }
      },
      "meta": { "reviewStatus": "accepted", "requiresExternalLinkReview": false }
    }

`verified` is `false` on a new submission. It becomes `true` when an admin
approves it, and only then does the skill appear in the directory and
become installable.

A slug and a version together are reserved globally. A second submission
of the same pair is a `409`, whether it comes from the same author or a
different one.

## 5. Plans and limits

Publishing is free on every plan. There is no listing fee, no upload limit
and no revenue share, on any plan.

| | Free | Pro | Team |
| --- | --- | --- | --- |
| Monthly price | $0 | $9 | $29 |
| Annual price | $0 | $90 | $290 |
| Publish skills | Unlimited | Unlimited | Unlimited |
| Public directory and REST API | Unlimited | Unlimited | Unlimited |
| MCP API keys | 1 | 5 | 25 |
| Install targets (projects) | 1 | 10 | Unlimited |
| Skill resolutions per month | 500 | 25,000 | 250,000 |
| Private, unlisted skills | No | 10 | Unlimited |
| Version pinning | No | Yes | Yes |
| Release webhooks | No | Yes | Yes |
| Team seats | 1 | 1 | 5 |

A resolution is one call that returns skill content. A search costs a tenth
of a resolution. The allowance resets on the first day of each month, in
UTC.

## 6. Visibility rules

- An approved, public skill is visible to everyone.
- A private skill is visible only to the account that published it. It is
  installable over MCP but never appears in the public directory or the
  public REST API.
- An unapproved skill is never visible over MCP, not even to its author.
  Approval is the gate for distribution.

## 7. Reading the risk signals

Every approved skill carries a risk summary:

    {
      "score": 42,
      "hasExternalLinks": false,
      "hasScripts": true,
      "hasCommands": false
    }

The score runs from 0 to 100. It reflects how many things the skill asks
the agent to reach for beyond reading text: an external link, a script, a
shell command.

A high score is not a defect, it is information. A skill that generates
files legitimately runs commands. An agent should read the signals and
decide, not treat a high score as a refusal.

## 8. Operating rules

- Do not execute a skill's content. Read it and follow it.
- Verify an install against the `contentHash` the server returns.
- Pin a version with `version` when reproducibility matters. Otherwise the
  latest approved version is installed.
- Call `check_updates` before a long-running job if the skill is critical.
- Respect the quota. The error at -32004 names the plan and the reset date.

## 9. Links

- Catalogue: https://abackskills.com/skills
- MCP guide: https://abackskills.com/docs/mcp
- Pricing: https://abackskills.com/pricing
- Short form: https://abackskills.com/llms.txt
- AI catalogue: https://abackskills.com/.well-known/ai-catalog.json
- MCP server card: https://abackskills.com/.well-known/mcp/server-card.json
- Agent skills index: https://abackskills.com/.well-known/agent-skills/index.json
- OpenAPI: https://abackskills.com/openapi.json
- Sitemap: https://abackskills.com/sitemap.xml