release 1.0.0: cost control, 41 tools, 29 skills, custom commands, auto-load

2026-09-07 19:59:58 +07:00
parent a22d8e13b1
commit ffa9a02c26
97 changed files with 4791 additions and 788 deletions
@@ -0,0 +1,101 @@
+# Extensions: auto-loaded skills, tools, and plugins
+
+External extensions load automatically from two directories on every start, the project
+shadowing the user by name:
+
+| Origin | Directories |
+|---|---|
+| user | `~/.shiro-neko/skills` `~/.shiro-neko/tools` `~/.shiro-neko/plugins` |
+| project | `.shiro/skills` `.shiro/tools` `.shiro/plugins` |
+
+Drop a file in and it is live on the next start. No registry, no install command, no restart
+of anything but the CLI itself.
+
+**Everything here is data, never code.** That is the same rule the [registry](registry.md)
+enforces, and it is the whole security model. An external extension can add instructions, a
+bounded tool, or a refusal rule — it cannot run arbitrary code, so it cannot read every file
+the agent can read or lie about what it blocks. A malformed file is reported on the welcome
+dashboard and skipped, never fatal.
+
+## Skills
+
+A skill is a Markdown file with frontmatter, exactly like a bundled one:
+
+```markdown
+---
+name: deploy
+description: Ship a release. Use when asked to deploy or cut a release.
+---
+
+# Deploy
+
+1. Confirm the tests pass. Do not deploy on a red suite.
+2. Tag with the version from src/version.ts, not by hand.
+```
+
+Skills merge by name with the precedence `builtin < registry < user < project`, so your own
+`debug.md` overrides the bundled `debug`. See [skills](skills.md) for the full format.
+
+## Tools
+
+A tool is a JSON manifest describing one bounded operation. Three kinds, each with a ceiling
+on what it can do:
+
+```json
+{
+  "name": "recent-changes",
+  "description": "List the ten most recently changed files",
+  "kind": "shell",
+  "command": "git diff --name-only HEAD~10",
+  "autoApprove": true
+}
+```
+
+| Field | Meaning |
+|---|---|
+| `name` | The tool name the model calls. Letters, digits, dashes, underscores. |
+| `description` | What the model reads to decide when to use it. |
+| `kind` | `shell`, `http`, or `read`. |
+| `command` | For `shell`: the template to run, with an optional `{arg}` placeholder. |
+| `url` | For `http`: the URL to fetch, with an optional `{arg}` placeholder. HTTPS only. |
+| `path` | For `read`: the workspace file to return, with an optional `{arg}` placeholder. |
+| `autoApprove` | `false` to require approval before running. Default `true`. |
+
+The model passes a single optional `arg` string, substituted into `{arg}`.
+
+**The limits are the point.** A `shell` tool runs a fixed template through the **guard** and
+the platform shell — the same chain a built-in `bash` call goes through, so an installed tool
+cannot do what the agent itself may not. An `http` tool fetches one HTTPS URL. A `read` tool
+returns one workspace file, jailed to the workspace. None of them executes code from the
+manifest.
+
+## Plugins
+
+A plugin is a refusal manifest — the same shape the registry installs — a name, an optional
+prompt appendix, and deny rules matched against tool input:
+
+```json
+{
+  "name": "no-prod-config",
+  "description": "refuses to edit production config",
+  "appendix": "Production config is changed by hand, never by the agent.",
+  "deny": [
+    { "tools": ["write_file", "edit_file"], "pathPattern": "config/production", "reason": "production config is hand-edited" },
+    { "tools": ["bash"], "commandPattern": "kubectl\\s+apply", "reason": "deploys to the cluster" }
+  ]
+}
+```
+
+A rule names the tools it covers and either a `pathPattern` (matched against the path a file
+tool carries) or a `commandPattern` (matched against a `bash` command), both as case-insensitive
+regexes, plus the `reason` handed to the model when it blocks. Patterns are validated on load;
+an invalid regex is a reported error, not a crash.
+
+Refusal plugins compose with the built-in [plugins](plugins.md) — the first block wins.
+
+## Relationship to the registry
+
+The [registry](registry.md) fetches the same kinds of files over HTTPS with a confirmation
+step. Auto-load is for your own and your project's files, which need no confirmation because
+you wrote them. The two mechanisms share the loaders and the safety model; they differ only in
+where the file comes from.