> ## Documentation Index
> Fetch the complete documentation index at: https://docs.major.build/llms.txt
> Use this file to discover all available pages before exploring further.

# Overview

> Reusable instruction bundles that extend what your agents can do.

Skills are reusable bundles of instructions, reference material, and scripts that you attach to agents. Instead of duplicating the same guidance across every agent's system prompt, you author a skill once and attach it wherever it's needed. Skills follow Anthropic's [Agent Skills](https://www.anthropic.com/news/skills) convention.

## What's in a skill

A skill is a versioned bundle of files:

```text theme={null}
SKILL.md          required - frontmatter (name, description) and instructions
references/*.md   optional - longer reference material the agent reads on demand
scripts/*.ts      optional - scripts the agent runs, e.g. to call a connector
package.json      scaffolded for you; add dependencies here if scripts need them
```

When an agent with an attached skill runs, it sees each skill's `description` and loads `SKILL.md` only when the task calls for it. It reads references or runs scripts only when it needs them, so attaching a skill doesn't bloat every prompt.

<Tip>
  The `description` decides when an agent loads the skill. Say what it does, when to use it, and the phrases users might say. For example: "Fetches and summarises Stripe charges and refunds. Use when the user asks to summarise charges, look up a refund, or mentions a Stripe customer id."
</Tip>

### Scripts

Scripts do real work, such as querying a connector. `@major-tech/resource-client` is preinstalled, so a script can call any connector the agent has access to without handling credentials (see [Resource client](/learn/connectors/resource-client)). A script prints one JSON line to stdout, `{"ok": true, ...}` or `{"ok": false, "error": "..."}`, and exits non-zero on failure.

## Building a skill

Describe the skill to the [Platform Agent](/build/platform-agent) or any client connected through [MCP](/build/mcp), and it writes the bundle on the skill's sandbox, where scripts can be tested before saving. You can also edit the files yourself with the [CLI](/reference/cli/skill).

## Attaching skills to an agent

In the agent builder, attach or detach skills from your agent. Major suggests skills and the connectors they recommend based on what your agent does. A single skill can be attached to many agents, and updating the skill updates the behavior everywhere it's used.

## Versioning

Skills are versioned, with two separate steps:

* **Save** writes the bundle as a new immutable version. Attached agents don't see it yet.
* **Publish** points the skill at its latest saved version. Attached agents load the published version from their next run.

You can roll back by publishing an earlier version.

## Access

Skills use three roles (**User**, **Editor**, **Admin**) so authoring can be separated from use, and deletion is blocked while a skill is still attached to an agent. See [Access & Permissions](/learn/agents/access#skills) for the full breakdown.

## Activity

Skill usage is logged: when a version is published, when a skill is attached or detached from an agent, and when an agent loads a skill or runs one of its scripts at runtime. This gives you an audit trail of how each skill is being used.