From f12bef2f77afc4fb513ac9f7375580e2152d61d3 Mon Sep 17 00:00:00 2001
From: Dotta <bippadotta@protonmail.com>
Date: Mon, 2 Mar 2026 16:09:03 -0600
Subject: [PATCH] docs: document agent instructions path API in skill
 references

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 skills/paperclip/SKILL.md                    | 27 ++++++++++++++++
 skills/paperclip/references/api-reference.md | 34 ++++++++++++++++++++
 2 files changed, 61 insertions(+)

diff --git a/skills/paperclip/SKILL.md b/skills/paperclip/SKILL.md
index de0bed25..11d09541 100644
--- a/skills/paperclip/SKILL.md
+++ b/skills/paperclip/SKILL.md
@@ -153,6 +153,32 @@ pls show the costs in either token or dollars on the /issues/{id} page. Make a p
 
 \*make sure to have a newline after/before your <plan/> tags
 
+## Setting Agent Instructions Path
+
+Use the dedicated route instead of generic `PATCH /api/agents/:id` when you need to set an agent's instructions markdown path (for example `AGENTS.md`).
+
+```bash
+PATCH /api/agents/{agentId}/instructions-path
+{
+  "path": "agents/cmo/AGENTS.md"
+}
+```
+
+Rules:
+- Allowed for: the target agent itself, or an ancestor manager in that agent's reporting chain.
+- For `codex_local` and `claude_local`, default config key is `instructionsFilePath`.
+- Relative paths are resolved against the target agent's `adapterConfig.cwd`; absolute paths are accepted as-is.
+- To clear the path, send `{ "path": null }`.
+- For adapters with a different key, provide it explicitly:
+
+```bash
+PATCH /api/agents/{agentId}/instructions-path
+{
+  "path": "/absolute/path/to/AGENTS.md",
+  "adapterConfigKey": "yourAdapterSpecificPathField"
+}
+```
+
 ## Key Endpoints (Quick Reference)
 
 | Action               | Endpoint                                                                                   |
@@ -167,6 +193,7 @@ pls show the costs in either token or dollars on the /issues/{id} page. Make a p
 | Create subtask       | `POST /api/companies/:companyId/issues`                                                    |
 | Create project       | `POST /api/companies/:companyId/projects`                                                  |
 | Create project workspace | `POST /api/projects/:projectId/workspaces`                                             |
+| Set instructions path | `PATCH /api/agents/:agentId/instructions-path`                                            |
 | Release task         | `POST /api/issues/:issueId/release`                                                        |
 | List agents          | `GET /api/companies/:companyId/agents`                                                     |
 | Dashboard            | `GET /api/companies/:companyId/dashboard`                                                  |
diff --git a/skills/paperclip/references/api-reference.md b/skills/paperclip/references/api-reference.md
index 08d0fc63..b7ea4444 100644
--- a/skills/paperclip/references/api-reference.md
+++ b/skills/paperclip/references/api-reference.md
@@ -280,6 +280,39 @@ Use the dashboard for situational awareness, especially if you're a manager or C
 
 ---
 
+## Setting Agent Instructions Path
+
+Use the dedicated endpoint when setting an adapter instructions markdown path (`AGENTS.md`-style files):
+
+```
+PATCH /api/agents/{agentId}/instructions-path
+{
+  "path": "agents/cmo/AGENTS.md"
+}
+```
+
+Authorization:
+- target agent itself, or
+- an ancestor manager in the target agent's reporting chain.
+
+Adapter behavior:
+- `codex_local` and `claude_local` default to `adapterConfig.instructionsFilePath`
+- relative paths resolve against `adapterConfig.cwd`
+- absolute paths are stored as-is
+- clear by sending `{ "path": null }`
+
+For adapters with a non-default key:
+
+```
+PATCH /api/agents/{agentId}/instructions-path
+{
+  "path": "/absolute/path/to/AGENTS.md",
+  "adapterConfigKey": "adapterSpecificPathField"
+}
+```
+
+---
+
 ## Project Setup (Create + Workspace)
 
 When a CEO/manager task asks you to "set up a new project" and wire local + GitHub context, use this sequence.
@@ -431,6 +464,7 @@ Terminal states: `done`, `cancelled`
 | GET    | `/api/agents/:agentId`             | Agent details + chain of command     |
 | GET    | `/api/companies/:companyId/agents` | List all agents in company           |
 | GET    | `/api/companies/:companyId/org`    | Org chart tree                       |
+| PATCH  | `/api/agents/:agentId/instructions-path` | Set/clear instructions path (`AGENTS.md`) |
 | GET    | `/api/agents/:agentId/config-revisions` | List config revisions            |
 | POST   | `/api/agents/:agentId/config-revisions/:revisionId/rollback` | Roll back config |