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

# Skills

> Write reusable agent instructions once and decide which members, teams and projects receive them.

**Agents → Skills** stores reusable instructions that your agents load when a task needs them.
A skill is written once, versioned, and shared with the organization, a project, a team or only
you. Agents connected to the [Aixy MCP endpoint](https://docs.aixy-gateway.com/agent-tools/connect-agent.md#use-your-organizations-skills)
receive the skills that apply to them without copying files between machines.

## Create a skill

1. Open **Agents → Skills** and choose **New skill**.
2. Choose the **Scope**. Start with **Only me**, test the skill, and promote it once it works. You
   can create skills only in scopes where you can publish.
3. Choose a **Source**:
   * **Write SKILL.md**: its YAML frontmatter needs a `name` (lowercase letters, digits and
     hyphens) and a `description`.
   * **Upload ZIP**: a package with `SKILL.md` at its root or inside one folder, up to 8 MiB.
     Supporting files such as `scripts/`, `references/` and `assets/` are kept as uploaded.
4. Optionally add a **Title** for the dashboard and comma-separated **Tags**, then choose
   **Create skill**.

Packages follow the open [Agent Skills specification](https://agentskills.io/specification).
Aixy stores and delivers scripts but never runs them; your agent runs them under its own approval
policy.

## Checks and versions

Every version is immutable. Choose **New version** to publish a change; leave **Version number**
empty to bump the patch. Each version runs static checks, shown under **Checks**:

| Result | What it means |
| - | - |
| **Blocked by checks** | Hidden or bidirectional characters, embedded credentials or binary scripts. The version works in its author's own scope but cannot be placed anywhere else. |
| **Check warnings** | Instructions longer than about 5,000 tokens. |
| Listed findings | Scripts and external URLs, shown to reviewers. |

**Fork** copies a skill into your own scope and records where it came from. **Deprecate** and
**Archive** retire a skill without deleting it; archived skills are not delivered to agents.
**Delete** removes every version, placement and request.

## Share a skill with more people

A skill reaches people through **placements**. Each placement binds the skill to a scope with a
mode and a version policy:

| Mode | Behavior |
| - | - |
| **Available** | Agents find it when a task needs it. |
| **Default** | Listed for every agent in that scope. |
| **Required** | Always present; narrower scopes cannot replace it. |

* **Pinned version** keeps the placement on one version until someone changes it, which is also
  how you roll back.
* **Follow new versions** moves the placement when a new version is published. Where the publisher
  has no authority, a review is requested instead.

To place a skill in another scope, choose **Promote**, select the **Target scope**, mode and version
policy, and optionally explain the **Reason**. Someone with authority in the target scope decides;
if that is you, the placement applies at once. The first placement outside your personal scope
transfers ownership to that scope, so shared skills remain when their author leaves. Remove a
placement under **Placements** to narrow the skill's reach again.

## Review requests

**Reviews** lists the promotion and update requests you made or can decide. Reviewers see the
version, the requester's reason and usage before choosing **Approve** or **Reject**. Requesters
can **Withdraw** a pending request.

Owners and Org admins set the organization's **Policy**:

* **Skills with scripts**: **Never share**, **Share after independent review** (the default), or
  **Share like any other skill**.
* **Requesters with authority can approve their own requests**: turn it off to require an
  independent reviewer for every promotion.

## What your agents receive

**What your agents receive** shows the skills resolved for you in the selected project: those
placed in the organization, the project, your teams and your personal scope. When two different
skills share a name, **Required** wins, then the narrower scope (you, project, team,
organization). Equal precedence is shown as a **Conflict** and both are kept.

Agents connected to the Aixy MCP endpoint load these skills with the `aixy_skills` helper. For an
agent without it, choose **Download for local agents** and unzip the file into the agent's skills
folder. The download is a snapshot: it does not update or remove local copies later.

Each skill shows its loads, the members who loaded it, and the last load over the past 30 days.
Usage records which skill and version were loaded, never the skill text, prompts or arguments.

## Who can do what

| Role | Skills access |
| - | - |
| Project user | Browse, use, author, version and request promotion |
| Project admin | Also decides placements in their projects and teams |
| Org admin and Owner | Every skills action, including organization placements and policy |

Skills that only one member owns are visible only to that member, including to administrators.
They are removed with the member's membership. Skills owned by a scope belong to that scope.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.