Skip to content

The agent that grows with you

docs(plugins): name locate_skill's real second parameter; decode SKILL.md like skill_view

Tekniumbb834a2cb329
diff --git a/website/docs/developer-guide/plugins/index.md b/website/docs/developer-guide/plugins/index.md
index 41e4cd28878..9e3e78dfd91 100644
--- a/website/docs/developer-guide/plugins/index.md
+++ b/website/docs/developer-guide/plugins/index.md
@@ -1050,7 +1050,7 @@ contract:
| `tools.skills_tool.sort_skills(skills)` | The one listing order (category, then name). |
| `tools.skills_tool.skill_search_dirs()` | `(roots, active_dir)`: `(tier, dir)` roots in precedence order (project, local, `create_dir`, external) and the live profile's skills dir. |
| `tools.skills_tool.skill_lookup_path_error(name)` | An error string if `name` is absolute or contains `..`, else `None`. Check it before any lookup. |
-| `tools.skills_tool.locate_skill(name, category, roots)` | `(error_json, skill_dir, skill_md)` for one name over `roots`: tier precedence, same-tier collision refusal and the project-skill quarantine gate. `skill_md` is set only when `error_json` is `None`. |
+| `tools.skills_tool.locate_skill(name, local_category_name, roots)` | `(error_json, skill_dir, skill_md)` for one name over `roots`: tier precedence, same-tier collision refusal and the project-skill quarantine gate. `local_category_name` is an extra relative path to try (it is not a category filter), so pass `None` unless you need one. `skill_md` is set only when `error_json` is `None`. |
| `tools.skills_sync.dir_hash(directory)` | The package hash the bundled-skill sync stores, so you can tell whether a user's copy still matches what was installed. |
| `tools.skill_usage.read_skill_name(skill_md, fallback)` | The frontmatter `name:` of a `SKILL.md`, else `fallback`. |
@@ -1065,7 +1065,7 @@ def open_skill(name):
return err
roots, _active = skill_search_dirs()
error, _skill_dir, skill_md = locate_skill(name, None, roots)
- return error or skill_md.read_text(encoding="utf-8")
+ return error or skill_md.read_text(encoding="utf-8-sig", errors="replace")
```
Plugin-registered skills (`ctx.register_skill`) are not on disk under these roots; `find_all_skills()`