From f3ed0532b43d7432f1bdfe715ae57fa64546e067 Mon Sep 17 00:00:00 2001 From: Adam <2363879+adamdotdevin@users.noreply.github.com> Date: Fri, 6 Nov 2026 14:41:10 -0600 Subject: [PATCH] docs(site): document { url, headers } instructions and skills --- services/site/src/docs/content/config.mdx | 18 ++++++++--- .../site/src/docs/content/instructions.mdx | 21 +++++++++++++ services/site/src/docs/content/skills.mdx | 30 +++++++++++++++++-- 3 files changed, 62 insertions(+), 7 deletions(-) diff --git a/services/site/src/docs/content/config.mdx b/services/site/src/docs/content/config.mdx index 8aded5ef72b..61cbe26338f 100644 --- a/services/site/src/docs/content/config.mdx +++ b/services/site/src/docs/content/config.mdx @@ -414,11 +414,16 @@ and cost considerations. ### Skills -Add directories or URLs that OpenCode should search for agent skills. +Add directories or URLs that OpenCode should search for agent skills. Write a +URL as `{ "url", "headers" }` to send headers with its requests. ```jsonc { - "skills": ["./team-skills", "https://example.com/.well-known/skills/"], + "skills": [ + "./team-skills", + "https://example.com/.well-known/skills/", + { "url": "https://skills.example.com/team/", "headers": { "Authorization": "Bearer {env:TEAM_SKILLS_TOKEN}" } }, + ], } ``` @@ -444,11 +449,16 @@ See the [commands guide](/commands) for arguments, models, agents, and file-base ### Instructions Declare additional instruction files, globs, or HTTP(S) URLs. OpenCode loads -them alongside discovered `AGENTS.md` files. +them alongside discovered `AGENTS.md` files. Write a URL as `{ "url", "headers" }` +to send headers with its request. ```jsonc { - "instructions": ["CONTRIBUTING.md", "docs/guidelines/*.md"], + "instructions": [ + "CONTRIBUTING.md", + "docs/guidelines/*.md", + { "url": "https://docs.example.com/team.md", "headers": { "Authorization": "Bearer {env:TEAM_DOCS_TOKEN}" } }, + ], } ``` diff --git a/services/site/src/docs/content/instructions.mdx b/services/site/src/docs/content/instructions.mdx index 80e62b6122e..1199b58781f 100644 --- a/services/site/src/docs/content/instructions.mdx +++ b/services/site/src/docs/content/instructions.mdx @@ -122,11 +122,32 @@ Configured instructions load after `AGENTS.md` files, in the order they are list | `~/` path | Resolved from your home directory | | Absolute path | Used as written; the file name may be a glob | | `http://` or `https://` | Fetched when config loads, with a five-second timeout | +| `{ "url", "headers" }` | Fetched like a URL, sending the headers with the request | - Local files update like `AGENTS.md` when they change. New files matching a glob load on the next config change. - Missing files are skipped. A URL that cannot be fetched is skipped, or keeps its last fetched content. - With `OPENCODE_DISABLE_PROJECT_CONFIG=1`, or when the workspace is outside the project, relative entries resolve against the global config directory. +### Private URLs + +Write an entry as an object to send headers with the request, for example to read instructions that need a token: + +```jsonc title="opencode.jsonc" +{ + "instructions": [ + { + "url": "https://docs.example.com/team/instructions.md", + "headers": { "Authorization": "Bearer {env:TEAM_DOCS_TOKEN}" }, + }, + ], +} +``` + +- `url` must start with `http://` or `https://`. Other entries in object form are skipped with a warning. +- The headers go to the URL and to redirects on the same origin. A redirect to another origin receives none of them. +- The instruction is labeled with its URL only. Header values never reach the model or OpenCode's logs. +- When several config files list the same URL, it is fetched once, with the headers from the highest-precedence file. + A connected [OpenCode Console](/console) workspace can also share instructions. See [Config](/config) for configuration locations and precedence. diff --git a/services/site/src/docs/content/skills.mdx b/services/site/src/docs/content/skills.mdx index 7936cb432a3..50e68fb66a1 100644 --- a/services/site/src/docs/content/skills.mdx +++ b/services/site/src/docs/content/skills.mdx @@ -86,6 +86,7 @@ Add more local directories or HTTP catalogs with the `skills` array in any `open | `~/` path | From the current user's home directory | | Absolute path | Used as written | | `http://` or `https://` URL | Loaded as an HTTP catalog | +| `{ "url", "headers" }` | Loaded as an HTTP catalog, sending the headers with every request | Every discovered config file contributes its entries. `skills` arrays are combined rather than replaced. @@ -117,6 +118,26 @@ For that entry, OpenCode downloads each file from `/git-release/ Each downloaded skill directory becomes a source root named after the entry, so both `git-release.md` and `SKILL.md` have the ID `git-release`. +### Private catalogs + +Write the entry as an object to send headers with `index.json` and every file download: + +```jsonc title="opencode.jsonc" +{ + "skills": [ + { + "url": "https://skills.example.com/team/", + "headers": { "Authorization": "Bearer {env:TEAM_SKILLS_TOKEN}" }, + }, + ], +} +``` + +- `url` must start with `http://` or `https://`. Other entries in object form are skipped with a warning. +- The headers go to the catalog and to redirects on the same origin. A redirect to another origin receives none of them. +- Downloads are cached by URL, so changing the headers does not download unchanged skills again. +- When several config files list the same URL, the headers from the highest-precedence file are used. + ## Frontmatter Use frontmatter to name the skill and control where it appears: @@ -175,9 +196,10 @@ Sources are registered from lower to higher precedence: 1. Built-in skills 2. `.claude/skills`, global first and then from the farthest ancestor toward the current directory 3. `.agents/skills`, global first and then from the farthest ancestor toward the current directory -4. `~/.config/opencode/skills` -5. Project `.opencode/skills`, from the project root toward the current directory -6. Explicit `skills` config entries, in config priority and array order +4. Skills from a connected integration, such as an [OpenCode Console](/console) workspace +5. `~/.config/opencode/skills` +6. Project `.opencode/skills`, from the project root toward the current directory +7. Explicit `skills` config entries, in config priority and array order Avoid duplicate IDs unless you intend to override an earlier skill. @@ -204,6 +226,8 @@ To load a skill yourself, mention it in your prompt as `@skill-id`. Supporting file contents are not loaded automatically. The agent reads them when the skill directs it to do so. The file sample is available for directory-based `SKILL.md` skills; flat Markdown skills do not receive a neighboring file list. +Reading a file in a `SKILL.md` skill's directory needs the `skill` permission for that skill and the `read` permission for the file. This holds when the directory is outside the project, such as a catalog skill in OpenCode's download cache, so no `external_directory` approval is asked. Editing those files still needs it. + ## Permissions Use the `skill` action and the skill ID as the resource. Rules run in order, and the last matching rule wins: