> 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

Open in ClaudeOpen in CodexOpen in Cursor
Open plan mode. Implement this Port guide in my org via MCP:

https://docs.port.io/guides/all/manage-ai-instructions

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. Diff the guide's data model (blueprints, properties, relations, actions, agents, automations, integrations, secrets) against mine.
3. Propose adaptations for gaps, reusing existing blueprints/relations over guide-named duplicates.
4. Flag what needs a UI click, credential, or secret from me, testing MCP capability empirically before ruling anything out.
5. 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.
- 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, 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:
- Confirm the guide's expected output exists and runs in Port.
- Summarize adaptations, seeded data, what was mocked or skipped, remaining UI steps, and how to verify.

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.

Sync AI instructions workflow

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

Sync AI instructions workflow diagram

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 of your portal.

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 of your portal.
  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 PR syncing AGENTS.md from Port