> For the complete documentation index, see llms.txt.
Skip to main content

Check out Port for yourself ➜ 

Manage AI instructions with Port

Implement with AI

Send this guide to your coding agent.

Prerequisite: Install Port MCP

In the age of AI coding agents (Claude, Copilot, Gemini, Cursor), teams need a single source of truth for how autonomous agents should contribute to repositories. Traditionally, these rules are stored manually in different locations based on the coding agent's specification such as .cursor/rules, .github/copilot-instructions, or other agent-specific folders. However, managing these scattered files at scale is cumbersome and leads to inconsistency.

To deal with this challenge, you can adopt the AGENTS.md structure as a unified standard for all AI coding instructions, regardless of the specific agent being used, and automate it with a Port workflow.

This guide demonstrates how to centralize AI instructions in Port and automatically sync them back into GitHub repositories whenever the ai_instructions property changes. When an update is detected, the workflow dispatches your chosen coding agent backend to open a pull request that updates AGENTS.md.

Port repository instruction update triggers a coding agent backend that opens an AGENTS.md pull request in GitHub

Common use cases​

  • Centralize AI guidelines by managing all AI agent instructions from a single location in Port.
  • Ensure consistency across repositories by automatically syncing updated instructions via pull requests.
  • Reduce manual overhead by eliminating the need for developers to manually update AGENTS.md files.

Prerequisites​

This guide assumes the following:

Set up data model​

We will enhance the GitHub repository blueprint to include AI instructions and configure the GitHub integration to sync these instructions automatically.

Update the repository blueprint​

To track AI instructions, we need to add a property for managing AI agent contribution guidelines.

  1. Go to the Data model page in Port.

  2. Find and select your existing repository blueprint (e.g., githubRepository or service).

  3. Click on {...} Edit JSON.

  4. Add the following property to the properties section:

    AI instructions property (click to expand)
    "ai_instructions": {
      "title": "AI Instructions",
      "description": "Rules and contribution guidelines for AI coding agents",
      "type": "string",
      "format": "markdown"
    }

  5. Click Save to update the blueprint.

Update GitHub integration mapping​

Now we need to configure the GitHub integration to automatically sync the AI instructions between Port and GitHub 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 to include the AI instructions property:

    GitHub Ocean integration mapping configuration (click to expand)
    deleteDependentEntities: false
    createMissingRelatedEntities: true
    enableMergeEntity: true
    resources:
      - kind: repository
        selector:
          query: true
          includedFiles:
            - README.md
            - AGENTS.md
        port:
          entity:
            mappings:
              identifier: .full_name
              title: .name
              blueprint: '"githubRepository"'
              properties:
                readme: .__includedFiles["README.md"]
                ai_instructions: .__includedFiles["AGENTS.md"]
                url: .html_url
                defaultBranch: .default_branch

  5. Click Save to update the integration configuration.

File path considerations

The integration will look for the AGENTS.md file at the root of each repository. Ensure your repositories follow this standardized file structure for consistent mapping across your organization.

Centralizing AI instructions​

The AGENTS.md pattern involves creating a centralized AGENTS.md file at the root of your repository that serves as the single source of truth for all AI coding instructions. To make your AI coding agents reference this standardized file, you need to configure them to point to it:

Create a .cursor/rules file in your repository with the following configuration:

---
description: General Guidelines
globs:
alwaysApply: true
---

@AGENTS.md

This configuration tells Cursor to always apply the guidelines from the AGENTS.md file to all files in your repository.

Build the workflow​

When ai_instructions changes in Port, the workflow forwards the updated Markdown to your coding agent backend so it can update AGENTS.md in the target repository.

Port workflow sends updated ai_instructions Markdown to the selected coding agent backend for repository synchronization

Choose the workflow JSON that matches your coding agent:

This workflow dispatches claude-backend.yaml using a GitHub integration action. With GitHub Ocean, you do not need to add a GitHub token to Port secrets for the dispatch itself. The integration handles workflow dispatch authentication.

Build the workflow

  1. Go to the Workflows page of your portal.

  2. Click on the + Workflow button in the top-right corner.

  3. In the Name field, enter Sync AI instructions, then click Confirm.

  4. On the editor page, click the see workflow JSON button (the code icon) to open the JSON editor.

  5. Copy and paste the workflow JSON below to replace the example workflow:

    Sync AI instructions workflow JSON for Claude Code (click to expand)
    {
      "identifier": "sync_ai_instructions",
      "title": "Sync AI instructions",
      "icon": "AI",
      "description": "When AI instructions change on a service, dispatch Claude Code to update AGENTS.md",
      "allowAnyoneToViewRuns": true,
      "nodes": [
        {
          "identifier": "trigger",
          "title": "On AI instructions updated",
          "icon": "DefaultProperty",
          "description": "Trigger when the ai_instructions property changes on a service entity",
          "config": {
            "type": "EVENT_TRIGGER",
            "event": {
              "type": "ENTITY_UPDATED",
              "blueprintIdentifier": "githubRepository"
            },
            "condition": {
              "type": "JQ",
              "expressions": [
                ".diff.before.properties.ai_instructions != .diff.after.properties.ai_instructions"
              ],
              "combinator": "and"
            }
          },
          "variables": {}
        },
        {
          "identifier": "run_claude_code",
          "title": "Update AGENTS.md with Claude Code",
          "icon": "Code",
          "description": "Dispatch the Claude Code backend workflow in the target repository",
          "config": {
            "type": "INTEGRATION_ACTION",
            "installationId": "<YOUR_GITHUB_OCEAN_INTEGRATION_ID>",
            "integrationProvider": "github-ocean",
            "integrationInvocationType": "dispatch_workflow",
            "integrationActionExecutionProperties": {
              "org": "<YOUR_GITHUB_ORG>",
              "repo": "<YOUR_WORKFLOW_REPO>",
              "workflow": "claude-backend.yaml",
              "workflowInputs": {
                "repo_name": "{{ .outputs.trigger.diff.after.relations.organization }}/{{ .outputs.trigger.diff.after.identifier }}",
                "command": "Please update the repository by creating or replacing the AGENTS.md file at the root with the following content:\n\n```markdown\n{{ .outputs.trigger.diff.after.properties.ai_instructions }}\n```\n\nCommit this change on a new branch and open a pull request titled: 'chore: sync AGENTS.md from Port' with description: 'This PR updates AGENTS.md based on the latest instructions from Port.'"
              },
              "reportWorkflowStatus": true
            }
          },
          "variables": {}
        }
      ],
      "connections": [
        {
          "sourceIdentifier": "trigger",
          "targetIdentifier": "run_claude_code"
        }
      ]
    }

  6. Click Save to save the workflow.

Replace placeholders

Replace YOUR_GITHUB_OCEAN_INTEGRATION_ID, YOUR_GITHUB_ORG, and YOUR_WORKFLOW_REPO with your GitHub Ocean integration ID, organization name, and the repository where claude-backend.yaml lives. You can find the integration ID on the Data sources page in Port.

Test the workflow​

Now let's test the complete flow to ensure everything works correctly.

Update AI instructions in Port​

  1. Go to your context lake page.
  2. Find a repository entity that has AI instructions defined and edit its content.
  3. Save the entity to trigger the workflow.

Verify the workflow run​

  1. Go to the Workflows page in Port.
  2. Open the latest run of Sync AI instructions and confirm the trigger and dispatch nodes completed successfully.

Verify GitHub pull request​

  1. Check your GitHub repository for a new pull request or Copilot-assigned issue.
  2. Review the changes to ensure the AGENTS.md file was updated correctly.
  3. Merge the pull request to complete the sync.
GitHub pull request showing the AGENTS.md update generated from Port repository instructions