Ingest prompts and skills from GitHub using GitOps

Teams that manage AI prompts and skills as code need a reliable way to sync those assets into Port. This guide shows you how to structure prompt and skill files in your GitHub repositories and map them to Port blueprints using the GitHub app integration. This gives you a GitOps workflow where GitHub is the source of truth and Port stays in sync automatically.

Common use cases

Keep AI prompts and skills version-controlled with clear audit trails.
Avoid manual entity creation and drift across systems.

Prerequisites

This guide assumes the following:

You have a Port account and have completed the onboarding process.
Port's GitHub integration is installed in your account.

Set up data model

Let's create two blueprints to manage AI prompts and skills.

Create the prompt blueprint

Go to the builder page of your portal.
Click on + Blueprint.
Click on the {...} button in the top right corner, and choose Edit JSON.

Paste the following JSON schema:

Prompt blueprint schema (click to expand)

{
  "identifier": "prompt",
  "title": "Prompt",
  "icon": "Microservice",
  "schema": {
    "properties": {
      "description": {
        "type": "string",
        "title": "Description"
      },
      "arguments": {
        "items": {
          "type": "object",
          "properties": {
            "name": {
              "type": "string",
              "description": "The name of the argument parameter"
            },
            "description": {
              "type": "string",
              "description": "A description of what this argument is for"
            },
            "required": {
              "type": "boolean",
              "description": "Whether this argument is required or optional",
              "default": false
            }
          },
          "required": [
            "name",
            "description"
          ]
        },
        "type": "array",
        "title": "Arguments"
      },
      "template": {
        "icon": "DefaultProperty",
        "type": "string",
        "title": "Prompt Template",
        "format": "markdown"
      }
    },
    "required": [
      "description",
      "template"
    ]
  },
  "mirrorProperties": {},
  "calculationProperties": {},
  "aggregationProperties": {},
  "relations": {}
}

Click Save to create the blueprint.

Create the skill blueprint

Go to the builder page of your portal.
Click on + Blueprint.
Click on the {...} button in the top right corner, and choose Edit JSON.

Paste the following JSON schema:

Skill blueprint schema (click to expand)

{
  "identifier": "skill",
  "title": "Skill",
  "icon": "Learn",
  "schema": {
    "properties": {
      "description": {
        "title": "Description",
        "type": "string",
        "description": "What the skill does and when the model should use it"
      },
      "instructions": {
        "title": "Instructions",
        "type": "string",
        "format": "markdown",
        "description": "Step-by-step instructions for the AI to follow"
      },
      "references": {
        "title": "References",
        "type": "array",
        "description": "Reference documents for the skill",
        "items": {
          "type": "object",
          "properties": {
            "path": {
              "type": "string",
              "description": "Resource path (e.g., references/common-errors.md)"
            },
            "content": {
              "type": "string",
              "description": "The file content"
            }
          },
          "required": [
            "path",
            "content"
          ],
          "additionalProperties": false
        }
      },
      "assets": {
        "title": "Assets",
        "type": "array",
        "description": "Asset files (templates, configs) for the skill",
        "items": {
          "type": "object",
          "properties": {
            "path": {
              "type": "string",
              "description": "Asset path (e.g., assets/mapping-template.yaml)"
            },
            "content": {
              "type": "string",
              "description": "The file content"
            }
          },
          "required": [
            "path",
            "content"
          ],
          "additionalProperties": false
        }
      },
      "content": {
        "type": "object",
        "title": "content"
      }
    },
    "required": [
      "description",
      "instructions"
    ]
  },
  "mirrorProperties": {},
  "calculationProperties": {},
  "aggregationProperties": {},
  "relations": {}
}

Click Save to create the blueprint.

Recommended file structure

You can map GitHub files and folders to Port entities. The structure below keeps prompts and skills consistent and predictable.

Prompt files

Store prompts as YAML files under .github/prompts using the .prompt.yaml suffix. This is consistent with GitHub's prompt storage standard.

Example file: .github/prompts/code-review.prompt.yaml.

Example prompt file (click to expand)

name: code-review
description: Review code changes for correctness, security, performance, and test coverage following repo conventions.
arguments:
  - name: change_scope
    description: Summary of the changes or files to review.
    required: false
  - name: focus_areas
    description: Specific concerns to prioritize (e.g., security, performance).
    required: false
message: |-
  # Code review

  Review code changes for this repository.

  Inputs:
  - change_scope: {{change_scope}}
  - focus_areas: {{focus_areas}}

  ## Instructions

  Focus on:
  - correctness and edge cases.
  - security risks and input validation.
  - performance regressions.
  - missing tests or insufficient coverage.
  - adherence to repo conventions in `AGENTS.md`.

  Output format:
  1. Findings (ordered by severity).
  2. Questions and assumptions.
  3. Suggested fixes.

  ## Examples
  - Review changes in {{change_scope}} with focus on {{focus_areas}}.
  - If {{change_scope}} is empty, review the full diff and infer key risks.

  ## Guidelines
  - Be specific and cite affected areas.
  - Prioritize actionable feedback.

Skill folders

Store each Anthropics skill in its own folder under skills/. Each folder should include a SKILL.md file with YAML frontmatter and instructions. You can add supporting files under references/ and assets/ as needed.

Example file: skills/my-skill/SKILL.md.

Example skill file (click to expand)

---
name: my-skill-name
description: A clear description of what this skill does and when to use it
---

# My skill name

Add your instructions here that the AI should follow when this skill is active.

## Examples
- Example usage 1.
- Example usage 2.

## Guidelines
- Guideline 1.
- Guideline 2.

File content validation

Make sure your prompt and skill files contain only the fields you intend to expose in Port, and avoid including secrets or credentials in any file content that will be ingested.

Update integration mapping

Now you will configure the GitHub integration to ingest prompts and skills from your repositories.

Go to the data sources page of your portal.
Find your GitHub integration and click on it.
Go to the Mapping tab.

Update the mapping configuration:

GitHub integration mapping configuration (click to expand)

deleteDependentEntities: false
createMissingRelatedEntities: true
enableMergeEntity: true
resources:
  - kind: repository
    selector:
      query: 'true'
      teams: true
    port:
      entity:
        mappings:
          identifier: .full_name
          title: .name
          blueprint: '"githubRepo"'
          properties:
            readme: file://README.md
            url: .html_url
            defaultBranch: .default_branch
          relations:
            githubTeams: '[.teams[].id | tostring]'

  - kind: folder
    selector:
      query: 'true'
      folders:
        - path: '**/skills/*'
    port:
      entity:
        mappings:
          identifier: .repo.name + "-" + .folder.name
          title: .repo.name + "-" + .folder.name
          blueprint: '"skill"'
          properties:
            instructions: file://SKILL.md
            description: .folder.name

  - kind: file
    selector:
      query: 'true'
      files:
        - path: .github/prompts/*.prompt.yaml
          skipParsing: false
    port:
      entity:
        mappings:
          identifier: .repo.name + "/" + .file.name
          title: .file.name | split(".") | .[0]
          blueprint: '"prompt"'
          properties:
            description: .file.content.description
            arguments: .file.content.arguments
            template: .file.content.message

Click Save to update the integration configuration.

Test the configuration

Now you can validate the full workflow and confirm that changes in GitHub appear in the Port catalog.

Update a .prompt.yaml or SKILL.md file in your repository and merge the change.
Go to your software catalog page.
Find the corresponding Prompt or Skill entity and confirm the content is updated.

Common use cases​

Prerequisites​

Set up data model​

Create the prompt blueprint​

Create the skill blueprint​

Recommended file structure​

Prompt files​

Skill folders​

Update integration mapping​

Test the configuration​

Related guides​