Skills registry
A skills registry is a central library of reusable skills that platform teams publish and developers consume across the organization. Instead of each squad maintaining its own prompts and instructions, approved skills live in Port and sync to developer machines or load at runtime through Port AI.
This page covers the platform-team workflow: organizing skills, enforcing distribution, and keeping skills in sync with Git. For skill concepts and runtime loading, see the Skills overview and Enrich Port AI with skills.
What the registry solves
Engineering teams adopt AI agents at different layers of the stack. Without a registry, skills get duplicated, quality varies, and platform teams lose visibility into what instructions agents follow. For inventory of agents hosted on external platforms, see External agents.
The skills registry gives you:
- One source of truth for approved skills in your software catalog.
- Controlled distribution through skill groups with required or optional enforcement.
- Git-backed workflows so skills stay version-controlled and reviewable.
- CLI sync so developers receive required skills automatically on startup.
Registry components
| Component | Role |
|---|---|
| Skill blueprint | Defines how skill entities are stored in Port (instructions, references, assets). |
| Skill group blueprint | Groups skills and controls enforcement (required vs optional) and auto-sync behavior. |
| Port CLI | Syncs skills from Port to local developer tool directories. |
| GitOps ingestion | Pulls skills from GitHub repositories into the catalog on sync. |
For blueprint schemas and entity creation, see Creating custom skills in the Skills overview.
Publish skills with the Port CLI
The Port CLI is the recommended path for distributing skills at scale. Skills synced through the CLI live as local files, work without the MCP server running, and auto-sync on startup when marked as required.
After installing the CLI, initialize and sync:
port skills init
port skills sync
Run port skills init once to choose which tools receive skills and which skills to sync. Required skill groups sync automatically to developer machines on startup.
Skill groups
Skill groups organize skills into collections and control distribution. Each group has an enforcement level and an auto-sync flag:
- Required: skills sync automatically on developer machine startup.
- Optional: developers choose whether to sync.
Create the skill_group blueprint alongside the skill blueprint in your data model. See the skill group blueprint example in the Skills overview.
For supported tools, configuration options, and troubleshooting, see the CLI skills setup guide.
Ingest skills from GitHub
You can manage skills as folders in Git and ingest them into Port through a GitHub integration. Changes in GitHub appear in your catalog after the integration syncs.
For file structure, mapper configuration, and a full walkthrough, see the guide on ingesting prompts and skills from GitHub using GitOps.
You can also upload skills from a folder with a script for CI/CD pipelines.
Governance patterns
Platform teams typically:
- Sanction skills by publishing only approved skill entities and groups in Port.
- Mark baseline skills as required so every developer receives deployment guidelines, security review steps, or onboarding instructions.
- Let squads propose skills through Git PRs that flow into the catalog via GitOps.
- Override built-in skills by creating custom entities with the same name when your process differs from Port defaults.
Next steps
- Skills overview: blueprint setup, entity creation, and best practices.
- Enrich Port AI with skills: how Port AI loads skills at runtime.
- Build an AI agent: attach sanctioned skills to domain-specific agents.