Visit us at ReInvent How to find us →

Manage skills

Last validated:

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.

Prerequisites

To manage skills, you need the following prerequisites:

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. Open the Aperture admin dashboard and go to Administration > Skills.

  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.

  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. Open the Aperture admin dashboard and go to Administration > Skills.

  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. Open the Aperture admin dashboard and go to Administration > Skills.

  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. Open the Aperture admin dashboard and go to Administration > Skills.

  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. Open the Aperture admin dashboard and go to Administration > Skills.

  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.

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>:

PatternMatches
**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. Open the Aperture admin dashboard and go to Administration > Configuration.

  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:

    "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 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. Open the Aperture admin dashboard and go to Administration > Skills.

  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. Open the Aperture admin dashboard and go to Administration > Skills.

  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 and that your grants include its proxy category.
  2. In Aperture Chat, go to Connectors and connect GitHub.
  3. 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. Open the Aperture admin dashboard and go to Administration > Skills.

  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. Open the Aperture admin dashboard and go to Administration > Skills.

  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. Open the Aperture admin dashboard and go to Administration > Configuration.

  2. Add a grant for the users:

    {
  "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: Share the steps users follow to add and use the skills you publish.
  • How grants work: Understand how Aperture combines grants from the Aperture configuration and your tailnet policy file.
  • Audit logs: Review who added, changed, or removed sources in the admin dashboard.