# Manage skills

Last validated Nov 10, 2026

As an Aperture administrator, you manage your organization's skills library from the admin dashboard. The library holds every skill you share with users. Each skill belongs to a source:

* A **Git** source syncs skills from a Git repository or a folder in one.
* A **Site** source syncs skills from a site that publishes them.
* A **Collection** holds skills that your team writes and edits in Aperture.

You decide who can discover each source. Users who can discover a source add the skills they want to **Your skills** and use them in Chat and in agents connected to Aperture. For the user tasks, refer to [Use skills][docs-use-skills].

## Prerequisites

To manage skills, you need the following prerequisites:

* A running [Aperture gateway][docs-get-started].
* The [Aperture admin role][docs-set-up-admin-access]. Only administrators can open the **Skills** and **Skill Activity** pages.

## Add a source

Add a source to sync skills from a Git repository or a site that publishes skills. Aperture detects the kind of source from the link.

1. \[Missing snippet: aperture\_admin\_nav.mdx]
2. Select **Add source**.
3. In **Link**, paste a link to the repository or site, then select **Find skills**. Aperture supports the following links:
   * `https` links to repositories on GitHub, GitLab, Codeberg, Bitbucket, Azure Repos, and self-hosted Gitea, Forgejo, or GitLab servers. Link to a folder to add only the skills in that folder.
   * Sites that publish skills at `/.well-known/agent-skills/index.json`.
4. In **Details**, review the **Display name** and **ID**. The ID is used by grants and skill paths, and you can't change it later.
5. In **Updates**, choose how upstream changes reach the library:
   * **Reviewed** (default): You approve each change first. Until then, users keep the version you approved.
   * **Trusted**: Changes in the source reach users automatically, within an hour.
6. Select **Continue**.
7. In **Skills**, choose what to add from the source, then select **Continue**:

   * **All current and future skills**: Every skill in the source, plus any added to it later.
   * **Only the skills I pick**: Just the ones you select. Skills the source adds later appear on the source's **Not added** tab, where you can add them.

   Before you add a skill, select its name to preview its files. Labels such as **Runs scripts**, **Hidden Unicode**, and **Reads outside its folder** identify skills to inspect closely.
8. In **Visibility**, choose who can discover the source, and optionally add **Labels**. Refer to [Control who can discover skills][ar-control-who-can-discover-skills].
9. Select **Add source**.

If the repository includes a plugin marketplace manifest, skills from other repositories appear on the **Other repositories** tab. To add them, choose **Only the skills I pick**. Changes in skills from other repositories are always reviewed, even on a trusted source.

## Create a collection

Create a collection to hold skills your team writes and edits in Aperture instead of syncing them from a repository.

1. \[Missing snippet: aperture\_admin\_nav.mdx]
2. Select **New collection**.
3. Enter a **Display name** and review the **ID**.
4. In **Who can discover it**, choose who can discover the collection.
5. Select **Create collection**.

To add skills to the collection, open it and select **Add skill**, then choose one of the following:

* **Create a skill**: Enter a **Name** and a **Description**, then select **Create**. The model reads the description to decide when to use the skill. Write the skill's instructions in the editor that opens.
* **Upload a skill**: Upload a `SKILL.md` file, or a `.zip` or `.skill` archive of a skill folder.
* **Import from a link**: Paste a link to a repository or site, select the skills to copy, then select **Import *N* skills**. The copies belong to the collection. Later changes in the repository don't reach them.

## Edit a skill in a collection

Each time you save a skill in a collection, Aperture saves a new version. Everyone who added the skill gets the new version with their next message.

1. \[Missing snippet: aperture\_admin\_nav.mdx]
2. Select the collection, then select the skill.
3. Select **Edit**.
4. Change the skill's files. To add a supporting file, select **Add file** and enter a path, such as `references/style.md`. Link to the file from `SKILL.md` so the model knows when to read it.
5. Select **Save version**, then confirm.

To return to an earlier version, select **History**, open the version you want, select **Restore this version**, then select **Restore** to confirm. Aperture saves the restored content as a new version, and the newer versions stay in **History**. **History** keeps up to 20 earlier versions of a skill, for 30 days each. Older versions expire and you can't restore them.

## Customize a skill from a synced source

Skills from Git and Site sources are read-only. To change one, copy it to a collection.

1. \[Missing snippet: aperture\_admin\_nav.mdx]
2. Select the source, then open the actions menu for the skill and select **Duplicate to…**.
3. Choose a **Collection**, then select **Duplicate**.

The collection owns the copy, so you can edit it there. The original stays as it is, and the copy doesn't receive upstream changes.

## Control who can discover skills

Users find skills only from sources a grant makes visible to them. Grants only add access. A grant for `**` or for a label reaches a new source as soon as you add it, and Aperture warns you when it does. The same visibility applies in Chat and in agents connected over MCP.

### Set visibility for a source

1. \[Missing snippet: aperture\_admin\_nav.mdx]
2. Select the source, then select the **Visibility** tab.
3. In **Who can discover it**, choose one of the following:
   * **Everyone**: Everyone can discover these skills.
   * **Only me**: Only you can discover these skills.
   * **People and groups**: Enter logins, `group:` entries, or `tag:` entries.
   * **Nobody**: Removes this source's own grant.
4. (Optional) In **Labels**, add labels so one grant can cover several sources. For example, a grant for `label:engineering` reaches every source with the `engineering` label.
5. Select **Save changes**.

These options change only the grant for this source. Other grants that reach the source, listed under **Also reached by**, still apply. The **Visibility** tab shows only grants from the Aperture configuration. Grants in your tailnet policy file can also make skills visible, and the tab doesn't show them.

> **Note:**
>
> Tagged devices can't use skills. A `tag:` entry doesn't deliver skills to any device.

### Set visibility with grants

You can also write the grant yourself. Use the `skills` field in a grant for the `tailscale.com/cap/aperture` capability. Each pattern matches skills by `<source-id>/<skill-name>`:

| Pattern                    | Matches                                 |
| -------------------------- | --------------------------------------- |
| `**`                       | Every skill in the library.             |
| `<source-id>/**`           | Every skill in one source.              |
| `<source-id>/<skill-name>` | One skill.                              |
| `label:<label>`            | Every skill in sources with that label. |

1. \[Missing snippet: aperture\_admin\_nav.mdx]

2. Add a grant with a `skills` field. The following example makes the `acme-playbooks` source visible to `group:engineering`, and every source labeled `finance` visible to `group:finance`:

   ```json
   "grants": [
     {
       "src": ["group:engineering"],
       "app": {
         "tailscale.com/cap/aperture": [
           { "skills": ["acme-playbooks/**"] }
         ]
       }
     },
     {
       "src": ["group:finance"],
       "app": {
         "tailscale.com/cap/aperture": [
           { "skills": ["label:finance"] }
         ]
       }
     }
   ]
   ```

3. Save the configuration.

Matching `group:` sources requires [visible groups][docs-visible-groups] enabled for the Aperture gateway.

## Review updates and new skills

Aperture checks public sources for changes within an hour. For a reviewed source, it holds each update until you approve it. If the source tracks **All current and future skills**, it also holds each new skill for review. Until then, users keep the version you approved. The **Skills** item in the sidebar shows how many items are waiting.

1. \[Missing snippet: aperture\_admin\_nav.mdx]
2. Select **Review**. The button shows how many items are waiting. The **Review** page lists items waiting for approval, grouped by source.
3. Select **Review** next to an item. Inspect the changed files and any warnings, such as executable files or hidden Unicode characters.
4. Choose one of the following:
   * **Approve and add** (new skill) or **Approve update** (update): Aperture adds the skill or applies the update for everyone who added it.
   * **Dismiss**: A dismissed new skill moves to the source's **Not added** tab. A dismissed update returns only if the source changes the skill again.

To check a source right away, open it and select **Check for updates**.

## Change how a source updates

1. \[Missing snippet: aperture\_admin\_nav.mdx]
2. Select the source, then select the **Settings** tab.
3. In **Updates**, change **Trust** to **Reviewed** or **Trusted**.
4. In **Tracking**, choose **All current and future skills** or **Only the skills I pick**.
5. Select **Save changes**. If you switched tracking to **All current and future skills**, select **Track all skills** to confirm.

When you switch tracking to **All current and future skills**, Aperture adds the skills under **Not added**. On a reviewed source, they wait for your review. On a trusted source, they become available in **Discover** to everyone who can discover the source. Skills you removed or dismissed stay under **Not added**.

On a trusted source that tracks **Only the skills I pick**, updates to the skills you added arrive automatically, but new skills don't.

## Add skills from a private GitHub repository

Aperture reads a private GitHub repository with your own GitHub connection. Private repositories work only on `github.com`.

1. Make sure your Aperture gateway has a [GitHub connector that uses per-user OAuth 2.0][docs-per-user-oauth2-connector] and that your grants include its `proxy` category.
2. In Aperture Chat, go to **Connectors** and connect GitHub.
3. [Add a source][ar-add-a-source] with a link to the repository.

A private source is always reviewed. Aperture doesn't check it for updates in the background. To find upstream changes, open the source and select **Check for updates**. Aperture reads the repository with your GitHub connection.

## Remove a skill from the library

1. \[Missing snippet: aperture\_admin\_nav.mdx]
2. Select the source, then open the actions menu for the skill.
3. Select **Remove** for a skill from a synced source, or **Delete** for a skill in a collection, then confirm.

Everyone who added the skill loses it. A removed synced skill moves to **Not added**, and syncs don't bring it back unless you add it again. Deleting a collection skill deletes all its versions, and you can't undo it.

## Delete a source or collection

1. \[Missing snippet: aperture\_admin\_nav.mdx]
2. Select the source, then select the **Settings** tab.
3. In **Danger zone**, select **Delete source** or **Delete collection**.
4. If grants in the Aperture configuration name the source, **Remove these grants too** appears and is selected. Leave it selected to remove those grants. If you keep them, they also reach any new source or collection that uses the same ID. Grants for `**` or for labels stay in place either way.
5. Select **Delete source** or **Delete collection** to confirm.

Users who added the source's skills lose them immediately. You can't undo the deletion.

## Turn off skill authoring

By default, every user can create and import personal skills. To make personal skills read-only for some users, set `enable_skill_authoring` to `false` in a grant.

1. \[Missing snippet: aperture\_admin\_nav.mdx]

2. Add a grant for the users:

   ```json
   {
     "src": ["group:contractors"],
     "app": {
       "tailscale.com/cap/aperture": [
         { "enable_skill_authoring": false }
       ]
     }
   }
   ```

3. Save the configuration.

Users without skill authoring can still add library skills. They can't create, import, edit, or copy skills, or turn skills on or off. Their existing personal skills stop reaching their conversations and agents, and the **Skill Creator** skill is hidden. An explicit `"enable_skill_authoring": true` in any grant that matches a user overrides `false`, so don't set `true` on a broad source. Administrators always keep skill authoring.

## Monitor skill usage

Open the Aperture admin dashboard and go to **Usage & Adoption** > **Skill Activity**. The page shows how people use skills in Chat and through agents, and how your library is adopted:

* **Skills**: Each library and built-in skill's source, how many users added it, and how often it was selected in Chat, read by the model, or loaded by an agent.
* **Sources**: How many skills each source has, how many were used, and how many users added them.
* **People**: How many library and personal skills each person used, and how many times they used built-in skills.

Activity for personal skills shows counts only. The page doesn't name personal skills.

## Next steps

* [Use skills][docs-use-skills]: Share the steps users follow to add and use the skills you publish.
* [How grants work][docs-how-grants-work]: Understand how Aperture combines grants from the Aperture configuration and your tailnet policy file.
* [Audit logs][docs-dashboard-admin]: Review who added, changed, or removed sources in the admin dashboard.

[ar-add-a-source]: #add-a-source

[ar-control-who-can-discover-skills]: #control-who-can-discover-skills

[docs-dashboard-admin]: /docs/aperture/reference/dashboard-admin

[docs-get-started]: /docs/aperture/get-started

[docs-how-grants-work]: /docs/aperture/how-grants-work

[docs-per-user-oauth2-connector]: /docs/aperture/how-to/set-up-per-user-oauth2-connector

[docs-set-up-admin-access]: /docs/aperture/how-to/set-up-admin-access

[docs-use-skills]: /docs/aperture/how-to/use-skills

[docs-visible-groups]: /docs/aperture/visible-groups