@restregular/dsh-skill-center 0.2.1 → 0.3.0

package/README.md

@@ -39,8 +39,65 @@ Sidebar                                   Main area
 | Create | Creates `<name>/SKILL.md` under the user Agents or user DSH skills root |
 | Delete | Moves the skill to `.trash/<timestamp>-<name>` in the same root — recoverable, never a hard delete |
 | Read-only guard | Skills embedded in plugins (e.g. `office-docx`) are labelled *embedded* and their switches/deletion are disabled |
+| Bundled skill | Ships an embedded **`skill-authoring`** skill (guidance + `references/` + a starter template) that teaches the agent which root a skill belongs in, what the frontmatter contract is, and where a skill's resource files go |
+| Model tool | Registers **`skill_create`**, which writes `<root>/<name>/SKILL.md` plus any resource files in one call — the path that works for skill roots outside the session workspace, where the file-write tools are sandboxed |
 | Security | Every write is confined to managed skill roots that really exist on disk; requests from non-loopback origins get `403` |
 
+## Bundled skill and model tool
+
+Beyond the panel, the host half publishes its own guidance for agents and one tool that acts on it.
+
+### `skill-authoring` (embedded skill)
+
+The package ships `skills/skill-authoring/` and registers it with `ctx.skills.registerProvider()`,
+so it appears in the session catalog exactly like the built-in skills — the model can load it with
+the `skill` tool, and the panel lists it as *embedded* (read-only, because the file belongs to the
+package, not to a managed root).
+
+```
+skills/skill-authoring/
+  SKILL.md                        routing + the five-step short path
+  references/roots.md             the root table, ranks, precedence, project-root detection
+  references/frontmatter.md       every field, the boolean spellings, why a skill silently does not load
+  references/resources.md         where resource files go and how the model is told to find them
+  references/plugin-bundled.md    shipping skill content inside a plugin package
+  templates/minimal/SKILL.md      starter bundle
+```
+
+Because the candidate carries `resourceBase: { kind: 'directory', path }`, the loaded skill arrives
+with `Base directory for this skill: <abs path>` in its `<skill_resources>` block, so the agent can
+read `references/*.md` with ordinary file tools. Rank 600 means any project or user skill named
+`skill-authoring` shadows this one — override it by writing your own.
+
+### `skill_create` (model tool)
+
+```
+skill_create({ name, description, whenToUse?, body?, root?, resources?, modelInvocable?, userInvocable?, overwrite? })
+```
+
+| Argument | Meaning |
+|---|---|
+| `name` | kebab-case skill name; also the bundle directory name |
+| `description` | frontmatter description — the only routing signal the catalog shows |
+| `whenToUse` | optional `whenToUse` frontmatter field |
+| `body` | the Markdown after the frontmatter; defaults to a `# <name>` heading |
+| `root` | `project-dsh` \| `project-agents` \| `user-dsh` \| `user-agents`; defaults to `user-agents` |
+| `resources` | `[{ path, content }]` written inside the same bundle directory (e.g. `references/roots.md`) |
+| `modelInvocable` / `userInvocable` | `false` writes `disable-model-invocation: true` / `user-invocable: false` |
+| `overwrite` | required to replace an existing skill; the default fails instead of clobbering |
+
+It exists because of a real obstacle: the file-write tools are sandboxed to the session workspace,
+while `$DSH_HOME/skills` and `$DSH_AGENTS_HOME/skills` are not in it, so an agent asked to "make me
+a skill" could only fail there. The tool writes with the same confinement as the panel — only the
+four managed roots, only inside `<root>/<name>/` — and rejects absolute resource paths, `..`
+segments, a resource that would overwrite `SKILL.md`, and a name that collides with an embedded
+skill. It registers through `ctx.inject(['tools'], …)`, so a composition without `ctx.tools` simply
+loses the tool instead of failing to mount.
+
+> [!NOTE]
+> The tool is registered globally, so **every agent on the host sees `skill_create`** (one extra
+> tool schema in the prompt). Removing the plugin removes it; there is no switch.
+
 ## Requirements
 
 - **DeepSeek Harness** desktop build that provides the `ctx.skills` registry and the loopback web server.
@@ -67,7 +124,7 @@ Then add the package to the profile's bundle list and restart:
 // <profile>/package.json
 {
   "dsh": { "profile": { "bundles": [/* … */ "@restregular/dsh-skill-center"] } },
-  "dependencies": { "@restregular/dsh-skill-center": "^0.2.1" }
+  "dependencies": { "@restregular/dsh-skill-center": "^0.3.0" }
 }
 ```
 
@@ -83,8 +140,25 @@ because the client registers `sidebar.panellist` with `order: 1`.
 > no sidebar row, `/plugins/@restregular/dsh-skill-center/client.js` returns `404`, and nothing is
 > logged. 0.2.1 fixed exactly this; 0.2.0 shipped the bare name.
 
+> [!IMPORTANT]
+> The client bundle must also call `__ModuleLoader__.load({ id: '@restregular/dsh-skill-center' })` —
+> **the package name, not the plugin id**. The browser module graph numbers rows by package name, and
+> `ClientModuleSystem.invalidate(id, rev)` (what the HMR `rebuilt` frame and `entries.reload` use)
+> deletes factory entries **by row id only**. A registration id that differs from the row id leaves
+> the stale factory in place, so the next bundle revision throws
+> `client-modules: duplicate factory registration … (bundle executed twice without invalidate?)`
+> and the whole web boot reports `1 entry did not activate`. 0.2.2 fixed this; 0.2.0/0.2.1 used the
+> bare plugin id. The bundle additionally skips registration when that id is already present, so a
+> double execution can no longer take the boot down.
+
 To uninstall: remove the bundle entry and the dependency, then restart.
 
+> [!WARNING]
+> Do not leave a bare-name junction/link for this package in the profile's `node_modules`
+> (e.g. `node_modules\dsh-skill-center` → the repo). Both the link and the scoped package register
+> the same plugin, which is exactly the two-sources situation behind the duplicate-registration
+> crash. Install the scoped package and nothing else.
+
 ## Troubleshooting
 
 Nothing appears in the sidebar after install + restart? Check in this order:
@@ -121,7 +195,7 @@ The host half mounts a **loopback-only** route at `/dsh-skill-center/api`:
 | GET | `list` | `sessionId?` `cwd?` | skill catalog + read metadata |
 | POST | `read` | `name` | raw `SKILL.md` text |
 | POST | `setInvocation` | `name` `modelInvocable?` `userInvocable?` | rewrite invocation policy |
-| POST | `create` | `name` `description` `body?` `rootId?` | create a skill bundle |
+| POST | `create` | `name` `description` `body?` `rootId?` `whenToUse?` `resources?` `overwrite?` `modelInvocable?` `userInvocable?` | create (or, with `overwrite`, replace) a skill bundle and its resource files; shares one implementation with `skill_create` |
 | POST | `delete` | `name` | move to `.trash` |
 
 Requests from anything other than `127.0.0.1` / `::1` are rejected with `403`.
@@ -158,6 +232,12 @@ Two halves, no shared imports:
 - Frontmatter edits are string-level: only the invocation keys are touched, everything else is preserved
   byte for byte, including line-ending style.
 - Delete is a `rename` into `.trash`.
+- Also registers an embedded skill provider (`ctx.skills.registerProvider`) for `skills/skill-authoring/`
+  and the `skill_create` tool (`ctx.inject(['tools'], …)` + `ctx.tools.register`). The tool schema is a
+  hand-written JSON Schema using only the subset `@deepseek-ai/dsh-tools` accepts, so the package keeps
+  zero runtime dependencies and needs no host-side module resolution.
+- The three parts degrade independently: a missing `tools` or `webServer` service, or a bundled-skill
+  asset that fails to parse, only logs a warning and leaves the rest mounted.
 
 **Browser half** — [`client/client.js`](client/client.js)
 
@@ -199,7 +279,8 @@ New-Item -ItemType Junction -Path "$env:USERPROFILE\.dsh\profiles\desktop\node_m
   -Target "D:\path\to\dsh-skill-center"
 ```
 
-Self-checks (both run against the local host route with a mini React shim):
+Self-checks (the first two run against the local host route with a mini React shim; the third is
+fully offline):
 
 ```powershell
 $env:ELECTRON_RUN_AS_NODE = 1
@@ -207,8 +288,18 @@ $exe  = "C:\path\to\DeepSeek Harness.exe"
 $here = "D:\path\to\dsh-skill-center"
 $env:DSH_SMOKE_SESSION = "<session-id>"; & $exe "$here\client-smoke.mjs"   # client half + real loopback route
 & $exe "$here\verify-compose.mjs"                                          # client half accepted by the module graph
+node "$here\verify-skill.mjs"                                              # bundled skill + skill_create, offline
 ```
 
+`verify-compose.mjs` must run through the Electron binary: it reads the shipped `@deepseek-ai`
+packages out of `app.asar`, which plain `node` cannot open. `verify-skill.mjs` is the opposite — it
+imports `lib/index.js` with a stub context and needs no host at all. It checks the bundled skill's
+contract (directory name vs frontmatter, non-empty description, `resourceBase` directory, every
+`references/`-style path cited in a table or link actually existing), the tool's JSON Schema against
+the subset `@deepseek-ai/dsh-tools` accepts, and then **really runs** `skill_create` inside a temp
+dir: create, resource placement, overwrite, duplicate names, illegal names, path traversal, flat
+files, explicit project roots, and the three degraded mount paths.
+
 > Renaming or relocating the package: the client module table caches package metadata by
 > `(loader baseUrl, loader line name)` — no file timestamps — so a running host keeps the old path.
 > The browser side uses the in-memory snapshot taken at activation and keeps working after a reload;
@@ -224,6 +315,11 @@ $env:DSH_SMOKE_SESSION = "<session-id>"; & $exe "$here\client-smoke.mjs"   # cli
   embedded skills plus that cwd's project skills; the footer shows the effective cwd and scope tier.
 - Catalog replacement is all-or-nothing: one switch change makes the host resend the whole skill
   catalog message (a Harness design choice, not this plugin's).
+- `skill_create` is registered host-wide, so every agent sees one more tool schema; it has no
+  per-agent switch, and only uninstalling the plugin removes it.
+- The bundled `skill-authoring` skill is embedded and therefore read-only in the panel. Because it
+  sits at rank 600, a project or user skill with the same name replaces it entirely — that is the
+  intended way to customize it.
 
 ## License
 
@@ -251,8 +347,57 @@ $env:DSH_SMOKE_SESSION = "<session-id>"; & $exe "$here\client-smoke.mjs"   # cli
 | 新建 | 在「用户 Agents 技能」或「用户 DSH 技能」根下创建 `<name>/SKILL.md` |
 | 删除 | 移动到同根目录的 `.trash/<时间戳>-<名字>`（可手工恢复，不硬删） |
 | 只读保护 | 插件内嵌技能（如 `office-docx`、`diagnose-windows-sandbox-acl`）标注「内嵌」，开关与删除按钮禁用 |
+| 随包技能 | 附带一个内嵌的 **`skill-authoring`** 指导技能（正文 + `references/` + 起步模板）：技能该放哪个根、frontmatter 契约是什么、资源文件放哪、怎么把技能打进插件包 |
+| 模型工具 | 注册 **`skill_create`**：一次调用写出 `<root>/<name>/SKILL.md` 与全部资源文件 —— 技能根在工作区之外时（文件写入工具被沙箱挡住）这是唯一走得通的路径 |
 | 安全 | 写操作只落在**真实存在于磁盘**的受管技能根内；非回环来源一律 `403` |
 
+### 随包技能与模型工具
+
+除了面板，宿主半边还会给 Agent 发一份指导技能和一个真正能动手的工具。
+
+**`skill-authoring`（内嵌技能）**：包内 `skills/skill-authoring/` 通过
+`ctx.skills.registerProvider()` 注册，和第一方内嵌技能一样出现在会话技能目录里 ——
+模型可以用 `skill` 工具加载它，面板把它标成「内嵌」（只读，因为它属于包，不属于受管根）。
+
+```
+skills/skill-authoring/
+  SKILL.md                        路由 + 五步短路径
+  references/roots.md             根表、rank、优先级、项目根判定
+  references/frontmatter.md       每个字段、布尔写法、为什么技能会静默不加载
+  references/resources.md         资源文件放哪、模型怎么被告知去找
+  references/plugin-bundled.md    把技能打进插件包的两种注册方式
+  templates/minimal/SKILL.md      起步模板
+```
+
+候选带上 `resourceBase: { kind: 'directory', path }` 之后，加载出来的
+`<skill_resources>` 里会写明 `Base directory for this skill: <绝对路径>`，
+Agent 因此能用普通文件工具去读 `references/*.md`。rank 600 意味着任何项目级/用户级同名技能都能盖过它 ——
+想改写它就自己建一个同名技能。
+
+**`skill_create`（模型工具）**：
+
+| 参数 | 含义 |
+|---|---|
+| `name` | kebab-case 技能名，同时是目录名 |
+| `description` | frontmatter 的 description：目录里唯一的路由信号 |
+| `whenToUse` | 可选，写进 frontmatter |
+| `body` | frontmatter 之后的 Markdown 正文；省略则写一个 `# <name>` 标题 |
+| `root` | `project-dsh` / `project-agents` / `user-dsh` / `user-agents`，默认 `user-agents` |
+| `resources` | `[{ path, content }]`，写进同一个技能目录（如 `references/roots.md`） |
+| `modelInvocable` / `userInvocable` | 传 `false` 分别写 `disable-model-invocation: true` / `user-invocable: false` |
+| `overwrite` | 覆盖已存在的技能必须显式传，默认宁可失败也不覆盖 |
+
+它存在的理由很具体：文件写入工具被沙箱限制在会话工作区内，而 `$DSH_HOME/skills`、
+`$DSH_AGENTS_HOME/skills` 不在工作区里 —— 用户说「给我做个技能」时，Agent 在那里根本写不进去。
+这个工具用的是和面板同一套落盘实现：只写四个受管根、只写 `<root>/<name>/` 之内，
+并拒绝绝对资源路径、`..` 段、会覆盖 `SKILL.md` 的资源，以及与内嵌技能重名。
+它通过 `ctx.inject(['tools'], …)` 注册，所以没有 `ctx.tools` 的组合只是少这个工具，不会挂不上。
+
+> [!NOTE]
+> 工具是**宿主级全局注册**：同一宿主上每个 Agent 都会多看到 `skill_create`（多一份工具 schema）。
+> 没有开关，卸载插件才会消失。
+
+
 ### 安装
 
 **市场安装**：侧栏「插件」→ 搜索 `@restregular/dsh-skill-center` → 安装 → 重启宿主。
@@ -269,7 +414,7 @@ pnpm add @restregular/dsh-skill-center
 // <profile>/package.json
 {
   "dsh": { "profile": { "bundles": [/* … */ "@restregular/dsh-skill-center"] } },
-  "dependencies": { "@restregular/dsh-skill-center": "^0.2.1" }
+  "dependencies": { "@restregular/dsh-skill-center": "^0.3.0" }
 }
 ```
 
@@ -283,8 +428,24 @@ pnpm add @restregular/dsh-skill-center
 > 但浏览器半边会被**静默丢弃** —— 侧栏没有「技能中心」、`/plugins/@restregular/dsh-skill-center/client.js`
 > 返回 `404`，而且日志里一个字都没有。0.2.1 修的就是这个；0.2.0 发出去的是裸名。
 
+> [!IMPORTANT]
+> 客户端 bundle 还必须用**包名**注册：`__ModuleLoader__.load({ id: '@restregular/dsh-skill-center' })`，
+> 不能用插件 id `dsh-skill-center`。浏览器模块图是按包名给行编号的，而
+> `ClientModuleSystem.invalidate(id, rev)`（HMR 的 `rebuilt` 帧 → `entries.reload` 走的正是它）
+> **只按行 id** 删工厂表里的条目：注册 id 与行 id 不一致 → 旧工厂删不掉 → 下一版 bundle 一执行就
+> `client-modules: duplicate factory registration … (bundle executed twice without invalidate?)`，
+> 整条 web boot 变成「1 entry did not activate」并弹「应用无法启动或已意外停止」。
+> 0.2.2 修的就是这个。bundle 另外加了一道幂等保护：该 id 已在工厂表里就跳过注册，
+> 重复执行最多是空转，不会再打挂启动。
+
 卸载：删掉上面两处清单项，重启即可。
 
+> [!WARNING]
+> 不要在 profile 的 `node_modules` 里给这个包留裸名链接/junction
+> （例如 `node_modules\dsh-skill-center` → 本仓库）。链接和真正的 scoped 包会各自注册同一个插件，
+> 正好构成「同一插件两个来源」——也就是上面那个 duplicate registration 崩溃的现场。
+> 只装 scoped 包，别的都清掉。
+
 ### 装完侧栏没出现？按顺序查这五步
 
 1. **宿主半边活着吗**：`http://127.0.0.1:19387/dsh-skill-center/api?op=ping` 应回 `{"ok":true,…}`。
@@ -309,6 +470,12 @@ pnpm add @restregular/dsh-skill-center
   `<projectRoot>/.dsh/skills`、`<projectRoot>/.agents/skills`、`$DSH_HOME/skills`、`$DSH_AGENTS_HOME/skills`。
 - frontmatter 改写是字符串级编辑，只动与调用策略相关的键，其余逐字保留（含行尾风格）。
 - 删除只 rename 进 `.trash`。
+- 另注册一个内嵌技能提供方（`ctx.skills.registerProvider`，指向包内 `skills/skill-authoring/`）
+  和 `skill_create` 工具（`ctx.inject(['tools'], …)` + `ctx.tools.register`）。
+  工具 schema 是手写的原始 JSON Schema，只使用 `@deepseek-ai/dsh-tools` 接受的子集 ——
+  本包因此保持零运行时依赖，也不需要宿主侧的模块解析。
+- 三块各自独立降级：缺 `tools` / `webServer`，或者随包技能的资产解析失败，
+  都只写一行日志，其余部分照常挂载。
 
 **浏览器半边**（`client/client.js`）注册两处槽位，不 require 任何 Harness Client 包：
 
@@ -340,6 +507,9 @@ Invoke-RestMethod -Method POST -Uri "http://127.0.0.1:19387/dsh-skill-center/api
 
 非回环来源一律 403。
 
+`create` 与模型工具 `skill_create` 共用一份实现：除 `name` / `description` / `body` / `rootId` 外，
+还接受 `whenToUse`、`resources: [{ path, content }]`、`overwrite`、`modelInvocable`、`userInvocable`。
+
 ### 开发
 
 | 改动 | 生效方式 |
@@ -357,8 +527,18 @@ $exe = "C:\path\to\DeepSeek Harness.exe"; $here = "D:\path\to\dsh-skill-center"
 $env:DSH_SMOKE_SESSION = "<session-id>"; & $exe "$here\client-smoke.mjs"
 # 客户端半侧是否会被浏览器模块图接受(复现 dsh-client-modules 的合成校验)
 & $exe "$here\verify-compose.mjs"
+# 随包技能 + skill_create:纯离线,不碰宿主也不碰真实用户技能根
+node "$here\verify-skill.mjs"
 ```
 
+`verify-compose.mjs` 必须用 Electron 可执行文件跑:它要读 app.asar 里随发行版交付的
+`@deepseek-ai` 包,普通 `node` 打不开 asar。`verify-skill.mjs` 正好相反 ——
+它用桩 ctx 直接 import `lib/index.js`,完全不需要宿主:检查随包技能契约
+（目录名 vs frontmatter、description 非空、`resourceBase` 目录真实存在、正文表格/链接里点到的
+`references/` 等路径是否真的存在）、检查工具 schema 是否落在 `@deepseek-ai/dsh-tools` 支持的子集内,
+然后**真的跑一遍** `skill_create`:新建、资源落盘、覆盖、重名、非法名、路径穿越、平坦文件、
+显式项目根,以及三条降级路径。
+
 > 搬迁/改名注意：客户端模块表按 `(loader baseUrl, loader 行名)` 缓存包元信息，不含文件时间戳。
 > 把包挪到别处后，运行中的宿主仍握着旧路径；浏览器端用的是激活时读进内存的快照，
 > 所以刷新页面照常可用，**下次重启宿主**才会解析新路径。
@@ -371,6 +551,10 @@ $env:DSH_SMOKE_SESSION = "<session-id>"; & $exe "$here\client-smoke.mjs"
 - 没有选中会话时退化为「按工作目录读取」，此时只能看到内嵌技能 + 该 cwd 的项目技能；
   面板底栏会显示实际使用的 cwd 与作用域级别。
 - 目录整体替换制：一次开关改动会让模型的技能目录消息整条重发（这是 Harness 自身的设计）。
+- `skill_create` 是宿主级全局注册：每个 Agent 都会多看到一份工具 schema，没有按 Agent 的开关，
+  只有卸载插件才会消失。
+- 随包 `skill-authoring` 是内嵌技能，面板里只读。它排在 rank 600，所以同名项目级/用户级技能会
+  整体盖过它 —— 这正是定制它的正道。
 
 ### 许可
 

package/client/client.js

@@ -6,11 +6,27 @@
  *      `order: 1` 使其排在 `plugins`(order 0)下方;
  *   2. `main`(keyed, root, key = "skill-center")— 中央区域的面板本体。
  *
+ * 注册 id **必须逐字等于包名**(`@restregular/dsh-skill-center`)。浏览器模块图是按
+ * 包名给行编号的,`ClientModuleSystem.invalidate`/`reload`(HMR 的 `rebuilt` 帧走的
+ * 就是它)只按**行 id** 清理工厂表:注册 id 与行 id 不一致时,旧工厂不会被删掉,
+ * 新版 bundle 一到就撞成
+ * `client-modules: duplicate factory registration ... (bundle executed twice without invalidate?)`,
+ * 于是整条 web boot 变成 "1 entry did not activate"。
+ *
  * 数据与写操作全部走宿主同源回环路由 `/dsh-skill-center/api`(见 ../lib/index.js)。
  * 样式只用宿主主题令牌 `--dsw-*`,不 import 任何 Harness Client 包。
  */
+const MODULE_ID = '@restregular/dsh-skill-center';
+
+/** 该 id 是否已经注册过工厂(宿主 facade 暴露 factories 表;取不到就当作没注册)。 */
+function alreadyRegistered() {
+  const factories = window.__ModuleLoader__?.factories;
+  return factories !== undefined && typeof factories.has === 'function' && factories.has(MODULE_ID);
+}
+
+if (!alreadyRegistered()) {
 window.__ModuleLoader__.load({
-  id: 'dsh-skill-center',
+  id: MODULE_ID,
   factory: (require) => {
     const React = require('react');
     const h = React.createElement;
@@ -765,3 +781,4 @@ window.__ModuleLoader__.load({
     return { apply, inject };
   },
 });
+}

package/lib/index.js

@@ -22,12 +22,18 @@ import {
 } from 'node:fs';
 import { homedir } from 'node:os';
 import { dirname, isAbsolute, join, resolve, sep } from 'node:path';
+import { fileURLToPath } from 'node:url';
 
 /** Loader identity of the Host half. */
 export const name = 'skill-center';
 
-/** Services this plugin needs; absent `webServer` keeps it inert instead of throwing. */
-export const inject = ['skills', 'webServer'];
+/**
+ * Services this plugin needs. `webServer` is *not* listed here: the loopback
+ * route is mounted through `ctx.inject(['webServer'], …)` so a deployment
+ * without a web server still gets the bundled skill and the `skill_create`
+ * tool instead of an inert plugin.
+ */
+export const inject = ['skills'];
 
 /** Loopback route prefix owned by this plugin. */
 const ROUTE = '/dsh-skill-center';
@@ -52,6 +58,26 @@ const ROOT_LABELS = {
   'user-agents': { label: '用户 Agents 技能', rank: 500 },
 };
 
+/**
+ * 随包(内嵌)技能:目录名 == frontmatter name,正文与资源都在本包 `skills/` 下。
+ * 这些技能以 provider 形式注册,资源通过 `resourceBase` 目录暴露给模型 ——
+ * 与第一方的 `@deepseek-ai/dsh-skill-office` 同一形态。
+ */
+const BUNDLED_SKILL_ROOT = fileURLToPath(new URL('../skills/', import.meta.url));
+
+/** 随包技能的名字列表。 */
+const BUNDLED_SKILL_NAMES = ['skill-authoring'];
+
+/** provider 名:面板的 provider 列显示这个名字。 */
+const BUNDLED_SKILL_PROVIDER = 'dsh-skill-center';
+
+/**
+ * 随包技能的 rank,与 `@deepseek-ai/dsh-skill` 的 `BUNDLED_SKILL_RANK` 一致:
+ * 项目根(100/200)与用户根(400/500)的同名技能都能盖过它。
+ * 这里写字面量而不是 import,是为了让本插件保持零运行时依赖。
+ */
+const BUNDLED_SKILL_RANK = 600;
+
 // ---------------------------------------------------------------------------
 // HTTP 小工具
 // ---------------------------------------------------------------------------
@@ -174,6 +200,93 @@ function frontmatterField(text, key) {
   return raw.replace(/^["']/u, '').replace(/["']$/u, '');
 }
 
+// ---------------------------------------------------------------------------
+// 随包技能:注册成 provider,资源用 resourceBase 目录暴露
+// ---------------------------------------------------------------------------
+
+/**
+ * 把本包 `skills/<name>/` 读成注册表候选。
+ *
+ * `resourceBase` 是模型能不能用上这个技能资源的关键:注册表会把
+ * "Base directory for this skill: <绝对路径>" 渲染进 `<skill_resources>`,
+ * 并告诉模型把正文里的相对路径解析到这个目录。缺了它,资源引用就只是空话。
+ *
+ * @param name - 技能名(等于目录名)。
+ * @returns 注册表候选。
+ * @throws 当 SKILL.md 缺失或没有 description 时(属于打包错误,要立刻看见)。
+ */
+function bundledSkillCandidate(name) {
+  const directory = join(BUNDLED_SKILL_ROOT, name);
+  const path = join(directory, 'SKILL.md');
+  const text = readFileSync(path, 'utf8');
+  const description = frontmatterField(text, 'description');
+  if (description === undefined) {
+    throw new Error(`随包技能 "${name}" 的 SKILL.md 缺少 description:${path}`);
+  }
+  return {
+    name,
+    description,
+    invocation: { modelInvocable: true, userInvocable: true },
+    provider: BUNDLED_SKILL_PROVIDER,
+    source: 'bundled',
+    rank: BUNDLED_SKILL_RANK,
+    resourceBase: { kind: 'directory', path: directory },
+    locator: path,
+    path,
+  };
+}
+
+/**
+ * 读随包技能的正文(frontmatter 之后的部分)。
+ * @param name - 技能名。
+ * @returns 已 trim 的 Markdown 正文。
+ */
+function bundledSkillBody(name) {
+  const text = readFileSync(join(BUNDLED_SKILL_ROOT, name, 'SKILL.md'), 'utf8');
+  const match = matchFrontmatter(text);
+  return (match === undefined ? text : text.slice(match[0].length)).trim();
+}
+
+/**
+ * 构造随包技能的 provider。
+ *
+ * `list()` 只回目录摘要;正文每次 `get()` 现读,所以仓库里的 SKILL.md 改完
+ * 下一次加载就生效(注册表只缓存目录,不缓存正文)。
+ *
+ * @returns skill provider 对象。
+ */
+function createBundledSkillProvider() {
+  const candidates = BUNDLED_SKILL_NAMES.map((name) => bundledSkillCandidate(name));
+  const byName = new Map(candidates.map((candidate) => [candidate.name, candidate]));
+  return {
+    name: BUNDLED_SKILL_PROVIDER,
+    list: () => Promise.resolve(candidates),
+    get(winner) {
+      const known = byName.get(winner?.name);
+      if (known === undefined) throw new Error(`随包技能 "${String(winner?.name)}" 不存在`);
+      const { rank: _rank, locator: _locator, ...summary } = known;
+      return Promise.resolve({ ...summary, content: bundledSkillBody(known.name) });
+    },
+  };
+}
+
+/**
+ * 注册随包技能。失败只记一行日志:技能资产出问题不该把整个插件(含面板)带下水。
+ * @param ctx - 宿主上下文。
+ */
+function mountBundledSkills(ctx) {
+  const skills = ctx.skills ?? ctx.get('skills');
+  if (skills === undefined) return;
+  try {
+    ctx.effect(
+      () => skills.registerProvider(createBundledSkillProvider),
+      'skill-center: bundled skills',
+    );
+  } catch (error) {
+    ctx.logger?.warn?.(`skill-center: 随包技能未能注册:${error?.message ?? error}`);
+  }
+}
+
 // ---------------------------------------------------------------------------
 // 技能根目录
 // ---------------------------------------------------------------------------
@@ -548,45 +661,163 @@ async function opSetInvocation(ctx, request) {
 }
 
 /**
- * 新建一个技能目录包。
+ * 归一化资源相对路径:必须是技能包目录内的相对路径,拒绝绝对路径、`.`/`..` 段与
+ * 二次写入 SKILL.md。面板与模型工具都走这道闸。
+ *
+ * @param raw - 原始路径(允许 `\` 分隔)。
+ * @param directory - 技能包目录。
+ * @returns 归一化后的 posix 相对路径,或 undefined(非法)。
+ */
+function normalizeResourcePath(raw, directory) {
+  if (typeof raw !== 'string') return undefined;
+  const value = raw.replace(/\\/gu, '/').trim();
+  if (value === '' || value.startsWith('/') || /^[A-Za-z]:/u.test(value)) return undefined;
+  const segments = value.split('/').filter((segment) => segment !== '');
+  if (segments.length === 0) return undefined;
+  if (segments.some((segment) => segment === '.' || segment === '..')) return undefined;
+  const relative = segments.join('/');
+  if (relative.toLowerCase() === 'skill.md') return undefined;
+  const base = resolve(directory);
+  const target = resolve(base, ...segments);
+  if (target !== base && !target.startsWith(base.endsWith(sep) ? base : base + sep)) return undefined;
+  return relative;
+}
+
+/**
+ * 新建(或按 `overwrite` 覆盖)一个技能包:写 frontmatter + 正文,再把资源文件落到
+ * 同一个技能目录里。面板的 `create` 与模型工具 `skill_create` 共用这一份实现。
+ *
  * @param ctx - 宿主上下文。
- * @param request - `{ sessionId, cwd, name, description, body, rootId, modelInvocable, userInvocable }`。
- * @returns 响应体。
+ * @param request - `{ sessionId, cwd, name, description, whenToUse, body, rootId, resources, overwrite, modelInvocable, userInvocable }`。
+ * @returns 响应体;`ok` 为 false 时带 `error`。
  */
-async function opCreate(ctx, request) {
+async function createSkillBundle(ctx, request) {
   const skillName = String(request.name ?? '').trim();
   if (!SKILL_NAME.test(skillName)) {
     return { ok: false, error: `技能名 "${skillName}" 不合法:只允许小写字母、数字与单个连字符(kebab-case)` };
   }
-  const description = String(request.description ?? '').trim();
+  const description = String(request.description ?? '').replace(/\s+/gu, ' ').trim();
   if (description === '') return { ok: false, error: 'description 必填' };
+  const whenToUse = String(request.whenToUse ?? '').replace(/\s+/gu, ' ').trim();
+  const overwrite = request.overwrite === true;
+  const rawResources = Array.isArray(request.resources) ? request.resources : [];
 
   const catalog = await readCatalog(ctx, request);
-  if (catalog.skills.some((skill) => skill.name === skillName)) {
-    return { ok: false, error: `技能 "${skillName}" 已存在` };
+  const existing = locateOnDisk(skillName, catalog.roots);
+  if (existing === undefined && catalog.skills.some((skill) => skill.name === skillName)) {
+    return {
+      ok: false,
+      error: `技能 "${skillName}" 已存在,但由插件内嵌或其它来源提供,不在可管理的技能根目录里`,
+    };
   }
-  const roots = catalog.roots.filter((root) => root.exists || root.id.startsWith('user-'));
-  const root = roots.find((candidate) => candidate.id === request.rootId)
-    ?? roots.find((candidate) => candidate.id === 'user-agents')
-    ?? roots[0];
-  if (root === undefined) return { ok: false, error: '没有可用的技能根目录' };
-
-  const dir = join(root.path, skillName);
-  if (existsSync(dir)) return { ok: false, error: `目录已存在:${dir}` };
+  if (existing !== undefined && !overwrite) {
+    return { ok: false, error: `技能 "${skillName}" 已存在:${existing.path}(需要覆盖请传 overwrite)` };
+  }
+
+  let root = existing?.root;
+  let directory = existing?.dir;
+  if (existing === undefined) {
+    if (request.rootId !== undefined && request.rootId !== '') {
+      // 显式指定的根允许尚不存在(mkdir 会补上):项目根就在工作区里,
+      // 由调用方明确点名比"静默换到用户根"更可预期。
+      root = catalog.roots.find((candidate) => candidate.id === request.rootId);
+      if (root === undefined) {
+        return {
+          ok: false,
+          error: `未知的技能根 "${request.rootId}";可选:${catalog.roots.map((candidate) => candidate.id).join('、')}`,
+        };
+      }
+    } else {
+      const usable = catalog.roots.filter((candidate) => candidate.exists || candidate.id.startsWith('user-'));
+      root = usable.find((candidate) => candidate.id === 'user-agents') ?? usable[0];
+    }
+    if (root === undefined) return { ok: false, error: '没有可用的技能根目录' };
+    directory = join(root.path, skillName);
+    if (existsSync(directory) && !overwrite) {
+      return { ok: false, error: `目录已存在:${directory}(需要覆盖请传 overwrite)` };
+    }
+  }
+
+  const resources = [];
+  if (existing?.flat === true) {
+    if (rawResources.length > 0) {
+      return {
+        ok: false,
+        error: `技能 "${skillName}" 是平坦文件 ${existing.path},无法承载资源文件;请改用目录包`,
+      };
+    }
+  } else {
+    for (const entry of rawResources) {
+      const relative = normalizeResourcePath(entry?.path, directory);
+      if (relative === undefined) {
+        return {
+          ok: false,
+          error: `资源路径 "${String(entry?.path ?? '')}" 不合法:必须是技能目录内的相对路径,不能是 SKILL.md,也不能含 . 或 .. 段`,
+        };
+      }
+      if (typeof entry?.content !== 'string') {
+        return { ok: false, error: `资源 "${relative}" 缺少 content` };
+      }
+      resources.push({
+        relative,
+        content: entry.content,
+        target: join(directory, ...relative.split('/')),
+      });
+    }
+  }
+
   const invocation = {
     modelInvocable: request.modelInvocable !== false,
     userInvocable: request.userInvocable !== false,
   };
   const lines = ['---', `name: ${skillName}`, `description: ${JSON.stringify(description)}`];
+  if (whenToUse !== '') lines.push(`whenToUse: ${JSON.stringify(whenToUse)}`);
   if (invocation.modelInvocable === false) lines.push('disable-model-invocation: true');
   if (invocation.userInvocable === false) lines.push('user-invocable: false');
   lines.push('---', '');
   const body = String(request.body ?? '').trim();
   lines.push(body === '' ? `# ${skillName}` : body, '');
-  mkdirSync(dir, { recursive: true });
-  const path = join(dir, 'SKILL.md');
+
+  const flat = existing?.flat === true;
+  const path = flat ? existing.path : join(directory, 'SKILL.md');
+  mkdirSync(flat ? dirname(path) : directory, { recursive: true });
   writeFileSync(path, lines.join('\n'), 'utf8');
-  return { ok: true, name: skillName, path, rootId: root.id };
+  for (const resource of resources) {
+    mkdirSync(dirname(resource.target), { recursive: true });
+    writeFileSync(resource.target, resource.content, 'utf8');
+  }
+
+  return {
+    ok: true,
+    name: skillName,
+    path,
+    directory: flat ? dirname(path) : directory,
+    rootId: root?.id,
+    rootLabel: root?.label,
+    replaced: existing !== undefined,
+    resources: resources.map((resource) => resource.relative),
+  };
+}
+
+/**
+ * 新建一个技能目录包(HTTP `op=create`)。
+ * @param ctx - 宿主上下文。
+ * @param request - 见 createSkillBundle。
+ * @returns 响应体。
+ */
+async function opCreate(ctx, request) {
+  const created = await createSkillBundle(ctx, request);
+  if (created.ok !== true) return created;
+  return {
+    ok: true,
+    name: created.name,
+    path: created.path,
+    directory: created.directory,
+    rootId: created.rootId,
+    rootLabel: created.rootLabel,
+    replaced: created.replaced,
+    resources: created.resources,
+  };
 }
 
 /**
@@ -614,6 +845,161 @@ async function opDelete(ctx, request) {
   return { ok: true, name: request.name, movedTo: target, rootId: entry.root.id };
 }
 
+// ---------------------------------------------------------------------------
+// 模型工具:skill_create
+// ---------------------------------------------------------------------------
+
+/**
+ * `skill_create` 的参数 schema。
+ *
+ * 这里手写**原始 JSON Schema**,而不是 import `@deepseek-ai/dsh-tools` 的
+ * `defineTool`:本包因此保持零运行时依赖,也不依赖宿主 node_modules 的解析路径。
+ * 只使用注册表支持的子集:type/oneOf/properties/required/additionalProperties/
+ * items/enum/const 加注解键(description/title…)。
+ */
+const SKILL_CREATE_PARAMETERS = {
+  type: 'object',
+  properties: {
+    name: {
+      type: 'string',
+      description: 'Kebab-case skill name; it is also the bundle directory name.',
+    },
+    description: {
+      type: 'string',
+      description: 'Frontmatter description — the only routing signal the model catalog shows. Write it as "Use when …".',
+    },
+    whenToUse: {
+      type: 'string',
+      description: 'Optional "whenToUse" frontmatter field (provider metadata; not rendered into the catalog).',
+    },
+    body: {
+      type: 'string',
+      description: 'Full Markdown body that follows the frontmatter. Omit to write a placeholder "# <name>" heading.',
+    },
+    root: {
+      type: 'string',
+      enum: ['project-dsh', 'project-agents', 'user-dsh', 'user-agents'],
+      description: 'Target skill root. Defaults to user-agents (~/.agents/skills); pass a project root for a repository-scoped skill.',
+    },
+    resources: {
+      type: 'array',
+      description: 'Extra files written inside the same bundle directory, e.g. references/roots.md or scripts/check.py.',
+      items: {
+        type: 'object',
+        properties: {
+          path: { type: 'string', description: 'Relative path inside the bundle directory.' },
+          content: { type: 'string', description: 'Full UTF-8 file content.' },
+        },
+        required: ['path', 'content'],
+        additionalProperties: false,
+      },
+    },
+    modelInvocable: {
+      type: 'boolean',
+      description: 'Default true; false writes disable-model-invocation: true, keeping the skill out of the model catalog.',
+    },
+    userInvocable: {
+      type: 'boolean',
+      description: 'Default true; false writes user-invocable: false, disabling the user-facing /name entry point.',
+    },
+    overwrite: {
+      type: 'boolean',
+      description: 'Default false: fail when the skill already exists. true rewrites SKILL.md and the listed resources in place.',
+    },
+  },
+  required: ['name', 'description'],
+  additionalProperties: false,
+};
+
+/** `skill_create` 的返回值 schema,与 execute 的返回字段一一对应。 */
+const SKILL_CREATE_OUTPUT = {
+  type: 'object',
+  properties: {
+    name: { type: 'string' },
+    directory: { type: 'string' },
+    skillFile: { type: 'string' },
+    rootId: { type: 'string' },
+    rootLabel: { type: 'string' },
+    resources: { type: 'array', items: { type: 'string' } },
+    replaced: { type: 'boolean' },
+  },
+  required: ['name', 'directory', 'skillFile', 'resources', 'replaced'],
+  additionalProperties: false,
+};
+
+/**
+ * 构造 `skill_create` 工具定义:把面板的"新建"能力交给模型,并顺带解决
+ * "技能根目录在工作区之外"这个真实障碍 —— 文件写入工具被沙箱限制在工作区内,
+ * 而受管技能根不在工作区。
+ *
+ * @param ctx - 宿主上下文。
+ * @returns 可交给 `ctx.tools.register()` 的定义。
+ */
+function skillCreateTool(ctx) {
+  return {
+    name: 'skill_create',
+    description: 'Create a Harness skill bundle: writes <root>/<name>/SKILL.md with the given frontmatter and body, plus any extra files listed in resources, inside that same directory. Use it to author or scaffold a skill, especially when the target skill root is outside the session workspace (~/.agents/skills, ~/.dsh/skills), where the file-write tools are sandboxed and cannot write. Put long-form detail in resources (for example references/<topic>.md, scripts/<tool>.py) and refer to those files by relative path from the body. Fails when a skill of that name already exists unless overwrite is true.',
+    parameters: SKILL_CREATE_PARAMETERS,
+    output: {
+      schema: SKILL_CREATE_OUTPUT,
+      render(_args, value) {
+        const lines = [
+          `${value.replaced === true ? 'Replaced' : 'Created'} skill "${value.name}"`,
+          `directory: ${value.directory}`,
+          `SKILL.md: ${value.skillFile}`,
+          `root: ${value.rootLabel} (${value.rootId})`,
+          value.resources.length === 0 ? 'resources: none' : `resources: ${value.resources.join(', ')}`,
+        ];
+        return [{ type: 'text', text: lines.join('\n') }];
+      },
+    },
+    async execute(args, exec) {
+      const session = exec?.agent?.session;
+      const created = await createSkillBundle(ctx, {
+        sessionId: session?.id,
+        cwd: session?.header?.cwd,
+        name: args.name,
+        description: args.description,
+        whenToUse: args.whenToUse,
+        body: args.body,
+        rootId: args.root,
+        resources: args.resources,
+        overwrite: args.overwrite,
+        modelInvocable: args.modelInvocable,
+        userInvocable: args.userInvocable,
+      });
+      if (created.ok !== true) throw new Error(created.error);
+      return {
+        name: created.name,
+        directory: created.directory,
+        skillFile: created.path,
+        rootId: created.rootId,
+        rootLabel: created.rootLabel,
+        resources: created.resources,
+        replaced: created.replaced,
+      };
+    },
+  };
+}
+
+/**
+ * 注册 `skill_create`。没有 tools 服务的组合里只是少一个工具,
+ * 面板与随包技能照常工作。
+ * @param ctx - 宿主上下文。
+ */
+function mountSkillTools(ctx) {
+  ctx.inject(['tools'], (scoped) => {
+    try {
+      scoped.effect(
+        () => scoped.tools.register(skillCreateTool(scoped)),
+        'skill-center: skill_create tool',
+      );
+    } catch (error) {
+      scoped.logger?.warn?.(`skill-center: skill_create 未能注册:${error?.message ?? error}`);
+    }
+  });
+}
+
 /** 路由表:op → 处理器。 */
 const OPERATIONS = {
   ping: async () => ({ ok: true, plugin: 'dsh-skill-center', version: 1 }),
@@ -631,9 +1017,9 @@ const OPERATIONS = {
 
 /**
  * 挂载回环路由,向客户端暴露技能目录与管理操作。
- * @param ctx - 宿主上下文(已保证 skills 与 webServer 就绪)。
+ * @param ctx - 宿主上下文(已保证 webServer 就绪)。
  */
-export function apply(ctx) {
+function mountRoutes(ctx) {
   const webServer = ctx.webServer ?? ctx.get('webServer');
   if (webServer === undefined) return;
 
@@ -689,3 +1075,14 @@ export function apply(ctx) {
     },
   }), 'skill-center: loopback routes');
 }
+
+/**
+ * 插件体:随包技能、模型工具、回环路由三块互相独立降级 ——
+ * 任何一块失败都只记日志,不会让宿主启动失败,也不会拖垮另外两块。
+ * @param ctx - 宿主上下文(已保证 skills 就绪)。
+ */
+export function apply(ctx) {
+  mountBundledSkills(ctx);
+  mountSkillTools(ctx);
+  ctx.inject(['webServer'], (scoped) => mountRoutes(scoped));
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@restregular/dsh-skill-center",
-  "version": "0.2.1",
-  "description": "技能中心 — DeepSeek Harness 技能管理面板：浏览当前会话可见的所有技能、查看正文、开关模型/用户调用、新建与删除。 · Skill Center for DeepSeek Harness: browse and manage the skills visible to the current session.",
+  "version": "0.3.0",
+  "description": "技能中心 — DeepSeek Harness 技能管理面板：浏览当前会话可见的所有技能、查看正文、开关模型/用户调用、新建与删除；随包附带 skill-authoring 指导技能与 skill_create 模型工具。 · Skill Center for DeepSeek Harness: browse and manage the skills visible to the current session, with a bundled skill-authoring skill and a skill_create model tool.",
   "type": "module",
   "main": "lib/index.js",
   "license": "MIT",
@@ -17,6 +17,7 @@
   "files": [
     "lib",
     "client",
+    "skills",
     "cordis.patch.yml"
   ],
   "exports": {
@@ -45,7 +46,9 @@
     "deepseek",
     "skills",
     "skill-center",
-    "agent-skills"
+    "agent-skills",
+    "skill-authoring",
+    "skill-create"
   ],
   "publishConfig": {
     "access": "public",

package/skills/skill-authoring/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: skill-authoring
+description: "Use when creating, editing, moving, or reviewing a Harness skill: choosing the skill root for project or user scope, writing SKILL.md frontmatter and body, placing the skill's resource files next to it, or shipping a skill inside a plugin."
+---
+
+# Authoring Harness skills
+
+A skill is a **directory bundle**: `<root>/<name>/SKILL.md` plus every resource file that `SKILL.md` refers to. The model sees only each skill's `name` and `description` in the session catalog; the body is loaded on demand when the model or the user invokes it, and resource files are never loaded automatically. A skill's body must therefore say which file to read and when.
+
+## Short path
+
+1. Pick the root — see `references/roots.md`. Project-scoped skill: `<projectRoot>/.agents/skills`. Available in every project: `$DSH_AGENTS_HOME/skills` (`~/.agents/skills`).
+2. Create `<root>/<name>/SKILL.md`. `name` is kebab-case and should equal the directory name.
+3. Keep the frontmatter minimal: `name` and `description` are required; the body starts after the closing `---`.
+4. Put resource files in subdirectories of **that same bundle directory** and point at them with relative paths.
+5. Verify: the frontmatter parses, `name` matches the directory, every referenced file exists, and the skill appears in the Skill Center panel (and in the catalog of the next model step).
+
+Use the `skill_create` tool when the target root is outside the current workspace: the file-write tools are sandboxed to the workspace, while the managed skill roots are not, so a direct write to `~/.agents/skills/...` is denied. `skill_create` writes `<root>/<name>/SKILL.md` plus any `resources` you pass, in one call, and returns the absolute bundle directory. Inside the workspace (for example `<projectRoot>/.agents/skills`) ordinary file writes work fine.
+
+## Frontmatter decides who can invoke the skill
+
+| Field | Effect |
+|---|---|
+| `description` | the only routing signal in the catalog — write it as "Use when …" and name the tasks, not the implementation |
+| `disable-model-invocation: true` | the skill leaves the model catalog entirely; only an explicit `/name` from the user loads it |
+| `user-invocable: false` | `/name` stops working for humans; the model can still load the skill |
+
+The camelCase spellings (`disableModelInvocation`, `modelInvocable`, `userInvocable`) are **rejected**: a skill carrying one is skipped with a warning instead of loading. The full contract, the accepted boolean spellings, and the silent failure modes are in `references/frontmatter.md`.
+
+## Resource placement
+
+Everything a skill needs lives under its own bundle directory, because the base directory reported to the model *is* that directory and relative paths resolve against it:
+
+```
+<root>/<name>/
+  SKILL.md
+  references/   long-form detail the body points at by relative path
+  scripts/      commands the body tells the model to run
+  assets/       fixtures, templates, images
+```
+
+The loaded skill arrives wrapped in `<skill_content>` with a `<skill_resources>` block that names the absolute base directory; the model is told to resolve relative paths against it before reading. Files under a bundle's resource subtrees are read directly by the file tools when the body asks for them, so editing a reference file needs no catalog refresh — only the skill *list* (names, descriptions, invocation policy) is cached. Details, path rules and the Desktop `app.asar` caveat: `references/resources.md`.
+
+## Shipping a skill inside a plugin
+
+A plugin publishes its own skills instead of writing into the user's roots: it registers a skill provider (or a runtime skill) and points each candidate at an asset directory inside the package. Use this when the skill's instructions and resources must version together with the code they describe. `references/plugin-bundled.md` has the provider contract, the candidate fields, the rank, and the two registration APIs.
+
+## Read next
+
+Read only the files this task needs; the table is complete.
+
+| Task | File |
+|---|---|
+| Which root a skill belongs in, root precedence, project-root detection | `references/roots.md` |
+| Frontmatter fields, validation, and why a skill silently does not load | `references/frontmatter.md` |
+| Where resource files go, how the model is told to find them, Desktop limits | `references/resources.md` |
+| Shipping skill instructions and resources inside a plugin package | `references/plugin-bundled.md` |
+| Starter bundle for a new skill | `templates/minimal/SKILL.md` |

package/skills/skill-authoring/references/frontmatter.md

@@ -0,0 +1,71 @@
+# The SKILL.md contract
+
+## File shape
+
+```markdown
+---
+name: my-skill
+description: "Use when …"
+---
+
+# Body
+
+Instructions, loaded only when the skill is invoked.
+```
+
+- The first line must be exactly `---`. A UTF-8 BOM before it breaks the check in `dsh-skill-filesystem`, and the file is then ignored as "missing YAML frontmatter" — this plugin's own frontmatter editor tolerates a BOM, the discovery parser does not.
+- The frontmatter ends at the next line that is exactly `---`. The body is everything after it, **trimmed** at both ends.
+- The frontmatter is parsed as YAML and must be a mapping. An array or a bare scalar is not frontmatter.
+- A directory bundle holds this file as `<root>/<name>/SKILL.md`; the flat form `<root>/<name>.md` is equivalent, but its resource base directory is the whole root, so use the bundle form for anything with resources.
+
+## Fields
+
+| Field | Required | Meaning |
+|---|---|---|
+| `name` | yes | routing name; must match `^[a-z0-9]+(?:-[a-z0-9]+)*$` — lowercase kebab-case, no underscores, no double or trailing hyphens |
+| `description` | yes | the routing sentence the model sees in the catalog; write "Use when …" and name the tasks |
+| `whenToUse` | no | provider metadata; **not** rendered into the session catalog, so it never helps routing — put routing text in `description` |
+| `metadata` | no | free-form object, preserved for consumers |
+| `disable-model-invocation` | no | `true` keeps the skill out of the model catalog and the `skill` tool; only an explicit `/name` from the user loads it |
+| `user-invocable` | no | `false` disables `/name` for humans while the model keeps access |
+
+Invocation keys accept a boolean or `1`/`0`/`true`/`false`/`yes`/`no`/`on`/`off` (case-insensitive). Any other value throws, and the skill is skipped.
+
+### The spelling trap
+
+The camelCase forms are **rejected on purpose**:
+
+- `disableModelInvocation` → use `disable-model-invocation`
+- `modelInvocable` → use `disable-model-invocation`
+- `userInvocable` → use `user-invocable`
+
+A file carrying one is skipped with `frontmatter field "…" is unsupported; use "…"`. There is no defaulting, and no partial load.
+
+## The four invocation states
+
+| Frontmatter | Model can load | `/name` works |
+|---|---|---|
+| (neither key) | yes | yes |
+| `disable-model-invocation: true` | no | yes |
+| `user-invocable: false` | yes | no |
+| both | no | no — the skill is registered but unreachable; almost always a mistake |
+
+`disable-model-invocation: true` is the right choice for a workflow a human must start deliberately (a release, a destructive migration): the catalog and the `skill` tool never advertise it, and the only entry point is the user typing `/name`.
+
+## Why a skill does not load
+
+Discovery logs one warning and skips the file; nothing reaches the model catalog, so a broken skill is indistinguishable from an absent one from inside the session. Check the host log for `skill file <path> ignored:` and the reason:
+
+| Warning | Cause |
+|---|---|
+| `missing YAML frontmatter` | no leading `---`, a BOM before it, or no closing `---` |
+| `invalid YAML frontmatter` | the block does not parse (tabs, unbalanced quotes, bad nesting) |
+| `frontmatter requires name and description` | either key missing, or not a non-empty string |
+| `invalid skill name "…"` | uppercase, underscore, space, or a doubled/trailing hyphen |
+| `invalid invocation frontmatter` | a non-boolean value, or a camelCase legacy key |
+
+## Rules that keep the skill manageable
+
+- **Keep `name` equal to the directory name.** Discovery takes the name from frontmatter, but the Skill Center panel and `skill_create` locate a skill on disk as `<root>/<name>/SKILL.md`. A mismatch (or two directories claiming one name) makes a skill that loads but cannot be opened, edited or deleted.
+- **One skill per bundle.** A second `SKILL.md` at a scanned root's direct child level becomes a second skill; only put extra `SKILL.md` files deeper, where discovery does not look.
+- **Do not write these files by hand-editing YAML with a formatter.** The panel rewrites only the invocation keys and preserves the rest byte for byte, but an external formatter that reflows the block can turn `description` into a folded scalar and change what the model sees.

package/skills/skill-authoring/references/plugin-bundled.md

@@ -0,0 +1,89 @@
+# Shipping skills inside a plugin
+
+A plugin that owns a workflow should publish the skill with the code it describes, not copy files into the user's roots: the package versions both together, and every session in the profile sees the same instructions. The host half needs only `skills` in its `inject` list.
+
+## Provider registration (recommended)
+
+`ctx.skills.registerProvider()` registers a catalog of skills that live in this package's own asset directory. Candidates are validated by the registry before they are cached, and each one can carry a `resourceBase` that tells the model where its resource files are.
+
+```js
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { join } from 'node:path';
+
+const NAME = 'my-skill';
+const ROOT = fileURLToPath(new URL('../skills/', import.meta.url)); // package assets
+const RANK_BUNDLED = 600; // @deepseek-ai/dsh-skill BUNDLED_SKILL_RANK
+
+export function apply(ctx) {
+  const directory = join(ROOT, NAME);
+  const path = join(directory, 'SKILL.md');
+  const raw = readFileSync(path, 'utf8');
+  const description = /* parse frontmatter, require a non-empty description */;
+  const candidate = {
+    name: NAME,
+    description,
+    invocation: { modelInvocable: true, userInvocable: true },
+    provider: 'my-plugin',        // must equal the provider's name
+    source: 'bundled',
+    rank: RANK_BUNDLED,
+    resourceBase: { kind: 'directory', path: directory },
+    locator: path,                // opaque; handed back to get()
+    path,                         // shown by discovery consumers such as this panel
+  };
+  ctx.effect(() => ctx.skills.registerProvider(() => ({
+    name: 'my-plugin',
+    list: () => Promise.resolve([candidate]),
+    async get(winner, options) {
+      const { rank, locator, ...summary } = winner;
+      return { ...summary, content: /* body after the frontmatter */ };
+    },
+  })), 'my-plugin: skill provider');
+}
+```
+
+Rules the registry enforces:
+
+- `provider` on every candidate must equal the provider's own `name`; two providers in one layer may not share a name, and `runtime` is reserved.
+- `name` must be kebab-case, `description` non-empty, `invocation` exactly two booleans, `rank` a finite number, `source` a string. One malformed candidate fails the whole observation, so validate while building the list, not inside `get()`.
+- `list()` returns an array, or `{ candidates, complete: false }` when discovery was partial. Read files inside `get()` — **bodies are never cached**, so re-reading keeps edits visible; only the catalog is cached until you call the `invalidate()` handed to the provider factory.
+- `get()` must return the selected candidate's `name` unchanged. A mismatch makes the registry drop its cached catalogs.
+- Register inside `ctx.effect(...)` so disposal removes the provider and invalidates the catalog when the plugin reloads.
+
+`resourceBase: { kind: 'directory', path }` is what makes the skill's resources usable: the model receives that absolute directory and is told to resolve relative paths against it. Without it the hint degrades to "resources are managed by provider X" and a resource-referencing skill becomes unusable.
+
+## Runtime registration (in-memory)
+
+`ctx.skills.register(skill)` inserts one in-memory skill into the calling context's layer, labelled with the reserved `runtime` provider and rank 250. It is the right tool when the instructions are generated per deployment (paths, versions, feature flags) rather than shipped as files:
+
+```js
+ctx.skills.register({
+  name: 'deployment-notes',
+  description: 'Use when …',
+  source: 'generated',
+  content: '# Deployment\n\n' + generatedBody,
+  invocation: { modelInvocable: true, userInvocable: true },
+});
+```
+
+`register()` takes the **definition**, not a candidate: `content` is required, `source` is required, and the object itself is handed back as the loaded definition. It accepts anything the provider form accepts except `rank`, `locator` and `get()`. Prefer a provider whenever the skill refers to resource files.
+
+## Bundle-provided root
+
+A profile bundle can instead add a plain directory root to the filesystem provider with a patch row, which buys the watcher and needs no provider code:
+
+```yaml
+- id: skill-filesystem
+  name: '@deepseek-ai/dsh-skill-filesystem'
+  config:
+    bundledSkillDir: '<absolute directory holding <name>/SKILL.md bundles>'
+```
+
+That row scans the directory at rank 600 (`$DSH_BUNDLED_SKILL_DIR` is the default when the field is absent). It is a single directory, it is only configurable from the profile patch, and it cannot express a URL or opaque resource base.
+
+## Consequences to state in the package README
+
+- **Read-only.** Such skills live outside the managed roots, so the Skill Center panel lists them as *embedded*: invocation switches, editing and deletion are disabled. That is intentional — the package owns them.
+- **Rank 600.** Any project or user skill with the same name shadows it, which is how a user overrides a shipped workflow.
+- **`app.asar`.** In the desktop build a bundled package may live inside `app.asar`; the Host side reads those paths fine, but shell commands, `glob`, `grep`, `node` and package managers cannot. Skills that tell the model to *run* a bundled script must say to copy it into the workspace first.
+- **Frontmatter is parsed twice.** The provider reads the description for the catalog and the body for the load; keep one parser for both so the two can never disagree.

package/skills/skill-authoring/references/resources.md

@@ -0,0 +1,51 @@
+# Skill resources
+
+## How the model is told where they are
+
+When a skill is loaded, the body is rendered inside `<skill_content>` together with a `<skill_resources>` block that carries the base location:
+
+| Provider sets | `<skill_resources>` says |
+|---|---|
+| `resourceBase: { kind: 'directory', path }` | `Base directory for this skill: <path>` — "Resolve relative paths mentioned by this skill against the base directory before using them. Load referenced resources only as needed." |
+| `resourceBase: { kind: 'url', url }` | `Base URL for this skill: <url>` |
+| `resourceBase: { kind: 'opaque', description }` | `Resources for this skill: <description>` |
+| nothing | "Resources for this skill are managed by provider …" |
+
+For every filesystem skill the base directory is the **bundle directory** (`<root>/<name>/`); for the flat `<name>.md` form it is the whole root. Resources are a *hint*, not an attachment: nothing lists the directory and nothing fetches a referenced file. The body has to name the file and say when to read it.
+
+## Layout
+
+```
+<root>/<name>/
+  SKILL.md          routing + the workflow itself
+  references/       detail too long for the body: contracts, tables, edge cases
+  scripts/          commands the body tells the model to run
+  assets/           fixtures, images, sample data
+  templates/        files meant to be copied into the workspace
+```
+
+These names are a convention, not a requirement — only the paths your `SKILL.md` actually mentions matter. Keep them stable: a renamed reference breaks every body that points at it.
+
+## Path rules
+
+- Write paths **relative to the base directory** (`references/api.md`, `scripts/check.py`). Never write an absolute path into a skill: the root differs per machine and per install.
+- Never rely on the working directory. A skill loads in whatever cwd the session has; the base directory is the only stable anchor.
+- Do not reference files outside the bundle directory. A resource in the workspace, another skill, or `$DSH_HOME` may be absent at load time, and the base directory is the one location the model is told to trust.
+- For a script, spell out how to run it: interpreter first, absolute path built from the base directory, and the expected cwd. On Windows the shell is PowerShell; `python`/`node` availability differs per host, so state the interpreter explicitly and prefer a command that fails loudly over one that silently does nothing.
+- Keep scripts side-effect-free or clearly gated: a skill body is followed by a model that will run what it says.
+
+## Size and cost
+
+- A loaded body has **no size cap** — everything in `SKILL.md` lands in context on every load. Keep it to routing plus the workflow, and push long-form detail into `references/` files that the body names one by one.
+- Reference files cost nothing until read, so favor several focused files over one large one, and say in the body when each is needed ("read `references/roots.md` before choosing a directory").
+- The catalog shows only `description` (truncated to the configured limit, 500 characters by default), so a long description buys nothing beyond the first sentence or two.
+
+## Writing resources
+
+- Agent file-write tools are sandboxed to the session workspace, so a resource that belongs in a user-level root (`~/.agents/skills/…`) cannot be written with them. Use the `skill_create` tool's `resources` argument (a Host-side write confined to managed roots), or ask for approval.
+- Editing or adding a resource file under an existing bundle does **not** change the catalog and needs no refresh — resource files are read directly by the file tools when the body asks for them. Adding a whole new skill bundle *is* a catalog change.
+- Keep the plugin's write guard in mind: `skill_create` only writes inside `<root>/<name>/` and rejects absolute paths, `..` segments and a second `SKILL.md`, so resources cannot be smuggled out of the bundle.
+
+## Desktop caveat
+
+Skills shipped inside a plugin that lives in `app.asar` (the first-party Office skills, for example) sit on a path that only the Host process's own file reads can open. Shell commands, the glob and search tools, `node` and package managers all fail on `app.asar` paths — copy such a file into the workspace with the file-read/file-write tools before running anything against it. Skills under the user and project roots are ordinary files with no such limit.

package/skills/skill-authoring/references/roots.md

@@ -0,0 +1,44 @@
+# Where skills live
+
+Local skills are discovered by `@deepseek-ai/dsh-skill-filesystem`. It scans a fixed list of **roots** and, in each root, only that root's **direct children**: a directory bundle `<name>/SKILL.md`, or a flat file `<name>.md`. Nested `**/SKILL.md` search is deliberately unsupported, so a skill inside `assets/` or `templates/` of another skill is never discovered.
+
+## The root table
+
+`<projectRoot>` is the nearest ancestor of the session's working directory that contains `.git`; if no ancestor has one, the working directory itself is the project root.
+
+| Rank | Source id | Path | Scope |
+|---|---|---|---|
+| 100 | `project-dsh` | `<projectRoot>/.dsh/skills` | this project |
+| 200 | `project-agents` | `<projectRoot>/.agents/skills` | this project |
+| 250 | `runtime` | in-memory (`ctx.skills.register()`) | plugin-provided |
+| 300 | `custom` | profile `customSkillDirs` entries | deployment |
+| 400 | `user-dsh` | `$DSH_HOME/skills` (`~/.dsh/skills`) | all projects |
+| 500 | `user-agents` | `$DSH_AGENTS_HOME/skills` (`~/.agents/skills`) | all projects |
+| 600 | `bundled` | `bundledSkillDir` / `$DSH_BUNDLED_SKILL_DIR` | shipped with the app or a plugin |
+
+`$DSH_HOME` defaults to `~/.dsh` and `$DSH_AGENTS_HOME` to `~/.agents`; both can be overridden by the environment. The `.system` subdirectory of `$DSH_HOME/skills` is skipped.
+
+## Choosing a root
+
+- **Project-specific workflow** (build/test/release steps of one repository): `<projectRoot>/.agents/skills`. It travels with the repository; `<projectRoot>/.dsh/skills` has the same scope and outranks it.
+- **Reusable across projects**: `$DSH_AGENTS_HOME/skills` (`~/.agents/skills`). This is what the Skill Center panel and `skill_create` use by default.
+- **Personal Harness-only workflow**: `$DSH_HOME/skills` (`~/.dsh/skills`).
+- Never hand-write into `custom` or `bundled` roots: they belong to the deployment and the package that ships them.
+
+Only the four roots marked `project-dsh`, `project-agents`, `user-dsh` and `user-agents` are **managed** by this plugin: the panel and `skill_create` may create and write there, and every write is confined to a root that exists on disk (or to a user root, which they create). A skill that lives anywhere else — inside a plugin package, a `custom` directory, or under a `bundled` root — is listed as **embedded** and read-only.
+
+## Precedence
+
+One name resolves to exactly one skill:
+
+1. **Layer first.** The registry keeps a host layer plus one layer per agent-preset scope; the nearest layer wins outright, so a preset-mounted repository plugin can shadow a host skill.
+2. **Rank second**, within one layer: the lowest rank wins, which is why a project skill shadows a user skill of the same name and both shadow a `bundled` one.
+3. Registration order, then provider-local order break the remaining ties.
+
+Shadowed duplicates are logged and hidden; there is no API that lists them. If an edit seems to have no effect, check for a same-named skill in a nearer layer or a lower rank — that is the usual cause.
+
+## Presence and refresh
+
+- A root that does not exist yet is simply empty; missing roots are polled until they appear, so creating `~/.agents/skills` later still works without a restart.
+- Discovered skills are re-read on every load, but the *catalog* (names, descriptions, invocation policy) is cached per workspace and only refreshes when the provider invalidates it: adding, renaming or deleting a bundle, a flat `<name>.md`, or a direct `SKILL.md` triggers that invalidation. Changes under a bundle's resource subtrees do not.
+- A skill present on disk but not in the catalog is usually invalid frontmatter, not a caching problem — see `frontmatter.md`.

package/skills/skill-authoring/templates/minimal/SKILL.md

@@ -0,0 +1,28 @@
+---
+name: <kebab-case-name>
+description: "Use when <the task or question this skill answers, named in the user's terms>."
+---
+
+# <Title>
+
+<One paragraph: what this skill produces and the boundary of the request it answers.>
+
+## Workflow
+
+1. <First concrete step, with the command or file it acts on.>
+2. <Second step.>
+3. <Verification step: what proves the result is correct.>
+
+## Constraints
+
+- <Rules that are not obvious from the steps: formats, ordering, what must not be touched.>
+- <Where output belongs, and what must never be written.>
+
+## Read next
+
+| Task | File |
+|---|---|
+| <the sub-task that needs detail> | `references/<topic>.md` |
+| <a repeatable action> | `scripts/<tool>.py` |
+
+Delete any row this skill does not need, and delete this instruction along with it. Keep every referenced file inside this bundle directory.