Skills registry

A skills registry is a central library of reusable skills that everyone across the organization can publish and consume. Instead of each squad maintaining its own prompts and instructions, approved skills live in one catalog in Port, discovered and installed through the UI, Port MCP, or a CLI command.

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.

The skills registry gives you:

• A catalog of every skill in your org - discoverable through the UI, Port MCP, or a CLI install.
• A golden path for sharing skills - one standard way to propose, review, and publish a new skill across the org, instead of ad hoc pull requests.
• Composable skills - group related skills into installable plugins as your registry grows.
• Quality and governance bars - certification review, duplicate detection, and an ROI scorecard catch skills that shouldn't be in the registry, whether they're low-quality, redundant, or not worth their cost.
• Visibility into usage and cost - real usage and spend data connected to the registry, so you can see which skills are actually adopted, and which are worth what they cost to run.

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.

Choose the skill or file kind

Choose one mapping kind. Do not combine them:

• Use the skill kind when you only need SKILL.md instructions in Port. It does not ingest files under references/ or assets/.
• Use the file kind when those extra files must land on the skill entity as properties.references and properties.assets.

Do not model extra files as related entities, and do not reconstruct references with mirror or calculation properties.

Skill kind

The skill kind 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

File kind

The file kind is the original GitOps pattern for skills. Map SKILL.md into instructions, and map files under references/ and assets/ into the matching array properties on the same skill identifier. Set enableMergeEntity: true so extra files merge onto the skill instead of replacing the instructions.

GitHub Ocean file kind mapping (click to expand)

deleteDependentEntities: false
createMissingRelatedEntities: true
enableMergeEntity: true
resources:
  - kind: file
    selector:
      query: 'true'
      files:
        - path: skills/**/SKILL.md
          organization: my-org
          repos:
            - name: my-repo
              branch: main
    port:
      entity:
        mappings:
          identifier: .repository.name + "/" + (.path | split("/")[1])
          title: .path | split("/")[1]
          blueprint: '"skill"'
          properties:
            instructions: .content
            description: .content | capture("description:\\s*(?<d>.+)").d
            location: '"global"'
          relations: {}
  - kind: file
    selector:
      query: 'true'
      files:
        - path: skills/**/references/**
          skipParsing: true
          organization: my-org
          repos:
            - name: my-repo
              branch: main
    port:
      entity:
        mappings:
          identifier: .repository.name + "/" + (.path | split("/")[1])
          blueprint: '"skill"'
          properties:
            references:
              - path: .path | split("/") | .[2:] | join("/")
                content: .content
  - kind: file
    selector:
      query: 'true'
      files:
        - path: skills/**/assets/**
          skipParsing: true
          organization: my-org
          repos:
            - name: my-repo
              branch: main
    port:
      entity:
        mappings:
          identifier: .repository.name + "/" + (.path | split("/")[1])
          blueprint: '"skill"'
          properties:
            assets:
              - path: .path | split("/") | .[2:] | join("/")
                content: .content

Each extra-file event replaces the whole references or assets array. If a skill has more than one file in the same directory, use the upload skills from a folder script so the full array is written in one request.

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. Folder kind with includedFiles: [SKILL.md] maps instructions only. If you also need references/ or assets/, use the file kind instead of adding extra mappings on top of folder kind.

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.

Build a skills registry with our guides

Follow these guides in order to go from a bare Git repository to a fully governed skills registry:

1. Set up a skills registry - model every skill in your org as a Port entity, assign it to groups, and let developers discover them.
2. Ship new skills through one golden path - give developers one standard way to propose a skill and track the review from a single dashboard.
3. Certify skills to meet industry and org standards - add an AI-driven review on top of the deterministic scorecards.
4. Avoid duplicate skills in your org registry - catch a duplicate skill pre-publish or during certification.
5. Bundle skills into plugins - group related skills into installable plugins, with an AI-driven suggestion and a self-service workflow to apply it.
6. Measure the ROI of skills in your org registry - connect real Claude usage and spend data to the registry.
7. Visualize Claude Skills adoption and usage - build a dashboard tracking adoption, sharing, and spend.

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.
• External agents: inventory of agents hosted on external platforms.