AIOps Bot Platform
Console

Skills Registry

Discover, contribute, add, and deploy Agent Skills across IBM projects.

The Skills Registry is an IBM-wide catalog of portable Agent Skills. A skill is a directory that follows the agentskills.io specification: it contains a SKILL.md file with YAML frontmatter and Markdown instructions, plus optional scripts/, references/, and assets/ folders.

Use the registry to:

  • Find skills contributed by other IBM users.
  • Contribute your own GitHub repository of skills.
  • Add selected skills to a project.
  • Link a complete repository to a project for automatic skill discovery.
  • Deploy project skills to one or more agents.
  • Link project repositories to agents for automatic delivery updates.
  • Deploy a skill or complete repository directly from the global registry.

How skills work

The admin server provides the registry and writes managed skill directories into the project workspace. Each agent receives an agent-specific workspace snapshot containing only the registry skills assigned to it. Bot-agent scans the configured skills folder and loads SKILL.md content when a skill is relevant.

Find skills from other people

Open Skills in the top navigation, or go to /skills. Use the Skills and Repositories tabs to switch between individual skills and repository channels. The repository view includes every public repository plus your own private repositories.

The registry list includes skills you can access:

  • Public skills contributed by any user.
  • Private skills from repositories you contributed.
  • Private skills that were added to a project you belong to.

You can search by:

  • Skill name.
  • Repository owner/name.
  • Contributor name or email.
  • Skill description keywords.

Open a skill detail page to see:

  • Skill name and description.
  • Repository path.
  • Contributor details.
  • License and compatibility fields, when provided.
  • Rendered SKILL.md instructions.

Contribute your own skills repository

Users contribute repositories, not individual skills. A single repository may contain one or many skill directories. The sync process discovers each SKILL.md file automatically.

Go to Skills → Repositories, or /skills?tab=repositories, then choose Add Repository. Repositories you contributed show a Yours badge and owner-only controls for sync, token updates, and deletion.

Supported repository sources:

  • Public https://github.com/<owner>/<repo> repositories.
  • Public https://github.ibm.com/<owner>/<repo> repositories.
  • Private or internal https://github.ibm.com/<owner>/<repo> repositories with an access token.

Accepted URL formats include HTTPS URLs and SSH-style GitHub URLs such as git@github.ibm.com:owner/repo.git.

Repository scope

When adding a repository, choose a scope:

  • Public — discovered skills are visible to all authenticated users.
  • Private — discovered skills are visible only to you, unless you add a skill from the repository to a project.

When a private skill is added to a project, every member of that project can see and deploy that skill inside that project.

Private repository tokens

Private repositories require an access token that can read the repository.

Tokens are stored in the platform HashiCorp Vault at a path like:

platform/skill-repo-tokens/<repositoryId>

The token is never stored in Postgres. The database stores only the Vault path and token health metadata.

When you add or update a token, the server tests access to the repository before saving it. If a later sync gets a 401 or 403 from GitHub, the repository is marked as needing a token update and the UI shows an Update Token action.

Push webhooks

Repository owners can use Webhook on a repository card to generate a repository-specific payload URL and signing secret. Add those values under the GitHub repository's Settings → Webhooks page with:

  • Content type set to application/json.
  • Only Push events selected.
  • Active enabled.

The secret is shown only when it is generated or rotated. It is stored in the platform Vault below platform/skill-repo-webhooks/<repositoryId>/ and is never stored in Postgres. Incoming requests must include GitHub's valid X-Hub-Signature-256 signature.

Signed ping events verify the setup without starting a sync. Pushes start a sync only when they target the repository's configured ref, or its default branch when no ref was configured. Other branch and tag pushes are acknowledged without consuming a sync allowance.

Validate your repository

The registry parses SKILL.md frontmatter and requires at least:

---
name: my-skill
description: What this skill does and when to use it.
---

Before adding a repository, validate it locally with:

npx check-skills validate . --recursive

For agent-friendly output, use:

npx check-skills validate . --recursive --llm

This catches malformed frontmatter, missing descriptions, invalid names, and common quality issues before the daily sync runs.

Sync behavior

Skill repositories are synced daily by cron at 3 AM. The cron reconciles the least-recently-synced repositories first and respects each owner's remaining combined daily allowance.

During sync, the server:

  1. Reads the repository tree through the GitHub API.
  2. Finds every SKILL.md file.
  3. Parses frontmatter and stores the full SKILL.md content in the database.
  4. Computes a content hash for update detection.
  5. Adds new skills.
  6. Updates changed skills.
  7. Marks removed skills as removed.
  8. Updates linked agents automatically: new skills appear, changed skills are replaced, and removed skills are deleted from the project workspace skills folder and disappear from agent workspace snapshots.
  9. Updates repository sync status and token health.

You can also trigger Sync manually from Skills → Repositories for a repository you contributed.

Daily sync allowance

Webhook, manual, and scheduled syncs share a combined per-user daily allowance. The system default comes from SKILL_REPOSITORY_DAILY_SYNC_LIMIT and is 5 when the variable is absent or invalid. The allowance resets at 00:00 UTC.

Only synchronization executions that actually start consume the allowance. Invalid webhook requests, ignored refs, duplicate GitHub deliveries, and pushes coalesced into an already pending execution do not consume it. A started sync does consume one slot even when GitHub access or workspace deployment later fails.

Administrators can view today's usage and set a positive per-user override from Admin → Repository Sync Allowances. Leaving the override blank restores the system default.

Add skills to a project

Open a project and select the Skills tab.

Project members with write or admin access can add skills from the registry to the project. Once added, the skill is visible to all project members.

Adding a skill to a project does not automatically deploy it to agents. It makes the skill available for deployment inside that project.

Link a repository to a project

Repository contributors can use Link My Repository on the project Skills tab to link one of their contributed repositories. Project members with write access can also deploy any public repository directly from the global registry. The project immediately sees every active skill in that repository, including skills discovered by future syncs.

This is the best option for larger or frequently changing repositories. Keep using individual project skills when the project needs a small curated set.

After a repository is linked, project members with write or admin access can choose Manage Agents and link the complete repository to one or more agents. No follow-up deployment is needed after repository syncs.

Deploy skills to agents

From the project Skills tab, choose Deploy on a skill. For a faster workflow, choose Deploy beside a skill or repository in the global registry, then select a writable project followed by one or more agents. The server adds the skill or links the repository to the project automatically.

You can deploy a skill to:

  • One agent.
  • Multiple selected agents.
  • All agents in the project.

The server records each deployment with the skill's current content hash and writes the deployed files into the project workspace. Agents receive them through GET /api/runtime/workspace with the rest of the workspace.

If an agent is linked to a repository and the same skill is also deployed manually, the project UI marks the overlap. Changing the manual deployment does not affect delivery while the repository link remains active.

Workspace convention

New project workspaces place managed skills at the workspace root:

${PROJECT_WORKSPACE}/{projectId}/
└── skills/
    └── <skill-name>/
        └── SKILL.md

Existing projects continue to use .agents/skills/ until a project admin moves the folder from the Files page. The configured folder is read-only in the file explorer because deployments are managed through the Skills Registry.

Repository and skill visibility

Visibility works at three levels:

  • Repository scope controls who can discover the skill in the global registry.
  • Project membership controls who can see skills added to a project.
  • Agent deployment or repository link controls which agents receive a skill through the runtime API.

This means a private repository can stay private to the contributor while a specific skill from that repository is shared with a project team.

Troubleshooting

If a repository does not sync:

  • Check the repository URL.
  • Confirm the token has read access to the repository.
  • Click Update Token if the token status is expired or missing.
  • Run npx check-skills validate . --recursive locally.
  • Use Sync from /skills?tab=repositories after fixing the repository.
  • Confirm the repository owner's combined daily sync allowance is not exhausted.
  • For webhooks, verify the payload URL, secret, JSON content type, Push event, and tracked branch or tag in GitHub settings.

If a skill is missing from the registry:

  • Ensure the file is named exactly SKILL.md.
  • Ensure SKILL.md has valid YAML frontmatter.
  • Ensure name and description are present.
  • Confirm the repository sync has run after your latest push.