@restregular/dsh-skill-center 0.2.2 → 0.3.1

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.