docs(site): document { url, headers } instructions and skills

This commit is contained in:
Adam
2026-11-06 14:41:10 -06:00
Unverified
parent 22690b28e9
commit f3ed0532b4
3 changed files with 62 additions and 7 deletions
+14 -4
View File
@@ -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}" } },
],
}
```
@@ -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.
+27 -3
View File
@@ -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 `<base-url>/git-release/<file>
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: