mirror of
https://github.com/anomalyco/opencode.git
synced 2026-11-19 17:01:37 +03:00
docs(site): document { url, headers } instructions and skills
This commit is contained in:
@@ -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.
|
||||
|
||||
@@ -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:
|
||||
|
||||
Reference in New Issue
Block a user