spb/skills-spboucher-ai

1---2title: Concepts3description: Skills, MCP servers, the ten artifact types, and what a registry entry does and does not promise.4order: 25section: Start6---78# Concepts910## What is an Agent Skill?1112A skill is a **directory of instructions and supporting files** that an agent loads when a task calls for it. Its entry point is `SKILL.md`: YAML frontmatter with a `name` and a `description`, followed by Markdown instructions. It may include `scripts/`, `references/` and `assets/`.1314```markdown15---16name: citation-check17description: Checks that every citation in a manuscript resolves to a reference. Use when reviewing a paper draft.18---1920# Citation check21221. List every citation key in the manuscript…23```2425The format is an open specification (agentskills.io). Claude Code, Codex and Cursor read it from a skills directory. A skill runs **inside your agent**, with your agent's permissions. Installing one means copying files.2627## What is an MCP server?2829A Model Context Protocol server is a **program that exposes tools** (and optionally resources and prompts) to an agent over a protocol. It runs as its own process:3031- **stdio**: your client starts a command on your machine and talks to it over standard input and output.32- **Streamable HTTP**: your client connects to a URL operated by someone.3334Installing one means adding an entry to your client's MCP configuration.3536## How they differ3738| | Agent Skill | MCP server |39|---|---|---|40| What it is | Instructions and files | A running program with typed tools |41| Where it runs | Inside the agent's own context | A separate local process or a remote service |42| Install | Copy a directory | Add a configuration entry |43| Needs secrets | Rarely | Often (API keys, set locally by you) |44| Main risk | Instructions or scripts you did not read | Code you run, or a remote operator you send data to |4546They combine well: a skill can describe *how* to use the tools an MCP server provides.4748## A listing is not a hosted server4950An MCP entry in this registry is **metadata**: transport, the command or URL, required environment variables, tool descriptions, source link, and usually a source archive. The registry does not run, proxy or vouch for the server.5152- For a stdio server, *you* run the command on your machine.53- For a remote server, the endpoint belongs to the publisher. Your requests go to them.5455The one MCP server the registry itself operates is its own: the [registry MCP endpoint](/docs/mcp), for searching and publishing.5657## The ten artifact types5859| Type id | What it is |60|---|---|61| `skill` | Directory with a standards-compatible `SKILL.md` |62| `mcp-server` | MCP server listing: transport, install data, tools |63| `agent` | Reusable agent persona, role, instructions and constraints |64| `prompt-pack` | Curated, versioned prompts and templates |65| `workflow` | Multi-step agent pipeline with examples |66| `connector` | API adapter or agent-callable utility |67| `hook` | Event-driven local or server-side extension |68| `bundle` | Group of registry items with locked dependency versions |69| `eval-kit` | Benchmark harness, test cases, fixtures |70| `template` | Starter project or agent configuration scaffold |7172The type of an artifact is fixed when it is created.7374## Capability labels7576Types do not share install semantics, so each artifact also carries explicit capability labels. Publishers may state them; otherwise they are derived from facts in the release.7778| Label | Meaning |79|---|---|80| `downloadable` | A release archive exists. |81| `installable` | A supported client can install it by copying files or adding configuration. |82| `remote-endpoint` | It points at a service operated by the publisher. |83| `documentation-only` | Nothing to install or run. |84| `source-linked` | A source repository is declared. |85| `executable` | The archive contains scripts, executables or binaries. |8687Nothing in the registry is executed by the registry.8889## Names, versions and immutability9091- An artifact is named `@namespace/slug`. A namespace belongs to one publisher.92- Versions are strict semantic versions (`1.2.0`, `2.0.0-beta.1`).93- A published version is **immutable**. A fix is a new version. A dangerous version is **revoked**: it stays in the history with a public reason and can no longer be downloaded.94- `latest` is the highest stable published version; a prerelease is `latest` only when no stable version exists.9596## Visibility and state9798| Visibility | Who can see it |99|---|---|100| `public` | Everyone; appears in search and listings |101| `unlisted` | Anyone with the link; not in search or listings |102| `private` | Only the publisher |103104| State | Meaning |105|---|---|106| `draft` | Created, no published release yet |107| `active` | Has at least one published release |108| `deprecated` | Still downloadable; the publisher recommends something else and says why |109| `archived` | Closed to new releases; hidden from listings, reachable by link |110| `taken down` | Removed by moderators |111112## Declared permissions113114A manifest can declare what the package needs: `filesystem:read`, `filesystem:write`, `network`, `shell`, `env`, `mcp`, `browser`, `credentials`. These are **the publisher's statements**, shown before install. The scanner notes when scripts appear to use the network or spawn processes without declaring it. Declarations are not enforced by the registry; your client's own permission system is what enforces anything.115