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 to ingest SKILL.md instructions. Set includeSkillFolder: true to also bundle the text files in each skill folder into properties.references.
• Use the file kind when you also need binary files under assets/ on the skill entity as 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'
      # Optional: bundle the text files in each skill folder into references
      includeSkillFolder: 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
            references: .skill.files
            location: '"global"'

GitLab v2 mapping configuration (click to expand)

deleteDependentEntities: false
createMissingRelatedEntities: true
resources:
  - kind: skill
    selector:
      query: 'true'
      # Optional: bundle the text files in each skill folder into references
      includeSkillFolder: 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
            references: .skill.files
            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 and 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 connector. 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.

Related docs

• Skills overview - the skill blueprint, built-in skills and how agents load skills.
• Skills registry - build an org-wide registry on top of ingested skills.