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 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.
• Git-backed workflows so skills stay version-controlled and reviewable.

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

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.

Store each skill in its own folder under skills/ with a SKILL.md file per folder. Then configure your GitHub integration to sync them:

GitHub Ocean mapping configuration (click to expand)

deleteDependentEntities: false
createMissingRelatedEntities: true
enableMergeEntity: true
resources:
  - kind: folder
    selector:
      query: 'true'
      folders:
        - path: '**/skills/*'
          organization: my-org  # Optional if githubOrganization is set (required if not set)
          repos:
            - name: my-repo
              branch: main
      includedFiles:
        - SKILL.md
    port:
      entity:
        mappings:
          identifier: .__repository.name + "-" + (.folder.path | split("/") | last)
          title: .__repository.name + "-" + (.folder.path | split("/") | last)
          blueprint: '"skill"'
          properties:
            instructions: .__includedFiles["SKILL.md"]
            description: .folder.path | split("/") | last
            location: '"global"'

Using GitHub (Sunset) or also syncing prompts

If your account still uses Port's older GitHub app integration, or you also want to sync prompt files alongside skills, see the Ingest prompts and skills from GitHub using GitOps guide, which covers both integration versions and the combined prompts and skills setup.

After configuration, skills from your GitHub repositories will automatically sync to Port. Changes in GitHub will appear in your Port catalog after the integration syncs.

Common practices

• Keep deleteDependentEntities: false on this data source. Setting it to true means a temporary sync issue, like a rate limit, a revoked permission, or a renamed repo, deletes skill entities on the next resync instead of leaving them stale.
• Use a consistent folder naming convention in skills/ so skill identifiers are predictable across repositories.

You can also upload skills from a folder with a script for CI/CD pipelines.

Governance patterns

Platform teams typically:

1. Sanction skills by publishing only approved skill entities and groups in Port.
2. Mark baseline skills as required so every developer receives deployment guidelines, security review steps, or onboarding instructions.
3. Let squads propose skills through Git PRs that flow into the catalog via GitOps.
4. 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.