docs: rebalance prose cleanup and add trimming skill

packages/skill/skill-local/README.md

@@ -28,7 +28,7 @@ Default roots are resolved in this provider's rank order:
 | 400 | `user-dsh` | `<dshHome>/skills` |
 | 500 | `user-agents` | `<agentsHome>/skills` |
 
-The project root is the nearest ancestor containing `.git`; without one, the current cwd is used. The user DSH root skips its `.system` child so system-owned directories are not accidentally treated as normal user skills. DeepSeek Harness no longer ships built-in system skills from this provider; additional built-ins can be supplied later by another provider.
+The project root is the nearest ancestor containing `.git`; without one, the current cwd is used. The user DSH root skips its `.system` child so system-owned directories are not treated as normal user skills. This provider supplies project and user skills; another provider may supply built-in system skills.
 
 When `ctx.fs` is available, discovery lists roots through `ctx.fs.listDir`, reads skill files through `ctx.fs.readText`, and probes `.git` through the filesystem service. Full skill loads forward the lookup abort signal to filesystem metadata and content reads. Without a filesystem service, the provider falls back to abortable Node filesystem I/O so minimal local contexts can still load skills. Missing, unreadable, or malformed skill files warn and skip instead of failing the whole request.
 

packages/skill/skill/src/index.ts

@@ -175,8 +175,8 @@ export class SkillService extends Service {
   }
 
   /**
-   * Register a borrowed same-process provider. Duplicate and reserved names
-   * throw; remote initialization belongs in `list()`. Fiber disposal unregisters
+   * Register a borrowed same-process provider synchronously during plugin apply. Duplicate and
+   * reserved names throw; remote initialization belongs in `list()`. Fiber disposal unregisters
    * the provider and invalidates catalog caches.
    * @param provider - the provider to register by `provider.name`.
    * @returns the exact Cordis effect disposer that unregisters this provider;
@@ -210,11 +210,11 @@ export class SkillService extends Service {
   }
 
   /**
-   * Register a borrowed readonly runtime skill. Project entries outrank runtime
-   * entries, which outrank user entries. A duplicate is ignored with a no-op
-   * disposer so it cannot remove the first registration.
+   * Register a borrowed readonly runtime skill. Project entries outrank runtime entries, which
+   * outrank user entries. Same-name runtime entries are first-wins; a duplicate logs a warning and
+   * receives a no-op disposer so it cannot remove the winner.
    * @param skill - the complete skill definition to expose for discovery.
-   * @returns the exact Cordis disposer, which also invalidates caches.
+   * @returns the exact Cordis effect disposer, preserving composite teardown order and invalidating caches.
    */
   register(skill: SkillRegistration): () => void {
     validateRuntimeSkill(skill)
@@ -256,8 +256,9 @@ export class SkillService extends Service {
   }
 
   /**
-   * Load and validate the winning provider candidate. Cancellation is checked
-   * after selection and raced against provider loading.
+   * Load and validate the winning candidate, passing its opaque discovery locator back to the
+   * provider. Cancellation is rechecked after selection, including cache hits, and raced against
+   * loading so an uncooperative provider cannot hang the caller.
    * @param name - kebab-case skill name.
    * @param options - lookup options; `cwd` selects workspace-sensitive skills and `signal` cancels work.
    * @returns the full skill, including body content, or `undefined`.

packages/skill/tool-skill/README.md

@@ -16,6 +16,10 @@ The plugin contributes one user-role `<system-reminder>` catalog through `agent/
 |---|---|---|
 | `name` | string (required) | Exact kebab-case skill name from the available skills listing. |
 
-Execution uses the calling agent's `session.header.cwd` so workspace-sensitive providers can resolve the right winning skill. A successful call returns one text tool result with `<skill_content name="...">`, containing `<skill_resources>` followed by `<skill_instructions>`. Resource guidance resolves paths or URLs explicitly referenced by the loaded instructions against `resourceBase`; referenced scripts, references, and assets load only when needed, and the tool does not enumerate a skill directory. Local filesystem skills provide a base directory, while remote or embedded providers can provide a URL or opaque provider-managed guidance. A name that cannot be resolved reports that the skill is unknown or no longer available; invalid names and skills marked `disableModelInvocation: true` retain distinct `isError` results.
+Execution uses the calling agent's `session.header.cwd` so workspace-sensitive providers resolve the winning skill. A successful call returns one text result containing `<skill_content name="...">`, `<skill_resources>`, and `<skill_instructions>`.
+
+Resource guidance resolves only paths or URLs explicitly referenced by the instructions against `resourceBase`; scripts, references, and assets load on demand, and the result does not enumerate a skill directory. Local providers may supply a directory, while remote or embedded providers may supply a URL or opaque loading guidance.
+
+An unresolved name reports that the skill is unknown or no longer available. Invalid names and `disableModelInvocation: true` skills produce distinct error results.
 
 The tool does not call `agent.inject()` in v1. Its result is already recorded as the tool result and becomes available to the next model step without duplicating the content as synthetic context.

packages/skill/tool-skill/src/index.ts

@@ -66,8 +66,8 @@ export function apply(ctx: Context, config: Config = {}): void {
     throw new Error('dsh-tool-skill: registered skill tool is not visible in the global registry')
   }
 
-  // Register after the tool so reverse-order fiber teardown removes this guidance listener
-  // before its referenced tool.
+  // Register after the tool so reverse teardown removes guidance first. Exact definition
+  // identity prevents a scoped shadow merely named `skill` from inheriting this catalog.
   ctx.on('agent/session-prefix', async (agent, _prefix, signal, next): Promise<Message[]> => {
     if (ctx.tools.get(skillTool.name, agent) !== registeredSkillTool) return await next()
     const skills = await ctx.skills.list({ cwd: agent.session.header.cwd, signal })