Merge pull request #2901 from port-labs/PORT-update-ai-instructions-guide

Update Manage AI Instructions with Port

Author: hadar-co

docs/guides/all/manage-ai-instructions.md

@@ -180,24 +180,25 @@ Before setting up the automation, we need to create an AI agent that will handle
       "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"
+        "prompt": "You are an AI agent responsible for keeping the AGENTS.md file up to date in GitHub repositories. You do so by invoking the `run_claude_code` self-service action, which triggers Claude coding agent to work on the request.\n\nWhen you invoke the `run_claude_code` self-service action:\n1. Set `repo_name` to the target repository.\n2. Construct the `prompt` so it includes the full new AGENTS.md Markdown provided by Port, not just a placeholder reference. The prompt 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 `prompt` 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",
+        "tools": [
+          "^(list|get|search|track|describe)_.*",
+          "run_run_claude_code"
+        ]
       },
       "relations": {}
     }
     ```
     </details>
 
+    :::tip MCP Enhanced Capabilities
+    The AI agent uses MCP (Model Context Protocol) enhanced capabilities to automatically discover important and relevant blueprint entities via its tools. The `^(list|get|search|track|describe)_.*` pattern allows the agent to access and analyze related entities in your software catalog, providing richer context for AI instructions management. Additionally, we explicitly add `run_run_claude_code` to the tools, which instructs the AI agent to call this specific action to update AGENTS.md files in repositories.
+    :::
+
 5. Click `Create` to save the agent.
 
 </TabItem>
@@ -217,24 +218,25 @@ Before setting up the automation, we need to create an AI agent that will handle
       "identifier": "ai_instructions_manager",
       "title": "AI Instructions Manager",
       "icon": "Github",
-      "team": [],
       "properties": {
-        "description": "AI agent that manages coding rules and instructions via GitHub Copilot",
+        "description": "AI agent that manages the AGENTS.md file in repositories via Github Copilot",
         "status": "active",
-        "allowed_blueprints": [
-          "service"
-        ],
-        "allowed_actions": [
-          "create_github_issue"
-        ],
-        "prompt": "You are an AI agent responsible for keeping the AGENTS.md file up to date in GitHub repositories.\n\nWhen you invoke the `create_github_issue` action:\n1. Set the `title` to: 'Update AGENTS.md with latest AI instructions from Port'.\n2. Always include the following labels: ['ai-instructions', 'auto_assign'].\n3. Set the `body` to include **explicit task instructions** for GitHub Copilot, followed by the new Markdown content. Use this template:\n\n---\n## Task for Copilot\nUpdate the `AGENTS.md` file at the root of the repository. Replace its contents entirely with the Markdown provided below. Commit the change on a new branch and open a pull request with:\n- Title: 'chore: sync AGENTS.md from Port'\n- Description: 'This PR updates AGENTS.md based on the latest instructions from Port.'\n\n## New AGENTS.md Content\nMARKDOWN START\n<the full Markdown provided from Port>\nMARKDOWN END\n---\n\nDo not ask for clarification. Always assume the Markdown from Port is final. The issue body above is the full instruction for Copilot.",
-        "execution_mode": "Automatic"
+        "prompt": "You are an AI agent responsible for keeping the AGENTS.md file up to date in GitHub repositories. You do so by invoking the `create_github_issue` self-service action, which triggers GitHub Copilot to work on the request.\n\nWhen you invoke the `create_github_issue` self-service action:\n1. Set the `title` to: 'Update AGENTS.md with latest AI instructions from Port'.\n2. Always include the following labels: ['ai-instructions', 'auto_assign'].\n3. Set the `body` to include **explicit task instructions** for GitHub Copilot, followed by the new Markdown content. Use this template:\n\n---\n## Task for Copilot\nUpdate the `AGENTS.md` file at the root of the repository. Replace its contents entirely with the Markdown provided below. Commit the change on a new branch and open a pull request with:\n- Title: 'chore: sync AGENTS.md from Port'\n- Description: 'This PR updates AGENTS.md based on the latest instructions from Port.'\n\n## New AGENTS.md Content\nMARKDOWN START\n<the full Markdown provided from Port>\nMARKDOWN END\n---\n\nDo not ask for clarification. Always assume the Markdown from Port is final. The issue body above is the full instruction for Copilot.",
+        "execution_mode": "Automatic",
+        "tools": [
+          "^(list|get|search|track|describe)_.*",
+          "run_create_github_issue"
+        ]
       },
       "relations": {}
     }
     ```
     </details>
 
+    :::tip MCP Enhanced Capabilities
+    The AI agent uses MCP (Model Context Protocol) enhanced capabilities to automatically discover important and relevant blueprint entities via its tools. The `^(list|get|search|track|describe)_.*` pattern allows the agent to access and analyze related entities in your software catalog, providing richer context for AI instructions management. Additionally, we explicitly add `run_create_github_issue` to the tools, which instructs the AI agent to call this specific action to create GitHub issues for AGENTS.md updates.
+    :::
+
 5. Click `Create` to save the agent.
 
 </TabItem>
@@ -254,24 +256,25 @@ Before setting up the automation, we need to create an AI agent that will handle
       "identifier": "ai_instructions_manager",
       "title": "AI Instructions Manager",
       "icon": "Code",
-      "team": [],
       "properties": {
         "description": "AI agent that manages the AGENTS.md file in repositories via Google Gemini",
         "status": "active",
-        "allowed_blueprints": [
-          "service"
-        ],
-        "allowed_actions": [
-          "trigger_gemini_assistant"
-        ],
-        "prompt": "You are an AI agent responsible for keeping the AGENTS.md file up to date in GitHub repositories.\n\nWhen you invoke the `trigger_gemini_assistant` action:\n1. Set `repo_name` to the target repository.\n2. Construct the `prompt` so it includes the full new AGENTS.md Markdown provided by Port, not just a placeholder reference. The prompt must:\n   - Clearly instruct Gemini 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 `prompt` 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"
+        "prompt": "You are an AI agent responsible for keeping the AGENTS.md file up to date in GitHub repositories. You do so by invoking the `trigger_gemini_assistant` self-service action, which triggers Google Gemini to work on the request.\n\nWhen you invoke the `trigger_gemini_assistant` self-service action:\n1. Set `repo_name` to the target repository.\n2. Construct the `prompt` so it includes the full new AGENTS.md Markdown provided by Port, not just a placeholder reference. The prompt must:\n   - Clearly instruct Gemini 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 `prompt` 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",
+        "tools": [
+          "^(list|get|search|track|describe)_.*",
+          "run_trigger_gemini_assistant"
+        ]
       },
       "relations": {}
     }
     ```
     </details>
 
+    :::tip MCP Enhanced Capabilities
+    The AI agent uses MCP (Model Context Protocol) enhanced capabilities to automatically discover important and relevant blueprint entities via its tools. The `^(list|get|search|track|describe)_.*` pattern allows the agent to access and analyze related entities in your software catalog, providing richer context for AI instructions management. Additionally, we explicitly add `run_trigger_gemini_assistant` to the tools, which instructs the AI agent to call this specific action to trigger Gemini for AGENTS.md updates.
+    :::
+
 5. Click `Create` to save the agent.
 
 </TabItem>