Ingest prompts and skills from GitHub using GitOps

Implement with AI

Send this guide to your coding agent.

Prerequisite: Install Port MCP

Open in ClaudeOpen in CodexOpen in Cursor

Open plan mode if your tool supports it; otherwise present the plan below filled in and wait for my approval. Implement this Port guide in my org via MCP:

https://docs.port.io/guides/all/ingest-prompts-skills-from-github-using-gitops

Read the raw markdown version at https://docs.port.io/guides/all/ingest-prompts-skills-from-github-using-gitops.md - it contains every tab and code block without page markup.

Goal: get the guide's core flow working end-to-end in my org; adapting it to fit my existing setup takes priority over matching the guide 1:1.

Plan:
1. Confirm MCP is connected, in the right org, with sufficient permissions.
2. If the guide offers alternative implementation paths (tabs), pick the one matching my installed integrations and tools, confirm it with me, and implement only that path.
3. Diff the guide's data model (blueprints, properties, relations, workflows, actions, agents, automations, integrations, webhook data sources, secrets) against mine.
4. Propose adaptations for gaps, reusing existing blueprints/relations over guide-named duplicates.
5. Flag what needs a UI click, credential, or secret from me, testing MCP capability empirically before ruling anything out. If the guide has a "Set up via API" section, use it for anything MCP can't do before treating a step as UI-only.
6. Stop on any blocker and give me options. Approving this plan authorizes the writes it lists; pause only for writes beyond what's listed.

Build:
- Extend blueprint schema additively when upserting; don't remove or overwrite existing properties, and treat type conflicts as a blocker, not an auto-fix.
- Never print secret values into the chat or logs; ask me to set them in Port, or write them via the secrets API without echoing them back.
- List any mock data in the plan, minimal and labeled mock; once approved, seed it without re-asking, and tell me what you seeded.
- For anything the guide writes downstream (e.g. a webhook target), use a real entity, not a mock.
- For pages/widgets, use the real page identifier from the app URL, not a guessed slug.
- When you hit a UI step confirmed (not assumed) unsupported via MCP and not covered by the guide's API sections, pause, give exact clicks, then resume via MCP.
- Validate and give links after each meaningful step (only a tool-returned URL, no guessed paths); don't proceed if the last run wasn't a success.

Done:
- Run the guide's "Let's test it" steps where possible (e.g. execute a workflow test run) and confirm the expected output exists in Port.
- Summarize adaptations, seeded data, what was mocked or skipped, remaining UI steps, and how to verify.

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.

• GitHub Ocean 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

Follow the steps in the Set up the data model section of the prompts documentation to create the prompt blueprint.

Create the skill blueprint

Follow the steps in the Step 1: Create the skill blueprint section of the skills documentation to create the skill 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.

1. Go to the data sources page in Port.

2. Find your GitHub integration and click on it.

3. Go to the Mapping tab.

4. Update the mapping configuration:

   GitHub Ocean mapping configuration (click to expand)

   deleteDependentEntities: false
   createMissingRelatedEntities: true
   enableMergeEntity: true
   resources:
     - kind: repository
       selector:
         query: 'true'
         teams: true
         includedFiles:
           - README.md
       port:
         entity:
           mappings:
             identifier: .name
             title: .name
             blueprint: '"githubRepo"'
             properties:
               readme: .__includedFiles["README.md"]
               url: .html_url
               defaultBranch: .default_branch
             relations:
               githubTeams: '[.teams[].id | tostring]'
   
     - 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
   
     - kind: file
       selector:
         query: 'true'
         files:
           - path: .github/prompts/*.prompt.yaml
             skipParsing: false
             organization: my-org  # Optional if githubOrganization is set (required if not set)
             repos:
               - name: my-repo
                 branch: main
       port:
         entity:
           mappings:
             identifier: .__repository.name + "/" + .name
             title: .name | split(".") | .[0]
             blueprint: '"prompt"'
             properties:
               description: .content.description
               arguments: .content.arguments
               template: .content.message
             relations:
               repository: .__repository

Ocean differences

GitHub (Ocean) uses files with organization and repos structure to scope which repositories are scanned. Use .content instead of .file.content for file content. For folders, use includedFiles and .__includedFiles["filename"] instead of the file:// prefix. Use .__repository or .repository for the repository relation.

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

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

Related guides

• Centralize AI coding rules with Port.
• Manage AI instructions with Port.