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. To measure which skills teams actually use, see Skills usage analytics.

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.
Native skill kind	Discovers SKILL.md files from GitHub Ocean or GitLab v2 and maps them into the catalog.
GitOps ingestion (folder kind)	Alternative folder-based sync for custom layouts (kind: folder + includedFiles).

For blueprint schemas and entity creation, see Creating custom skills in the Skills overview.

Ingest skills from Git

You can manage skills as SKILL.md files in Git and ingest them into Port through the GitHub Ocean or GitLab v2 integrations.

Recommended: native skill kind

Prefer the dedicated skill kind. It discovers common Agent Skill layouts (for example .cursor/skills/**/SKILL.md and skills/**/SKILL.md), parses frontmatter and instructions, and emits one entity per skill.

GitHub Ocean mapping configuration (click to expand)

deleteDependentEntities: false
createMissingRelatedEntities: true
enableMergeEntity: true
resources:
  - kind: skill
    selector:
      query: 'true'
      paths:
        - path: 'skills/**/SKILL.md'
          organization: my-org
          repos:
            - name: my-repo
              branch: main
        - path: '.cursor/skills/**/SKILL.md'
          organization: my-org
    port:
      entity:
        mappings:
          identifier: .__repository.full_name + "/" + .skill.skillMdPath
          title: .skill.name // .skill.skillMdPath
          blueprint: '"skill"'
          properties:
            instructions: .skill.instructions
            description: .skill.description
            location: '"global"'

GitLab v2 mapping configuration (click to expand)

deleteDependentEntities: false
createMissingRelatedEntities: true
resources:
  - kind: skill
    selector:
      query: 'true'
      paths:
        - path: 'skills/**/SKILL.md'
          repos:
            - group/my-repo
        - path: '.cursor/skills/**/SKILL.md'
    port:
      entity:
        mappings:
          identifier: .repo.path_with_namespace + "/" + .skill.skillMdPath
          title: .skill.name // .skill.skillMdPath
          blueprint: '"skill"'
          properties:
            instructions: .skill.instructions
            description: .skill.description
            location: '"global"'

On GitLab, skill discovery always uses the repository tree API (glob-friendly, not Advanced Search). On GitHub, discovery uses recursive git-tree matching with the same path-selector shape as the file kind - large orgs pay a tree walk per scanned repository.

See also:

• GitHub Ocean - ingest agent skills
• GitLab v2 - ingest agent skills

Alternative: folder kind + included files

You can still manage skills as folders in Git and ingest them with kind: folder when you need a custom folder layout:

GitHub Ocean folder-based mapping (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 repositories will automatically sync to Port. Changes in Git 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.
• Skills usage analytics: measure skill adoption from Cursor and Claude.
• Build an AI agent: attach sanctioned skills to domain-specific agents.