a dotfile but it's really big
0
fork

Configure Feed

Select the types of activity you want to include in your feed.

skill: don't point agents towards simlinks

karitham 358f70c0 0c17c7e6

+34 -30
+34 -30
modules/opencode/skills/skill-builder/SKILL.md
··· 20 20 - File MUST be named exactly `SKILL.md` (case-sensitive) 21 21 - Folder MUST use kebab-case: lowercase, hyphens only, no spaces/capitals/underscores 22 22 - MUST NOT include a README.md inside skill folders, because SKILL.md is the single entrypoint and a README creates ambiguity about which file is authoritative 23 - - Skills live at `~/.config/opencode/skills/<name>/` (global) or `.opencode/skills/<name>/` (project-local) 24 23 25 24 ## 2. Frontmatter Reference 26 25 27 26 ```yaml 28 27 --- 29 - name: my-skill # required 30 - description: ... # required 31 - license: MIT # optional 32 - compatibility: ... # optional 33 - metadata: # optional 28 + name: my-skill # required 29 + description: ... # required 30 + license: MIT # optional 31 + compatibility: ... # optional 32 + metadata: # optional 34 33 author: jane 35 34 version: "1.0" 36 - allowed-tools: Bash Read # optional, space-delimited 35 + allowed-tools: Bash Read # optional, space-delimited 37 36 --- 38 37 ``` 39 38 40 - | Field | Constraints | 41 - |---|---| 42 - | `name` | 1-64 chars. Lowercase alphanumeric + hyphens. No leading/trailing/consecutive hyphens. MUST match folder name. | 43 - | `description` | 1-1024 chars. No XML angle brackets. See §3. | 44 - | `license` | Short license identifier (e.g., MIT, Apache-2.0). | 45 - | `compatibility` | 1-500 chars. Environment requirements (OS, runtime, tools). | 46 - | `metadata` | Key-value string map. | 47 - | `allowed-tools` | Space-delimited tool names pre-approved for this skill. | 39 + | Field | Constraints | 40 + | --------------- | -------------------------------------------------------------------------------------------------------------- | 41 + | `name` | 1-64 chars. Lowercase alphanumeric + hyphens. No leading/trailing/consecutive hyphens. MUST match folder name. | 42 + | `description` | 1-1024 chars. No XML angle brackets. See §3. | 43 + | `license` | Short license identifier (e.g., MIT, Apache-2.0). | 44 + | `compatibility` | 1-500 chars. Environment requirements (OS, runtime, tools). | 45 + | `metadata` | Key-value string map. | 46 + | `allowed-tools` | Space-delimited tool names pre-approved for this skill. | 48 47 49 48 Security constraints: 49 + 50 50 - MUST NOT use XML angle brackets (`<` `>`) in any frontmatter value, because frontmatter is injected into XML-structured system prompts and unescaped brackets break parsing 51 51 - `name` MUST NOT contain "claude" or "anthropic" (reserved) 52 52 ··· 107 107 108 108 Skills load in three levels to minimize context cost: 109 109 110 - | Level | What loads | When | Budget | 111 - |---|---|---|---| 112 - | 1. Frontmatter | `name` + `description` | Always (system prompt) | ~100 tokens per skill | 113 - | 2. SKILL.md body | Core instructions | Agent triggers the skill | Keep under 500 lines | 114 - | 3. Linked files | references/, scripts/, assets/ | Agent reads explicitly | No cost until accessed | 110 + | Level | What loads | When | Budget | 111 + | ---------------- | ------------------------------ | ------------------------ | ---------------------- | 112 + | 1. Frontmatter | `name` + `description` | Always (system prompt) | ~100 tokens per skill | 113 + | 2. SKILL.md body | Core instructions | Agent triggers the skill | Keep under 500 lines | 114 + | 3. Linked files | references/, scripts/, assets/ | Agent reads explicitly | No cost until accessed | 115 115 116 116 Practical guidance: 117 117 ··· 148 148 149 149 ```markdown 150 150 ## Summary 151 + 151 152 [required — 1-2 sentences] 152 153 153 154 ## Details 155 + 154 156 [optional — supporting context] 155 157 ``` 156 158 ··· 197 199 198 200 ### Location 199 201 200 - - Global: `~/.config/opencode/agents/<name>.md` 202 + - Global: `~/dotfiles/modules/opencode/agents/<name>.md` 201 203 - Project: `.opencode/agents/<name>.md` 202 204 203 205 ### Frontmatter ··· 219 221 --- 220 222 ``` 221 223 222 - | Field | Required | Notes | 223 - |---|---|---| 224 - | `description` | Yes | Same rules as skill descriptions (§3). | 225 - | `mode` | No | `primary` (top-level) or `subagent` (delegated to). | 226 - | `permission` | No | Tool permission overrides. Pattern-matched, most specific wins. | 224 + | Field | Required | Notes | 225 + | ------------- | -------- | --------------------------------------------------------------- | 226 + | `description` | Yes | Same rules as skill descriptions (§3). | 227 + | `mode` | No | `primary` (top-level) or `subagent` (delegated to). | 228 + | `permission` | No | Tool permission overrides. Pattern-matched, most specific wins. | 227 229 228 230 ### Content 229 231 ··· 233 235 You are the **Code Reviewer**. You review pull requests for correctness and style. 234 236 235 237 ## Protocol 238 + 236 239 1. Read the diff 237 240 2. Check against project conventions 238 241 3. Report issues with file:line references 239 242 240 243 ## Constraints 244 + 241 245 - MUST NOT suggest style changes that contradict existing patterns 242 246 - MUST NOT approve without reading every changed file 243 247 ``` ··· 258 262 259 263 ### Iteration 260 264 261 - | Problem | Fix | 262 - |---|---| 265 + | Problem | Fix | 266 + | ---------------- | ---------------------------------------------------- | 263 267 | Under-triggering | Add more keywords and trigger phrases to description | 264 - | Over-triggering | Be more specific, add negative triggers | 265 - | Wrong output | Add examples, tighten constraints | 268 + | Over-triggering | Be more specific, add negative triggers | 269 + | Wrong output | Add examples, tighten constraints | 266 270 267 271 Debug with: _"When would you use the [skill name] skill?"_ 268 272