Skip to main content

Check out Port for yourself 

Manage AI Instructions with Port

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

This guide demonstrates how to centralize these instructions inside your internal developer portal, and automatically sync them back into GitHub repositories whenever they are updated. This ensures consistency, visibility, and automation — without developers needing to manually edit AGENTS.md.

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

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

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

  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 integration mapping configuration (click to expand)
    deleteDependentEntities: false
    createMissingRelatedEntities: true
    enableMergeEntity: true
    resources:
      - kind: repository
        selector:
          query: true
        port:
          entity:
            mappings:
              identifier: .full_name
              title: .name
              blueprint: '"service"'
              properties:
                readme: file://README.md
                ai_instructions: file://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.

Configure AI agent​

Before setting up the automation, we need to create an AI agent that will handle the actual file updates in GitHub repositories. Choose the configuration that matches your preferred AI coding agent:

  1. Go to the AI agents page of your portal.

  2. Click on + AI Agent.

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

  4. Copy and paste the following JSON configuration:

    AI Instructions Manager Claude agent configuration (click to expand)
    {
      "identifier": "ai_instructions_manager",
      "title": "AI Instructions Manager",
      "icon": "Details",
      "team": [],
      "properties": {
        "description": "AI agent that manages the AGENTS.md file in repositories via Claude Code",
        "status": "active",
        "allowed_blueprints": [
          "service"
        ],
        "allowed_actions": [
          "run_claude_code"
        ],
        "prompt": "You are an AI agent responsible for keeping the AGENTS.md file up to date in GitHub repositories.\n\nWhen you invoke the `run_claude_code` action:\n1. Set `repo_name` to the target repository.\n2. Construct the `command` so it includes the full new AGENTS.md Markdown provided by Port, not just a placeholder reference. The command must:\n   - Clearly instruct Claude to replace the contents of `AGENTS.md` at the root of the repository.\n   - Include the full Markdown text from Port inside a fenced code block.\n   - End with instructions to commit on a new branch and open a PR with:\n     - Title: 'chore: sync AGENTS.md from Port'\n     - Description: 'This PR updates AGENTS.md based on the latest instructions from Port.'\n\nExample `command` format:\n\n```\nPlease update the repository by creating or replacing the AGENTS.md file at the root with the following content:\n\n```markdown\n<the full Markdown instructions provided by Port go here>\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.'\n```\n\nAlways embed the actual Markdown content directly. Never leave it as a placeholder or a reference.",
        "execution_mode": "Automatic"
      },
      "relations": {}
    }

  5. Click Create to save the agent.

Agent customization

You can customize the agent's behavior by:

  • Modifying the prompt to include additional instructions
  • Adding more allowed blueprints or actions
  • Adjusting the execution mode based on your security requirements
  • Including team assignments for better governance

Set up automation​

When ai_instructions changes in Port, you want those updates to be reflected in GitHub. For this, configure an automation that triggers whenever the property changes, and forwards the updated Markdown to the AI agent that manages AGENTS.md.

  1. Go to the Automations page of your portal.

  2. Click on + Automation.

  3. Copy and paste the following JSON configuration:

    Update AI Instructions automation (click to expand)
    {
      "identifier": "update_ai_instructions",
      "title": "Update AI Instructions",
      "description": "Automation to trigger the AI agent when the AI instructions changes",
      "icon": "AI",
      "trigger": {
        "type": "automation",
        "event": {
          "type": "ENTITY_UPDATED",
          "blueprintIdentifier": "service"
        },
        "condition": {
          "type": "JQ",
          "expressions": [
            ".diff.before.properties.ai_instructions != .diff.after.properties.ai_instructions"
          ],
          "combinator": "and"
        }
      },
      "invocationMethod": {
        "type": "WEBHOOK",
        "url": "https://api.getport.io/v1/agent/ai_instructions_manager/invoke",
        "agent": false,
        "synchronized": true,
        "method": "POST",
        "headers": {
          "RUN_ID": "{{ .run.id }}",
          "Content-Type": "application/json"
        },
        "body": {
          "prompt": "Update the repository '{{ .event.context.entityIdentifier }}'.\n\nCreate or replace the file `AGENTS.md` at the root with the following exact content\nMARKDOWN START:\n\n{{ .event.diff.after.properties.ai_instructions }}\n\nMARKDOWN END.\nCommit this change on a new branch and open a pull request.",
          "labels": {
            "source": "AI Instructions Manager",
            "entityIdentifier": "{{ .event.context.entityIdentifier }}"
          }
        }
      },
      "publish": true
    }

  4. Click Create to save the automation.

Test the workflow​

Now let us test the complete workflow to ensure everything works correctly.

Update AI instructions in Port​

  1. Go to your software catalog page.
  2. Find a repository entity that has AI instructions defined and edit it's content.

Verify GitHub pull request​

  1. Check your GitHub repository for a new pull request.
  2. Review the changes to ensure the AGENTS.md file was updated correctly.
  3. Merge the pull request to complete the sync.