Private Skill Registry

The private skill registry lets you publish skills to make them available for other workspaces to install, track versions and approval status, and monitor usage across your organization.

When to use the registry

Use the skill registry when you want to:

• Share a skill with other workspaces in your organization
• Version and approve skills before teams use them
• Track which skills are popular or unused
• Provide a curated library of internal tools and helpers

If you're creating a skill just for your own workspace, you don't need the registry — create it directly.

Skill visibility

Every skill has a visibility setting that determines who can see and install it:

When you create a skill, it starts as private.

Publishing a skill version

Once a skill is stable, you can publish it to create an immutable snapshot that can be reviewed and installed:

1. Open the skill in Skills
2. Click Publish (or Publish New Version if there's an older version)
3. Fill in changelog — describe what's new or what changed
4. Click Publish

The skill is now in pending_review status. A workspace admin or approver can then review and approve it.

Publishing creates a version:

• Version 1 — first published version
• Version 2 — next time you publish after changes
• Version 3, 4, etc.

Each version is immutable — you can't edit a published version. To make changes, edit the draft skill and publish a new version.

Approval workflow

Published skills follow an approval workflow:

1. Author publishes

Author clicks Publish and the skill moves to pending_review.

2. Reviewer approves or rejects

A workspace admin or reviewer can:

• Approve — skill moves to approved and can be installed by other workspaces
• Reject — skill stays in draft; author can make changes and re-submit

To review a skill:

1. Go to Skills → Pending Review
2. Click on the skill
3. Review the code and changelog
4. Click Approve or Reject

3. Approved skills are installable

Once approved, other workspaces see the skill in their Skills → Registry and can install it.

Installing a skill

To install a skill published by another workspace:

1. Go to Skills → Registry
2. Browse approved skills from other workspaces
3. Click Install on a skill
4. Confirm the installation

AACWorkflow creates a local copy of the skill in your workspace, pinned to the version you installed. Your copy is independent — edits to the source skill don't automatically update your copy.

To update to a newer version of an installed skill:

1. Go to Skills → Installed
2. Find the installed skill
3. Click Update

The latest approved version is pulled into your workspace.

To uninstall a skill:

1. Go to Skills → Installed
2. Find the skill
3. Click Uninstall

The local copy is removed, but agents using it are updated to show the skill is unavailable.

Version history and diffing

Each published version is preserved, and you can view the full history:

1. Open a skill
2. Click the Versions tab
3. See all published versions with:
   • Version number
   • Author and publish date
   • Changelog
   • Diff from the previous version

To see what changed between versions:

1. In the Versions tab, select two versions
2. Click View Diff

Lines removed are shown in red; lines added are in green.

Usage metrics

Track how often a skill is being used:

1. Open a skill
2. Go to the Metrics tab

You'll see:

• Agents using it — how many agents have the skill linked
• Tasks executed — total number of tasks that ran with the skill
• Last used — when the skill was last executed

Use these metrics to:

• Identify popular skills
• Find unused skills (consider removing them)
• Understand skill adoption across your organization

Organizing skills

Visibility strategy

• Private — experimental or personal skills; not ready to share
• Workspace — skills everyone in your workspace uses
• Organization — stable, reviewed tools other teams should know about

Naming conventions

Use descriptive names that include the domain or tool:

• github-pr-reviewer — reviews GitHub PRs
• aws-cost-analyzer — analyzes AWS costs
• sql-optimizer — optimizes SQL queries
• internal-docs-generator — generates internal documentation

Organization

Within a workspace, use tags or prefixes to group related skills:

• github-* — all GitHub-related skills
• aws-* — all AWS-related skills
• internal-* — internal-only tools

Best practices

• Publish only stable skills — test thoroughly before publishing
• Write clear changelogs — help reviewers and users understand what changed
• Version carefully — don't jump versions; use semantic versioning (1.0 → 1.1 → 2.0)
• Keep skills focused — one skill, one job; split if doing multiple things
• Archive old versions — after a new version is approved, users shouldn't need the old one
• Document dependencies — if a skill needs external tools or APIs, document that clearly

Version management

When a new version is published:

1. Old version stays approved — existing installs continue to work
2. New version enters pending review — must be approved
3. Users can upgrade — click Update to pull the latest approved version
4. Pinning — users stay on their installed version unless they manually update

This means:

• Breaking changes don't force upgrades
• Users choose when to update
• Old versions stay available for fallback

Archiving and deprecation

To retire a skill:

1. Open the skill
2. Go to Settings
3. Click Archive

An archived skill:

• Stops appearing in the registry
• Can't be newly installed
• Existing installs still work (but show a deprecation notice)
• Agents already using it can still run, but users are advised to switch to a replacement

Optionally, set a suggested replacement so users know what to switch to.

Sharing skills across organizations

If you want to share a skill with people outside your organization:

1. Export the skill as a file (.tar.gz or similar)
2. Share the file out-of-band
3. Other teams can import it via Skills → Import from File

Public sharing (to the entire AACWorkflow community) is not currently supported, but this private registry lets you share within your organization easily.

Security and governance

• Approval gates — all published skills must be approved before use
• Workspace scoping — skills are isolated per workspace; workspace-specific data doesn't leak
• Versioning — each version is immutable; changes require a new version and re-approval
• Audit trail — all publishes, approvals, and installs are logged

See Skill signing and review for additional governance and checksums.

Next steps

• Skill signing and review — approval gates and tampering detection
• Skills — learn how to create and use skills
• Squads — organize agents to use specific skills