Merge pull request #109 from deepseek-harness/codex/skill-system

Add skill registry and local provider

.gitignore

@@ -19,4 +19,3 @@ tmp/
 .DS_Store
 .idea
 mise.toml
-

AGENTS.md

@@ -15,6 +15,7 @@ packages/    Harness packages at packages/<group>/<pkg>/, all named @deepseek-ai
   llm/         LLM seam + the DeepSeek adapters (hand-rolled + pi-ai design twin)
   bash/        bash executor seam + local impl + model-facing bash tools
   fs/          filesystem seam + local impl + policy gate + read/write/edit tools
+  skill/       skill provider registry + local impl + catalog/loader tool
   web/         web seam + search/fetch providers + model-facing web tools
   compact/     compaction seam + basic backend
   subagent/    subagent seam + spawn/fork/ACP backends + delegation tool
@@ -71,7 +72,7 @@ pnpm run hygiene
 out=$(printf 'echo ci smoke\n' | pnpm run demo:echo 2>&1)
 printf '%s\n' "$out" | grep -q '\[tool call\] echo({"text":"ci smoke"})'
 printf '%s\n' "$out" | grep -q '\[tool result\] ECHO: CI SMOKE'
-ls .sessions/_no-cwd/main-session-*.jsonl >/dev/null
+test -n "$(find .sessions -path '.sessions/cwd-*/main-session-*.jsonl' -type f -print -quit)"
 rm -rf .sessions
 pnpm exec vitest run --config vitest.e2e.config.ts packages/ui/stdio-agent/tests/built-bin.e2e.ts packages/ui/acp-agent/tests/built-bin.e2e.ts packages/workflow/workflow-workerthread/tests/built-worker.e2e.ts packages/code-runtime/code-runtime-worker/tests/built-lib.e2e.ts
 ```

docs/architecture.md

@@ -1,6 +1,6 @@
 # DeepSeek Harness Architecture
 
-The project is an SDK for building agent harnesses. The idea is to have **everything as a plugin**. For example, the agent loop is just one plugin shipped by default.
+The **DeepSeek Harness SDK** builds agent harnesses on Cordis. The principle is simple: **everything is a plugin**. The shipped loop is one plugin, not a privileged kernel.
 
 ## Overview
 
@@ -29,6 +29,7 @@ Composition is preferred over inheritance. `packages/core/` is a repository grou
 | `ctx.sandbox` | [`sandbox/`](../packages/sandbox/README.md) | same-world process confinement (argv wrapping, per-call policy) |
 | `ctx.codeRuntime` | [`code-runtime/`](../packages/code-runtime/README.md) | model-written program execution |
 | `ctx.fs` | [`fs/`](../packages/fs/README.md) | filesystem provider primitives and policy events |
+| `ctx.skills` | [`skill/`](../packages/skill/README.md) | skill provider registry and progressive disclosure |
 | `ctx.web` | [`web/`](../packages/web/README.md) | search/fetch provider registries |
 | `ctx.compact` | [`compact/`](../packages/compact/README.md) | session-log compaction |
 | `ctx.subagents` | [`subagent/`](../packages/subagent/README.md) | named delegation providers |
@@ -128,11 +129,11 @@ Streaming is a raw chunk protocol (`block-start` through `finish`) with `BlockAs
 
 A swappable capability usually splits into **interface / implementation / consumer**: the interface owns the `ctx` key and event names; an implementation registers a backend; a consumer exposes model-facing behavior through `ctx.tools` or prompt assembly. The bash trio is the reference shape, and the [capability graph](capability-seams.md) shows the current package families.
 
-Some cases bend the template deliberately. LLM keeps interface and consumer event names together because adapters are the implementations. Filesystem adds policy checks around provider primitives. Web is one service with search and fetch provider registries, so provider swaps do not rename model tools. Subagents use a named provider registry because multiple delegation backends can coexist; `spawn` starts fresh, `fork` seeds from the parent's completed-turn prefix, and ACP can drive an out-of-process child ([subagent.md](core-data-structures/subagent.md)).
+Some seams bend the template deliberately. LLM keeps interface and consumer vocabulary together because adapters are the implementations. Filesystem adds policy gates around provider primitives. Web is one service with search and fetch provider registries, so provider swaps do not rename model tools. Skills and subagents use named provider registries; local skills scan project/user roots, and other providers can add embedded or remote catalogs without registry/tool changes. Subagents spawn fresh, fork from the parent's completed-turn prefix, or use ACP children ([subagent.md](core-data-structures/subagent.md)).
 
 ### Bundles And Apps
 
-`dsh-agent-core` is the default bundle: one plugin loading the agent loop ([README](../packages/core/agent-core/README.md)). App packages compose it with a front end and own the entrypoint `bin`: `dsh-stdio-agent` for the terminal REPL, and `dsh-acp-agent` for ACP over JSON-RPC stdio with no stdout logger ([ui/](../packages/ui/README.md)). A deployment is a thin `cordis.yml` leaf: swappable backends, one app entry, and optional product tools ([examples/](../examples/AGENTS.md), [runnable wirings](cookbook/extension-cookbook.md#runnable-wirings), [graph atlas](graph-atlas.md)).
+`dsh-agent-core` is the default composition bundle: one plugin loading the shared spine ([README](../packages/core/agent-core/README.md)). App packages compose it with a front door and boot `bin`: `dsh-stdio-agent` for terminal REPL, and `dsh-acp-agent` for ACP over JSON-RPC stdio with no stdout logger ([ui/](../packages/ui/README.md)). A deployment is a thin `cordis.yml` leaf: swappable backends, one app entry, and optional product tools ([examples/](../examples/AGENTS.md), [runnable wirings](cookbook/extension-cookbook.md#runnable-wirings), [graph atlas](graph-atlas.md)).
 
 ### Where New Behavior Goes
 
@@ -158,4 +159,4 @@ The [extension cookbook](cookbook/extension-cookbook.md) carries plugin skeleton
 - Exact event and service signatures in [events](cordis-catalog/events.md)
 - [services](cordis-catalog/services.md) catalogs
 - package contracts in the [package map](../packages/README.md)
-- [RFCs](rfc/README.md)
+- [RFCs](rfc/README.md)

docs/capability-seams.md

@@ -33,11 +33,15 @@ flowchart LR
   pkg_tool_ask_user["tool-ask-user"]
   pkg_tool_bash["tool-bash"]
   pkg_tool_cordis["tool-cordis"]
+  pkg_tool_skill["tool-skill"]
   pkg_tool_subagent["tool-subagent"]
   pkg_tool_todo["tool-todo"]
   pkg_user_interaction["user-interaction"]
   svc_userInteraction["ctx.userInteraction<br/>Human question/answer seam"]
   pkg_stdio_agent["stdio-agent"]
+  pkg_skill["skill"]
+  svc_skills["ctx.skills<br/>Skill provider registry"]
+  pkg_skill_local["skill-local"]
   svc_agents["ctx.agents<br/>Agent registry"]
   svc_agentLoop["ctx.agentLoop<br/>Concrete loop driver"]
   pkg_agent_core["agent-core"]
@@ -101,6 +105,8 @@ flowchart LR
   pkg_session_persistence --> svc_sessionPersistence
   pkg_session_persistence_jsonl --> svc_sessionPersistence
   pkg_session_persistence_sqlite --> svc_sessionPersistence
+  pkg_skill --> svc_skills
+  pkg_skill_local --> svc_skills
   pkg_stdio_agent --> svc_userInteraction
   pkg_subagent --> svc_subagents
   pkg_subagent_acp --> svc_subagents
@@ -141,6 +147,7 @@ flowchart LR
   svc_sessions --> pkg_invariants
   svc_sessions --> pkg_session_persistence
   svc_sessions --> pkg_subagent_inprocess
+  svc_skills --> pkg_tool_skill
   svc_subagents --> pkg_tool_subagent
   svc_systemPrompt --> pkg_agent_loop
   svc_systemPrompt --> pkg_tool_fs
@@ -152,6 +159,7 @@ flowchart LR
   svc_tools --> pkg_tool_bash
   svc_tools --> pkg_tool_cordis
   svc_tools --> pkg_tool_fs
+  svc_tools --> pkg_tool_skill
   svc_tools --> pkg_tool_subagent
   svc_tools --> pkg_tool_todo
   svc_tools --> pkg_tool_web
@@ -169,8 +177,9 @@ flowchart LR
 | `ctx.sessions` | `core` | [`session`](../packages/core/session) | - | [`agent-loop`](../packages/core/agent-loop), [`agent`](../packages/core/agent), [`session-persistence`](../packages/session-persistence/session-persistence), [`subagent-inprocess`](../packages/subagent/subagent-inprocess), [`invariants`](../packages/support/invariants) | - | Owns append-only Session instances and emits the durable session event feed. |
 | `ctx.sessionPersistence` | `seam` | [`session-persistence`](../packages/session-persistence/session-persistence) | [`session-persistence-jsonl`](../packages/session-persistence/session-persistence-jsonl), [`session-persistence-sqlite`](../packages/session-persistence/session-persistence-sqlite) | [`agent-loop`](../packages/core/agent-loop), [`acp`](../packages/ui/acp) | - | Backends persist the same SessionEvent vocabulary; apps choose a backend at composition time. |
 | `ctx.systemPrompt` | `core` | [`system-prompt`](../packages/core/system-prompt) | - | [`agent-loop`](../packages/core/agent-loop), [`tools`](../packages/core/tools), [`tool-fs`](../packages/fs/tool-fs), [`tool-web`](../packages/web/tool-web) | - | Collects prompt sections and model-facing tool schemas for each step. |
-| `ctx.tools` | `core` | [`tools`](../packages/core/tools) | - | [`agent-loop`](../packages/core/agent-loop), [`tool-ask-user`](../packages/ui/tool-ask-user), [`tool-bash`](../packages/bash/tool-bash), [`tool-cordis`](../packages/cordis/tool-cordis), [`tool-fs`](../packages/fs/tool-fs), [`tool-subagent`](../packages/subagent/tool-subagent), [`tool-todo`](../packages/todo/tool-todo), [`tool-web`](../packages/web/tool-web), [`acp`](../packages/ui/acp) | - | Registers tool definitions, exposes schemas to the prompt, and routes calls through tools/pre-execute and tools/post-execute. |
+| `ctx.tools` | `core` | [`tools`](../packages/core/tools) | - | [`agent-loop`](../packages/core/agent-loop), [`tool-ask-user`](../packages/ui/tool-ask-user), [`tool-bash`](../packages/bash/tool-bash), [`tool-cordis`](../packages/cordis/tool-cordis), [`tool-fs`](../packages/fs/tool-fs), [`tool-skill`](../packages/skill/tool-skill), [`tool-subagent`](../packages/subagent/tool-subagent), [`tool-todo`](../packages/todo/tool-todo), [`tool-web`](../packages/web/tool-web), [`acp`](../packages/ui/acp) | - | Registers tool definitions, exposes schemas to the prompt, and routes calls through tools/pre-execute and tools/post-execute. |
 | `ctx.userInteraction` | `seam` | [`user-interaction`](../packages/ui/user-interaction) | [`stdio-agent`](../packages/ui/stdio-agent), [`acp`](../packages/ui/acp) | [`tool-ask-user`](../packages/ui/tool-ask-user), [`stdio-agent`](../packages/ui/stdio-agent), [`acp`](../packages/ui/acp) | - | UI front doors provide the active human-answer provider; tool-ask-user pauses a tool call on the provider-neutral ask() promise. |
+| `ctx.skills` | `seam` | [`skill`](../packages/skill/skill) | [`skill-local`](../packages/skill/skill-local) | [`tool-skill`](../packages/skill/tool-skill) | - | Merges provider skill catalogs; tool-skill renders the session-prefix catalog and loads complete skill bodies. |
 | `ctx.agents` | `core` | [`agent`](../packages/core/agent) | - | [`agent-loop`](../packages/core/agent-loop), [`acp`](../packages/ui/acp), [`subagent-inprocess`](../packages/subagent/subagent-inprocess), [`stdio-agent`](../packages/ui/stdio-agent), [`invariants`](../packages/support/invariants) | - | Owns live Agent handles and the create/resume factory seam. |
 | `ctx.agentLoop` | `bundle` | [`agent-loop`](../packages/core/agent-loop) | - | [`agent-core`](../packages/core/agent-core) | - | The one concrete loop plugin; extension packages depend on dsh-agent events and services, not on this package. |
 | `ctx.bash` | `seam` | [`bash`](../packages/bash/bash) | [`bash-local`](../packages/bash/bash-local), [`bash-sandbox`](../packages/bash/bash-sandbox) | [`tool-bash`](../packages/bash/tool-bash), [`hooks-claude`](../packages/hooks/hooks-claude), [`hooks-codex`](../packages/hooks/hooks-codex) | - | The model-facing bash tools and hook bridges consume this seam; sandboxed or remote executors replace bash-local without touching them. |

docs/config-catalog.md

@@ -56,10 +56,12 @@ export interface Config {
   tools?: ToolsConfig
   /** Directory the JSONL session backend writes under. Defaults to `./.sessions`. */
   persistenceRoot?: string
+  /** Skill registry, local-provider, and model-facing consumer config forwarded to agent-core. */
+  skills?: agentCore.SkillConfig
 }
 ```
 
-Depends on: [`ToolsConfig`](#deepseek-aidsh-tools)
+Depends on: [`agentCore`](../packages/core/agent-core/src/index.ts) · [`ToolsConfig`](#deepseek-aidsh-tools)
 
 Source: [`packages/ui/acp-agent/src/index.ts:52`](../packages/ui/acp-agent/src/index.ts)
 
@@ -71,12 +73,12 @@ Source: [`packages/ui/acp-agent/src/index.ts:52`](../packages/ui/acp-agent/src/i
  * `agents` to the agent loop (an app that pre-creates no agents, like the ACP
  * bridge, simply omits it), `persona` and `toolOrder` to the system-prompt
  * plugin (the deployment's persona section and the explicit model-facing tool
- * order), the `tools` object to the tool registry (its presentation `mode`).
- * Every field is optional INPUT here because each owner's schema
- * supplies the default (`[]` / `''` / absent — lexicographic / `native`); the
- * schema is the INTERSECTION of the owners' own schemas (the registry's
- * nested under its `tools` key), so validation and defaulting can never
- * drift from them.
+ * order), the `tools` object to the tool registry (its presentation `mode`),
+ * and `skills` to the skill registry/local provider/tool consumer. Every field
+ * is optional INPUT here because each owner's schema supplies the default;
+ * the schema is the INTERSECTION of the owners' own schemas (with registry
+ * schemas nested under their bundle keys), so validation and defaulting can
+ * never drift from them.
  */
 export interface Config {
   /** The agent-loop `agents` list (see dsh-agent-loop's `Config`). */
@@ -87,12 +89,24 @@ export interface Config {
   toolOrder?: SystemPromptConfig['toolOrder']
   /** The tool registry's config — its presentation `mode` (see dsh-tools' `Config`). */
   tools?: ToolsConfig
+  /** Skill registry, local provider, and model-facing consumer config. */
+  skills?: SkillConfig
+}
+
+/** Skill bundle config forwarded to the registry, local provider, and model-facing consumer. */
+export interface SkillConfig {
+  /** Registry-level discovery cache settings. */
+  registry?: SkillRegistryConfig
+  /** Local filesystem skill provider settings. */
+  local?: SkillLocal.Config
+  /** Model-facing skill catalog and tool settings. */
+  tool?: toolSkill.Config
 }
 ```
 
-Depends on: [`AgentLoopConfig`](#deepseek-aidsh-agent-loop) · [`SystemPromptConfig`](#deepseek-aidsh-system-prompt) · [`ToolsConfig`](#deepseek-aidsh-tools)
+Depends on: [`AgentLoopConfig`](#deepseek-aidsh-agent-loop) · [`SkillLocal`](../packages/skill/skill-local/src/index.ts) · [`SkillRegistryConfig`](#deepseek-aidsh-skill) · [`SystemPromptConfig`](#deepseek-aidsh-system-prompt) · [`ToolsConfig`](#deepseek-aidsh-tools) · [`toolSkill`](../packages/skill/tool-skill/src/index.ts)
 
-Source: [`packages/core/agent-core/src/index.ts:71`](../packages/core/agent-core/src/index.ts)
+Source: [`packages/core/agent-core/src/index.ts:87`](../packages/core/agent-core/src/index.ts)
 
 ## `@deepseek-ai/dsh-agent-loop`
 
@@ -108,6 +122,8 @@ export interface Config {
   agents: (AgentOptions & {
     /** Agent id to register under; also seeds the fresh per-run session id (`${id}-session-<uuid>`). */
     id: AgentId
+    /** Optional workspace cwd for the config-created fresh session. */
+    cwd?: string
     /**
      * If set, the config agent RESUMES this persisted session id instead of
      * starting a fresh `${id}-session-<uuid>`. Sourced from an env var in
@@ -557,6 +573,36 @@ export type JournalMode = 'wal' | 'delete' | 'truncate' | 'persist'
 
 Source: [`packages/session-persistence/session-persistence-sqlite/src/index.ts:50`](../packages/session-persistence/session-persistence-sqlite/src/index.ts)
 
+## `@deepseek-ai/dsh-skill`
+
+```ts config-catalog
+/** Skill registry configuration. */
+export interface Config {
+  /** Maximum number of completed cwd/provider catalog snapshots kept in memory. */
+  collectCacheMaxEntries?: number
+}
+```
+
+Source: [`packages/skill/skill/src/index.ts:112`](../packages/skill/skill/src/index.ts)
+
+## `@deepseek-ai/dsh-skill-local`
+
+Requires: `skills`
+
+```ts config-catalog
+/** Local filesystem skill provider configuration. */
+export interface Config {
+  /** DeepSeek Harness config root. Defaults to `$DSH_HOME` or `~/.dsh`. */
+  dshHome?: string
+  /** Shared agent config root. Defaults to `$DSH_AGENTS_HOME` or `~/.agents`. */
+  agentsHome?: string
+  /** Additional skill roots scanned after project roots and before user roots. */
+  customSkillDirs?: string[]
+}
+```
+
+Source: [`packages/skill/skill-local/src/index.ts:39`](../packages/skill/skill-local/src/index.ts)
+
 ## `@deepseek-ai/dsh-stdio-agent`
 
 ```ts config-catalog
@@ -566,7 +612,9 @@ Source: [`packages/session-persistence/session-persistence-sqlite/src/index.ts:5
  * {@link @deepseek-ai/dsh-agent-core}'s forwarded `agents` list); `persona` is
  * the deployment persona (forwarded to the system-prompt plugin); `toolOrder`
  * is the explicit model-facing tool order (forwarded to the system-prompt plugin);
- * `persistenceRoot` is the JSONL backend's directory; `welcome` is the UI banner.
+ * fresh sessions use `process.cwd()` as their workspace cwd; resumed sessions
+ * keep their persisted cwd. `persistenceRoot` is the JSONL backend's directory;
+ * `welcome` is the UI banner.
  */
 export interface Config {
   /** Model name for the `main` agent (must have a registered adapter). */
@@ -581,6 +629,8 @@ export interface Config {
   persistenceRoot?: string
   /** stdin-chat banner printed once on start. Defaults to `'ready.'`. */
   welcome?: string
+  /** Skill registry, local-provider, and model-facing consumer config forwarded to agent-core. */
+  skills?: agentCore.SkillConfig
   /**
    * If set, the `main` agent RESUMES this persisted session id instead of
    * starting fresh. Sourced from an env var in the leaf `cordis.yml`
@@ -590,9 +640,9 @@ export interface Config {
 }
 ```
 
-Depends on: [`ToolsConfig`](#deepseek-aidsh-tools)
+Depends on: [`agentCore`](../packages/core/agent-core/src/index.ts) · [`ToolsConfig`](#deepseek-aidsh-tools)
 
-Source: [`packages/ui/stdio-agent/src/index.ts:63`](../packages/ui/stdio-agent/src/index.ts)
+Source: [`packages/ui/stdio-agent/src/index.ts:65`](../packages/ui/stdio-agent/src/index.ts)
 
 ## `@deepseek-ai/dsh-subagent-acp`
 
@@ -795,6 +845,20 @@ export interface Config {
 
 Source: [`packages/fs/tool-fs/src/index.ts:48`](../packages/fs/tool-fs/src/index.ts)
 
+## `@deepseek-ai/dsh-tool-skill`
+
+Requires: `tools` · `skills`
+
+```ts config-catalog
+/** Model-facing skill catalog configuration. */
+export interface Config {
+  /** Maximum normalized description length rendered in the session catalog; minimum 3. */
+  catalogDescriptionMaxLength?: number
+}
+```
+
+Source: [`packages/skill/tool-skill/src/index.ts:19`](../packages/skill/tool-skill/src/index.ts)
+
 ## `@deepseek-ai/dsh-tool-subagent`
 
 Requires: `tools` · `subagents`

docs/cordis-catalog/events.md

@@ -263,6 +263,28 @@ Awaited durability checkpoint. The agent loop awaits `ctx.parallel('session/flus
 
 Source: [`packages/core/session/src/index.ts:57`](../../packages/core/session/src/index.ts)
 
+## `skill/*`
+
+### `skill/provider-added` — emit
+
+A skill provider became resolvable in the `ctx.skills` registry. Consumers can observe this instead of depending on Cordis plugin load order, which is concurrent for sibling plugins.
+
+```ts cordis-catalog
+'skill/provider-added'(provider: SkillProvider): void
+```
+
+Source: [`packages/skill/skill/src/index.ts:130`](../../packages/skill/skill/src/index.ts)
+
+### `skill/provider-removed` — emit
+
+A skill provider left the registry because its plugin fiber was disposed.
+
+```ts cordis-catalog
+'skill/provider-removed'(name: string): void
+```
+
+Source: [`packages/skill/skill/src/index.ts:136`](../../packages/skill/skill/src/index.ts)
+
 ## `subagent/*`
 
 ### `subagent/end` — emit

docs/cordis-catalog/services.md

@@ -16,12 +16,12 @@ The agent-loop plugin (`ctx.agentLoop`): creates ReactLoopAgents, runs their loo
 The loop itself is deliberately thin — every behavior beyond "call the model, run the tools, repeat" belongs to plugins listening on the event taxonomy declared in @deepseek-ai/dsh-agent.
 
 ```ts cordis-catalog
-create(id: AgentId, options: AgentOptions = {}): ReactLoopAgent
+create(id: AgentId, options: AgentOptions = {}, meta: Pick<SessionHeader, 'cwd'> = {}): ReactLoopAgent
 createAgent(options: CreateAgentOptions): AgentHandle
 async resume(options: ResumeAgentOptions): Promise<AgentHandle>
 ```
 
-Source: [`packages/core/agent-loop/src/index.ts:68`](../../packages/core/agent-loop/src/index.ts)
+Source: [`packages/core/agent-loop/src/index.ts:70`](../../packages/core/agent-loop/src/index.ts)
 
 ## `ctx.agents` — `AgentRegistry`
 
@@ -219,6 +219,19 @@ fork(source: SessionForkSource, boundary?: number, childSessionId?: SessionId):
 
 Source: [`packages/core/session/src/index.ts:405`](../../packages/core/session/src/index.ts)
 
+## `ctx.skills` — `SkillService`
+
+Registry of skill providers. It merges provider catalogs with stable first-wins duplicate handling, exposes sorted model-visible summaries, and loads full skill bodies on demand.
+
+```ts cordis-catalog
+registerProvider(provider: SkillProvider): () => void
+register(skill: SkillRegistration): () => void
+async list(options: SkillLookupOptions = {}): Promise<SkillSummary[]>
+async get(name: string, options: SkillLookupOptions = {}): Promise<SkillDefinition | undefined>
+```
+
+Source: [`packages/skill/skill/src/index.ts:157`](../../packages/skill/skill/src/index.ts)
+
 ## `ctx.subagents` — `SubagentService`
 
 The `subagents` service: a registry of named SubagentProviders and a capability-checked start surface.

docs/core-data-structures/core.md

@@ -25,6 +25,7 @@ Everything else is documented on a **sub-page**, not here. The rule that draws t
 | [sandbox.md](sandbox.md) | the process-confinement seam: file-effect modes, `SandboxPolicy`, `ConfinedArgv`, enforcement and fail-closed errors |
 | [code-runtime.md](code-runtime.md) | the code-execution seam: `CodeRunRequest`/`Result`, binding namespaces, captured logs, the `CodeRunFailure` taxonomy |
 | [filesystem.md](filesystem.md) | the filesystem seam: `FsTarget`, read/write/edit outcomes, observed-file state, `FsErrorCode` |
+| [skills.md](skills.md) | the skill service: discovery priority, `SkillSummary`/`SkillDefinition`, session-prefix catalog, model-facing `skill` loading |
 | [compaction.md](compaction.md) | the compaction seam: the `compact/*` session events, `CompactionResult`, the `CompactService` interface |
 | [subagent.md](subagent.md) | the subagent seam: the named-provider registry, `SubagentStartRequest`/`Result`/`Run`, the start-time-vs-runtime capability split |
 | [web.md](web.md) | the web access seam: `WebSearchRequest`/`Result`, `WebFetchRequest`/`Result`, `WebFetchBody`, provider/capability status, `WebError` |

docs/core-data-structures/skills.md

@@ -0,0 +1,116 @@
+# Skills
+
+The [skill capability family](../../packages/skill) is split across three packages: the registry ([dsh-skill](../../packages/skill/skill), `ctx.skills`) merges provider catalogs; the local provider ([dsh-skill-local](../../packages/skill/skill-local)) scans project/custom/user directories; the consumer ([dsh-tool-skill](../../packages/skill/tool-skill)) owns the session-prefix catalog and model-facing `skill` tool. Skills are optional instructions, not session events, so their vocabulary lives here rather than in [core.md](core.md).
+
+Source: [`packages/skill/skill/src/index.ts`](../../packages/skill/skill/src/index.ts), [`packages/skill/skill-local/src/index.ts`](../../packages/skill/skill-local/src/index.ts), and [`packages/skill/tool-skill/src/index.ts`](../../packages/skill/tool-skill/src/index.ts).
+
+## Provider registry
+
+`ctx.skills` is a multi-provider registry. Providers can represent local directories, embedded plugin data, HTTP catalogs, or another source. Provider plugins register synchronously during `apply()`; remote initialization, authentication, and discovery are awaited by `list()`. The registry validates candidates, resolves duplicate skill names first-wins by rank/provider order/local order, and sorts the final summaries by `name` for deterministic consumers. A provider `list()` rejection is logged and skipped without caching the degraded catalog; malformed candidates still fail fast because they violate the provider contract.
+
+```ts type-equiv
+interface SkillProvider {
+  name: string
+  list(options: SkillLookupOptions): Promise<SkillCandidate[]>
+  get(candidate: SkillCandidate, options: SkillLookupOptions): Promise<SkillDefinition | undefined>
+}
+```
+
+## Local discovery priority
+
+The shipped local provider scans roots in rank order:
+
+| Rank | Source | Root |
+|---|---|---|
+| 100 | `project-dsh` | `<projectRoot>/.dsh/skills` |
+| 200 | `project-agents` | `<projectRoot>/.agents/skills` |
+| 300 | `custom` | `Config.customSkillDirs` |
+| 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. When `ctx.fs` is available, the git-root walk probes `.git` through the filesystem service so remote or sandboxed workspaces do not fall back to the host filesystem boundary. The user DSH root skips its `.system` child, and DeepSeek Harness no longer ships built-in system skills from the local provider. Additional built-ins can be supplied later by another provider.
+
+## Skill identity
+
+Skill names are kebab-case (`^[a-z0-9]+(?:-[a-z0-9]+)*$`). The local provider accepts directory bundles (`<name>/SKILL.md`) and flat Markdown files (`<name>.md`). Nested recursive `**/SKILL.md` discovery is intentionally outside v1.
+
+```ts type-equiv
+type SkillSource = 'project-dsh' | 'project-agents' | 'runtime' | 'user-dsh' | 'user-agents' | 'custom' | (string & {})
+```
+
+## Summaries, candidates, and complete definitions
+
+`SkillSummary` is the registry's model-invocable summary shape. Consumers choose which fields to render; the session catalog uses only `name` and `description`, never the body or absolute file path. `disableModelInvocation` hides a skill from model listings while allowing trusted code to load it by name.
+
+```ts type-equiv
+interface SkillSummary {
+  name: string
+  description: string
+  whenToUse?: string
+  disableModelInvocation?: boolean
+  source: SkillSource
+  provider: string
+  resourceBase?: SkillResourceBase
+}
+```
+
+`SkillCandidate` is the provider-to-registry shape. `locator` is opaque provider state; the registry only stores it and gives it back to the winning provider's `get()`.
+
+```ts type-equiv
+interface SkillCandidate extends SkillSummary {
+  rank: number
+  locator: unknown
+  path?: string
+  metadata?: Record<string, unknown>
+}
+```
+
+`SkillDefinition` is the complete parsed result returned by `ctx.skills.get()` and used by the `skill` tool. `resourceBase` tells the tool how to render relative-resource guidance for local, URL, or provider-managed skills.
+
+```ts type-equiv
+type SkillResourceBase =
+  | { kind: 'directory'; path: string }
+  | { kind: 'url'; url: string }
+  | { kind: 'opaque'; description: string }
+```
+
+```ts type-equiv
+interface SkillDefinition extends SkillSummary {
+  content: string
+  path?: string
+  metadata?: Record<string, unknown>
+}
+```
+
+Runtime skills use the same complete shape and participate in the same first-wins collection order. The returned disposer removes the contribution and invalidates discovery caches.
+
+```ts type-equiv
+type SkillRegistration = Omit<SkillDefinition, 'provider'> & {
+  provider?: string
+}
+```
+
+## Lookup and configuration
+
+Skill lookup is cwd-sensitive because providers may expose workspace-local skills, and its optional signal cancels provider work for the caller. If no git root is found, the local provider treats the supplied cwd itself as the project root.
+
+```ts type-equiv
+interface SkillLookupOptions {
+  cwd?: string | undefined
+  signal?: AbortSignal | undefined
+}
+```
+
+The registry owns only its discovery-cache bound. The local provider owns filesystem roots (`dshHome`, `agentsHome`, and `customSkillDirs`). The consumer owns its catalog description bound.
+
+```ts type-equiv
+interface Config {
+  collectCacheMaxEntries?: number
+}
+```
+
+## Session catalog and tool contract
+
+`dsh-tool-skill` contributes a user-role `<system-reminder>` through `agent/session-prefix`. The catalog contains sorted skill `name` and normalized, XML-escaped `description` only; it omits bodies, paths, sources, providers, and routing hints. Prefix discovery forwards the caller's abort signal through `SkillLookupOptions`. `catalogDescriptionMaxLength` is the consumer config for the description bound, with default `500` and integer minimum `3`. Its request-only, header-logged lifecycle is defined by the [session-prefix RFC](../rfc/implemented/feature/2026-07-07-session-prefix.md).
+
+The model-facing `skill({ name })` tool validates the kebab-case name, loads the complete definition for the calling agent cwd, reports an unresolved skill as unknown or no longer available, rejects `disableModelInvocation` skills, and returns a tool result containing `<skill_content name="...">`, `<skill_resources>`, and `<skill_instructions>`. `resourceBase` resolves explicitly referenced scripts, references, and assets only as needed; the loaded result does not enumerate a skill directory. The tool result is the model-visible path for complete instructions.

docs/event-producer-consumer.md

@@ -14,7 +14,7 @@ This matrix shows which packages dispatch each harness-owned event and which pac
 | `agent/prompt-submit` | `waterfall` | [`packages/core/agent/src/types.ts:370`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`waterfall`) | [`acp`](../packages/ui/acp), [`hooks-claude`](../packages/hooks/hooks-claude), [`hooks-codex`](../packages/hooks/hooks-codex), [`repeat-tool-guard`](../packages/guard/repeat-tool-guard) |
 | `agent/queued` | `emit` | [`packages/core/agent/src/types.ts:290`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | - |
 | `agent/request` | `waterfall` | [`packages/core/agent/src/types.ts:394`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`waterfall`) | - |
-| `agent/session-prefix` | `waterfall` | [`packages/core/agent/src/types.ts:441`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`waterfall`) | - |
+| `agent/session-prefix` | `waterfall` | [`packages/core/agent/src/types.ts:441`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`waterfall`) | [`tool-skill`](../packages/skill/tool-skill) |
 | `agent/session-start` | `emit` | [`packages/core/agent/src/types.ts:305`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | [`hooks-claude`](../packages/hooks/hooks-claude), [`hooks-codex`](../packages/hooks/hooks-codex) |
 | `agent/status` | `emit` | [`packages/core/agent/src/types.ts:281`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | [`acp`](../packages/ui/acp), [`invariants`](../packages/support/invariants), [`repeat-tool-guard`](../packages/guard/repeat-tool-guard), [`stdio-agent`](../packages/ui/stdio-agent) |
 | `agent/step-result` | `waterfall` | [`packages/core/agent/src/types.ts:451`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`waterfall`) | - |
@@ -27,6 +27,8 @@ This matrix shows which packages dispatch each harness-owned event and which pac
 | `session/created` | `emit` | [`packages/core/session/src/index.ts:39`](../packages/core/session/src/index.ts) | [`session`](../packages/core/session) (`emit`) | [`invariants`](../packages/support/invariants), [`session-persistence`](../packages/session-persistence/session-persistence) |
 | `session/event` | `emit` | [`packages/core/session/src/index.ts:47`](../packages/core/session/src/index.ts) | [`session`](../packages/core/session) (`emit`) | [`acp`](../packages/ui/acp), [`invariants`](../packages/support/invariants), [`session-persistence`](../packages/session-persistence/session-persistence), [`stdio-agent`](../packages/ui/stdio-agent) |
 | `session/flush` | `parallel` | [`packages/core/session/src/index.ts:57`](../packages/core/session/src/index.ts) | [`agent-loop`](../packages/core/agent-loop) (`parallel`) | [`session-persistence`](../packages/session-persistence/session-persistence) |
+| `skill/provider-added` | `emit` | [`packages/skill/skill/src/index.ts:130`](../packages/skill/skill/src/index.ts) | [`skill`](../packages/skill/skill) (`emit`) | - |
+| `skill/provider-removed` | `emit` | [`packages/skill/skill/src/index.ts:136`](../packages/skill/skill/src/index.ts) | [`skill`](../packages/skill/skill) (`emit`) | - |
 | `subagent/end` | `emit` | [`packages/subagent/subagent/src/index.ts:98`](../packages/subagent/subagent/src/index.ts) | [`subagent`](../packages/subagent/subagent) (`events.dispatch`) | [`hooks-claude`](../packages/hooks/hooks-claude) |
 | `subagent/provider-added` | `emit` | [`packages/subagent/subagent/src/index.ts:72`](../packages/subagent/subagent/src/index.ts) | [`subagent`](../packages/subagent/subagent) (`emit`) | [`tool-subagent`](../packages/subagent/tool-subagent) |
 | `subagent/provider-removed` | `emit` | [`packages/subagent/subagent/src/index.ts:83`](../packages/subagent/subagent/src/index.ts) | - | [`tool-subagent`](../packages/subagent/tool-subagent) |

docs/module-graph.md

@@ -36,6 +36,11 @@ flowchart TD
     pkg_fs_policy["fs-policy"]
     pkg_tool_fs["tool-fs"]
   end
+  subgraph group_skill["packages/skill"]
+    pkg_skill["skill"]
+    pkg_skill_local["skill-local"]
+    pkg_tool_skill["tool-skill"]
+  end
   subgraph group_compact["packages/compact"]
     pkg_compact["compact"]
     pkg_compact_basic["compact-basic"]
@@ -127,6 +132,8 @@ flowchart TD
   pkg_bash --> pkg_session
   pkg_fs_local --> pkg_fs
   pkg_fs_policy --> pkg_fs
+  pkg_skill_local --> pkg_fs
+  pkg_skill_local --> pkg_skill
   pkg_compact --> pkg_llm
   pkg_compact --> pkg_session
   pkg_web_fetch_local --> pkg_timeout
@@ -191,6 +198,10 @@ flowchart TD
   pkg_tool_fs --> pkg_session
   pkg_tool_fs --> pkg_system_prompt
   pkg_tool_fs --> pkg_tools
+  pkg_tool_skill --> pkg_agent
+  pkg_tool_skill --> pkg_llm
+  pkg_tool_skill --> pkg_skill
+  pkg_tool_skill --> pkg_tools
   pkg_subagent --> pkg_agent
   pkg_subagent --> pkg_llm
   pkg_subagent --> pkg_tools
@@ -234,8 +245,11 @@ flowchart TD
   pkg_agent_core --> pkg_invariants
   pkg_agent_core --> pkg_llm
   pkg_agent_core --> pkg_session
+  pkg_agent_core --> pkg_skill
+  pkg_agent_core --> pkg_skill_local
   pkg_agent_core --> pkg_system_prompt
   pkg_agent_core --> pkg_tool_bash
+  pkg_agent_core --> pkg_tool_skill
   pkg_agent_core --> pkg_tools
   pkg_subagent_acp --> pkg_agent
   pkg_subagent_acp --> pkg_llm
@@ -293,6 +307,7 @@ flowchart TD
 | --- | --- | --- |
 | [`brand`](../packages/util/brand) | `util` | — |
 | [`timeout`](../packages/util/timeout) | `util` | — |
+| [`skill`](../packages/skill/skill) | `skill` | — |
 | [`subagent-subprocess`](../packages/subagent/subagent-subprocess) | `subagent` | — |
 | [`acp-snapshot`](../packages/support/acp-snapshot) | `support` | — |
 | [`app-boot`](../packages/ui/app-boot) | `ui` | — |
@@ -310,6 +325,7 @@ flowchart TD
 | [`bash`](../packages/bash/bash) | `bash` | [`brand`](../packages/util/brand), [`sandbox`](../packages/sandbox/sandbox), [`session`](../packages/core/session) |
 | [`fs-local`](../packages/fs/fs-local) | `fs` | [`fs`](../packages/fs/fs) |
 | [`fs-policy`](../packages/fs/fs-policy) | `fs` | [`fs`](../packages/fs/fs) |
+| [`skill-local`](../packages/skill/skill-local) | `skill` | [`fs`](../packages/fs/fs), [`skill`](../packages/skill/skill) |
 | [`compact`](../packages/compact/compact) | `compact` | [`llm`](../packages/llm/llm), [`session`](../packages/core/session) |
 | [`web-fetch-local`](../packages/web/web-fetch-local) | `web` | [`timeout`](../packages/util/timeout), [`web`](../packages/web/web) |
 | [`web-search-deepseek`](../packages/web/web-search-deepseek) | `web` | [`web`](../packages/web/web) |
@@ -332,6 +348,7 @@ flowchart TD
 | [`agent-loop`](../packages/core/agent-loop) | `core` | [`agent`](../packages/core/agent), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-persistence`](../packages/session-persistence/session-persistence), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools) |
 | [`tool-bash`](../packages/bash/tool-bash) | `bash` | [`agent`](../packages/core/agent), [`bash`](../packages/bash/bash), [`llm`](../packages/llm/llm), [`sandbox`](../packages/sandbox/sandbox), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools), [`user-approval`](../packages/ui/user-approval) |
 | [`tool-fs`](../packages/fs/tool-fs) | `fs` | [`fs`](../packages/fs/fs), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools) |
+| [`tool-skill`](../packages/skill/tool-skill) | `skill` | [`agent`](../packages/core/agent), [`llm`](../packages/llm/llm), [`skill`](../packages/skill/skill), [`tools`](../packages/core/tools) |
 | [`subagent`](../packages/subagent/subagent) | `subagent` | [`agent`](../packages/core/agent), [`llm`](../packages/llm/llm), [`tools`](../packages/core/tools) |
 | [`tool-web`](../packages/web/tool-web) | `web` | [`llm`](../packages/llm/llm), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools), [`web`](../packages/web/web) |
 | [`timeout-policy`](../packages/timeout/timeout-policy) | `timeout` | [`llm`](../packages/llm/llm), [`timeout`](../packages/util/timeout), [`tools`](../packages/core/tools) |
@@ -342,7 +359,7 @@ flowchart TD
 | [`tool-ask-user`](../packages/ui/tool-ask-user) | `ui` | [`agent`](../packages/core/agent), [`tools`](../packages/core/tools), [`user-interaction`](../packages/ui/user-interaction) |
 | [`repeat-tool-guard`](../packages/guard/repeat-tool-guard) | `guard` | [`agent`](../packages/core/agent), [`tools`](../packages/core/tools) |
 | [`tool-workflow`](../packages/workflow/tool-workflow) | `workflow` | [`agent`](../packages/core/agent), [`llm`](../packages/llm/llm), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools), [`workflow`](../packages/workflow/workflow) |
-| [`agent-core`](../packages/core/agent-core) | `core` | [`agent`](../packages/core/agent), [`agent-loop`](../packages/core/agent-loop), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`system-prompt`](../packages/core/system-prompt), [`tool-bash`](../packages/bash/tool-bash), [`tools`](../packages/core/tools) |
+| [`agent-core`](../packages/core/agent-core) | `core` | [`agent`](../packages/core/agent), [`agent-loop`](../packages/core/agent-loop), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`skill`](../packages/skill/skill), [`skill-local`](../packages/skill/skill-local), [`system-prompt`](../packages/core/system-prompt), [`tool-bash`](../packages/bash/tool-bash), [`tool-skill`](../packages/skill/tool-skill), [`tools`](../packages/core/tools) |
 | [`subagent-acp`](../packages/subagent/subagent-acp) | `subagent` | [`agent`](../packages/core/agent), [`llm`](../packages/llm/llm), [`subagent`](../packages/subagent/subagent), [`subagent-subprocess`](../packages/subagent/subagent-subprocess) |
 | [`subagent-inprocess`](../packages/subagent/subagent-inprocess) | `subagent` | [`agent`](../packages/core/agent), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools) |
 | [`tool-subagent`](../packages/subagent/tool-subagent) | `subagent` | [`agent`](../packages/core/agent), [`llm`](../packages/llm/llm), [`subagent`](../packages/subagent/subagent), [`tools`](../packages/core/tools) |

docs/rfc/INDEX.md

@@ -63,6 +63,7 @@ Generated by `pnpm run gen-rfc-index` from the RFC tree — never edit by hand;
 | [SessionStore fork API](implemented/feature/2026-06-30-session-store-fork-api.md) | 2026-06-30 |
 | [Subagent lifecycle enrichment — lastAssistantMessage (observe-only)](implemented/feature/2026-06-30-subagent-observe-enrich.md) | 2026-06-30 |
 | [Dynamic workflows — a script-driven multi-agent orchestration seam](implemented/feature/2026-07-05-dynamic-workflows.md) | 2026-07-05 |
+| [Skill system — progressive disclosure instructions for agents](implemented/feature/2026-07-05-skill-system.md) | 2026-07-05 |
 | [The approval seam — one-shot permission decisions over a waterfall of answerers](implemented/feature/2026-07-06-approval-seam.md) | 2026-07-06 |
 | [Explicit model-facing tool order](implemented/feature/2026-07-06-explicit-tool-order.md) | 2026-07-06 |
 | [The subprocess sandbox — confinement seam, native runners, escalation, and per-session modes](implemented/feature/2026-07-06-sandbox.md) | 2026-07-06 |

docs/rfc/implemented/feature/2026-07-05-skill-system.md

@@ -0,0 +1,53 @@
+# RFC: Skill system — progressive disclosure instructions for agents
+
+Status: implemented
+
+## Problem
+
+Agent products have converged on a skill pattern: keep the request prompt small by listing only available instruction bundles, then load the full body when the model decides a task matches. Codex, Claude Code, OpenCode, and Kimi Code differ in details, but all separate discovery metadata from complete instructions so a workspace can carry reusable behavior without paying the full prompt cost on every turn.
+
+DeepSeek Harness uses the same primitive so project-specific review, plugin-authoring, and tool-usage guidance lives next to the workspace or the user's agent configuration instead of being hard-coded into the loop.
+
+## Decision
+
+`@deepseek-ai/dsh-skill` is the pure provider registry (`ctx.skills`), `@deepseek-ai/dsh-skill-local` is the shipped local filesystem provider, and `@deepseek-ai/dsh-tool-skill` owns the session-prefix catalog and model-facing loader tool. `dsh-agent-core` loads the registry, local provider, and consumer by default so stdio and ACP apps get the same behavior while embedded or remote providers contribute skills without changing the registry or consumer. Its `skills` config forwards `registry`, `local`, and `tool` branches to those owners.
+
+Provider plugins register synchronously during `apply()`. Provider catalogs return ranked candidates from awaited `list()` calls, where remote providers perform initialization, authentication, and discovery while honoring the lookup abort signal. The registry validates each candidate, resolves same-name skills first-wins by rank, provider registration order, and provider-local order, then sorts summaries by skill name for deterministic consumers. It caches only completed catalog snapshots and retries when a provider/runtime revision changes during discovery, so an unload cannot freeze a stale, unresolvable skill into a session prefix. Runtime `ctx.skills.register(...)` remains a convenience for embedded in-process skills and uses project-over-user priority; `runtime` is reserved as the registry-owned provider name.
+
+The local provider scans cwd-sensitive project roots, custom roots, and user roots in first-wins rank order: project `.dsh`, project `.agents`, `customSkillDirs`, user `.dsh`, then user `.agents`. The user `.dsh/skills` scan skips `.system` so a system-owned directory is not treated as normal user content. DeepSeek Harness does not ship built-in system skills; embedded or remote providers supply additional skills when configured.
+
+Each skill is either `<name>/SKILL.md` or `<name>.md` with YAML frontmatter. `name` and `description` are required; `whenToUse`, `disableModelInvocation`, and `metadata` are optional. Names are kebab-case. YAML frontmatter is parsed with the `yaml` package instead of `js-yaml` or a hand-written parser: `yaml` is the already-declared modern parser for this package's limited frontmatter needs, and a narrow parser would either reject valid YAML users expect to work or grow into an unreviewed YAML subset.
+
+Local skill filesystem I/O goes through `ctx.fs` when a filesystem service is loaded: project-root lookup probes `.git` with `resolve` and `stat`, root discovery uses `listDir`, and skill reads use `readText`. The Node filesystem remains a fallback for minimal contexts that mount `dsh-skill-local` without the fs seam. Missing roots, unreadable or malformed skill files, and transient provider `list()` failures degrade to warn-and-skip so one bad source does not make every agent request fail; malformed candidates still fail fast because they are provider contract violations.
+
+`dsh-tool-skill` contributes one user-role `<system-reminder>` catalog through [`agent/session-prefix`](2026-07-07-session-prefix.md). The catalog contains sorted skill name and description only; it excludes bodies, paths, sources, providers, and routing hints. Descriptions are whitespace-normalized, XML-escaped, and capped by `catalogDescriptionMaxLength`, whose default is `500` and minimum is `3`. The session-prefix seam freezes the request-only catalog per loop instance and records it in the request header, preserving reconstructability without adding it to durable history. Full skill bodies are never included in the catalog.
+
+The `skill({ name })` tool loads one full skill for the current agent cwd and returns a tool result containing `<skill_content name="...">`, `<skill_resources>`, and `<skill_instructions>`. `resourceBase` supplies a directory, URL, or opaque provider-managed base for explicitly referenced scripts, references, and assets; resources load only as needed, without directory enumeration. An unresolved name reports that the skill is unknown or no longer available; invalid names and skills marked `disableModelInvocation` retain distinct tool errors. The tool result is the model-visible disclosure path.
+
+The data structures and catalog/tool contract are documented in [skills.md](../../../core-data-structures/skills.md), with service signatures in the generated [services catalog](../../../cordis-catalog/services.md).
+
+## Alternatives considered
+
+**Inject full skill bodies into every system prompt.** Rejected because it destroys progressive disclosure and makes every request pay for instructions that may not apply.
+
+**Expose skills only as slash commands.** Rejected because model-initiated loading is the core capability; slash/ACP command advertisement does not change discovery.
+
+**Put local filesystem scanning directly inside `ctx.skills`.** Rejected because coding agents, web agents, and future plugin ecosystems need different skill sources. A provider registry mirrors the subagent seam: the registry owns conflict resolution and consumers, while implementations own loading.
+
+**Use a system-prompt section.** Rejected because the rendered system prompt is a single string, while the catalog is a user-role `<system-reminder>` message with request-only lifecycle requirements. [`agent/session-prefix`](2026-07-07-session-prefix.md) is the selected mechanism: it places the catalog ahead of derived history and records the composed message in the request header.
+
+**Materialize built-in DSH authoring skills under `~/.dsh/skills/.system`.** Rejected because bundled skills do not write user home on startup, and embedded or remote providers supply configured skills.
+
+**Recursively discover nested `**/SKILL.md`.** Rejected. Flat files and one-level directory bundles cover the configured roots while keeping duplicate handling and catalog order easy to reason about.
+
+**Hand-parse frontmatter.** Rejected because the accepted schema includes an open `metadata` object. A narrow parser would either reject valid YAML users expect to work or grow into an unreviewed YAML subset.
+
+## Consequences
+
+The agent-core spine includes one session-prefix contributor, one local provider, and one model-facing tool. Skill discovery is cwd-sensitive, so callers that create agents with different session cwd values can observe different project skill overrides by design.
+
+The catalog is deterministic for a fixed root set and runtime registration revision, but disk changes are not watched; discovery is memoized until runtime registration invalidates the cache or the process restarts.
+
+## Deferred
+
+Forked skill contexts (`context: fork`), direct user/slash invocation (`user-invocable`), parameter declarations and hints (`arguments` and `argument-hint`), and per-skill tool constraints (`allowed-tools` and `disallowed-tools`) are outside the shipped contract. The registry, local provider, and model-facing tool do not parse, advertise, or enforce these fields.

docs/tool-catalog.md

@@ -20,6 +20,7 @@ This table connects model-visible tool names to the plugin package and service s
 | `@deepseek-ai/dsh-tool-bash` | `bash`, `bash_kill`, `bash_output` | `ctx.tools`, `ctx.bash` | `tool/call`, `tool/result`, `context/message via agent.inject() for background completion notices` | - | The bash/bash_output/bash_kill tools are model-facing consumers of the bash executor seam. |
 | `@deepseek-ai/dsh-tool-cordis` | `cordis_inspect`, `cordis_mount`, `cordis_unmount` | `ctx.tools` | `tool/call`, `tool/result`, `live plugin-tree mutations (mount/unmount)` | - | Ships in examples/cordis-agent only (a deliberate opt-in — mounted code gets the real ctx, see docs/rfc/implemented/feature/2026-07-08-self-referential-cordis-toolset.md). Plugins the model mounts may register ADDITIONAL model-visible tools at runtime; the request-header ToolsDelta logs those tool-set changes. |
 | `@deepseek-ai/dsh-tool-fs` | `edit`, `read`, `write` | `ctx.tools`, `ctx.fs`, `ctx.systemPrompt` | `tool/call`, `fs/write-intent or fs/edit-intent for mutations`, `fs/observed after successful file operations`, `tool/result` | - | The read-before-write/edit policy is added by `@deepseek-ai/dsh-fs-policy` (an `fs/*` event-gate plugin, no schema change); a deployment that loads these tools is expected to also load it. The tool schemas above are identical with or without the policy plugin. |
+| `@deepseek-ai/dsh-tool-skill` | `skill` | `ctx.tools`, `ctx.skills` | `tool/call`, `tool/result` | - | - |
 | `@deepseek-ai/dsh-tool-subagent` | `subagent` | `ctx.tools`, `ctx.subagents` | `tool/call`, `tool/result`, `child session events through the chosen provider` | `subagent`, `subagent_fork` | The registered tool name is the load-time `toolName` config (default `subagent`); the schema above is that default. The shipped example agents load this package once per subagent backend, so the model additionally sees `subagent_fork` (bound to the fork backend) with an identical schema — see `examples/coding-agent/cordis.yml` and `examples/acp-agent/cordis.yml`. |
 | `@deepseek-ai/dsh-tool-todo` | `todo_write` | `ctx.tools`, `owning Agent session` | `tool/call`, `todo/write`, `tool/result` | - | todo_write is session-owned state; UIs render the latest todo/write event as a checklist or ACP plan. |
 | `@deepseek-ai/dsh-tool-workflow` | `workflow` | `ctx.tools`, `ctx.workflows`, `ctx.systemPrompt`, `a calling Agent (exec.agent parents the script children)` | `tool/call`, `tool/result` | - | - |
@@ -370,6 +371,29 @@ Source: [`packages/fs/tool-fs/src/index.ts`](../packages/fs/tool-fs/src/index.ts
 
 The read-before-write/edit policy is added by `@deepseek-ai/dsh-fs-policy` (an `fs/*` event-gate plugin, no schema change); a deployment that loads these tools is expected to also load it. The tool schemas above are identical with or without the policy plugin.
 
+## `@deepseek-ai/dsh-tool-skill`
+
+### `skill`
+
+Load the full instructions for an available skill. Call this with the exact skill name from the session skill catalog before acting on a task that names or clearly matches that skill.
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "name": {
+      "type": "string",
+      "description": "The exact skill name from the available skills list."
+    }
+  },
+  "required": [
+    "name"
+  ]
+}
+```
+
+Source: [`packages/skill/tool-skill/src/index.ts`](../packages/skill/tool-skill/src/index.ts)
+
 ## `@deepseek-ai/dsh-tool-subagent`
 
 ### `subagent`

examples/acp-agent/tests/acp.e2e.ts

@@ -63,7 +63,16 @@ function spawnAcpAgent(cwd: string, env: NodeJS.ProcessEnv = process.env): Spawn
   const child = spawn(
     process.execPath,
     ['--import', tsxLoader, binScript, configPath],
-    { cwd, env: { ...env, TSX_TSCONFIG_PATH: repoTsconfig }, stdio: ['pipe', 'pipe', 'pipe'] },
+    {
+      cwd,
+      env: {
+        ...env,
+        TSX_TSCONFIG_PATH: repoTsconfig,
+        DSH_HOME: join(cwd, '.dsh'),
+        DSH_AGENTS_HOME: join(cwd, '.agents'),
+      },
+      stdio: ['pipe', 'pipe', 'pipe'],
+    },
   )
   const stderr: string[] = []
   child.stderr.setEncoding('utf8')
@@ -151,7 +160,13 @@ describe('acp-agent over real stdio (no key required)', () => {
     // which this purity test never triggers). So this runs WITHOUT real creds.
     const child = spawn(process.execPath, ['--import', tsxLoader, binScript, configPath], {
       cwd: workdir,
-      env: { ...process.env, DEEPSEEK_API_KEY: process.env.DEEPSEEK_API_KEY ?? 'sk-dummy-for-boot', TSX_TSCONFIG_PATH: repoTsconfig },
+      env: {
+        ...process.env,
+        DEEPSEEK_API_KEY: process.env.DEEPSEEK_API_KEY ?? 'sk-dummy-for-boot',
+        TSX_TSCONFIG_PATH: repoTsconfig,
+        DSH_HOME: join(workdir, '.dsh'),
+        DSH_AGENTS_HOME: join(workdir, '.agents'),
+      },
       stdio: ['pipe', 'pipe', 'pipe'],
     })
     const out: string[] = []

examples/acp-agent/tests/acp.snapshot.ts

@@ -52,6 +52,7 @@ const SCENARIOS: Scenario[] = [
   { name: 'tool-call-turn', hasModelTurn: true, recorded: true },
   { name: 'fs-terminal-card', hasModelTurn: true, recorded: true },
   { name: 'todo-plan', hasModelTurn: true, recorded: true },
+  { name: 'skill-load', hasModelTurn: true, recorded: false, pinsHeader: true, headerClass: 'skill' },
   { name: 'workspace-edit', hasModelTurn: true, recorded: true },
   { name: 'fs-read', hasModelTurn: true, recorded: true },
   { name: 'fs-write', hasModelTurn: true, recorded: true },

examples/acp-agent/tests/snapshots/skill-load/input.json

@@ -0,0 +1,7 @@
+{
+  "steps": [
+    { "op": "initialize" },
+    { "op": "newSession" },
+    { "op": "prompt", "text": "Load the snapshot-skill skill with the skill tool, then reply DONE." }
+  ]
+}

examples/acp-agent/tests/snapshots/skill-load/stdout.golden.jsonl

@@ -0,0 +1,8 @@
+{"jsonrpc":"2.0","id":1,"result":{"protocolVersion":1,"agentInfo":{"name":"deepseek-harness-acp","version":"0.0.1"},"agentCapabilities":{"loadSession":true,"promptCapabilities":{"image":false,"audio":false,"embeddedContext":false}},"authMethods":[]}}
+{"jsonrpc":"2.0","id":2,"result":{"sessionId":"{{sessionId}}"}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"Load the requested skill."}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"tool_call","toolCallId":"call_skill_load","title":"Load skill snapshot-skill","kind":"read","status":"in_progress","rawInput":"snapshot-skill"}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"tool_call_update","toolCallId":"call_skill_load","status":"completed","content":[{"type":"content","content":{"type":"text","text":"<skill_content name=\"snapshot-skill\">\n<skill_resources>\nBase directory for this skill: {{cwd}}/.dsh/skills/snapshot-skill\nResolve relative paths mentioned by this skill against the base directory before using them. Load referenced resources only as needed.\n</skill_resources>\n\n<skill_instructions>\nFollow these snapshot-only instructions.\nResolve referenced resources relative to this skill directory.\n</skill_instructions>\n</skill_content>"}}]}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"The skill is loaded."}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_message_chunk","content":{"type":"text","text":"DONE"}}}}
+{"jsonrpc":"2.0","id":3,"result":{"stopReason":"end_turn"}}

examples/acp-agent/tests/snapshots/skill-load/workspace/.dsh/skills/snapshot-skill/SKILL.md

@@ -0,0 +1,7 @@
+---
+name: snapshot-skill
+description: Exercise project skill discovery and loading in snapshot tests.
+---
+
+Follow these snapshot-only instructions.
+Resolve referenced resources relative to this skill directory.

examples/coding-agent/tests/keyless-smoke.e2e.ts

@@ -62,6 +62,8 @@ async function bootAndEof(): Promise<{ stdout: string; code: number }> {
           // A dummy key so llm-deepseek's apply() (key-PRESENT check only) boots.
           // No prompt is sent, so the adapter never streams — no network call.
           DEEPSEEK_API_KEY: 'keyless-smoke-no-call',
+          DSH_HOME: join(cwd, '.dsh'),
+          DSH_AGENTS_HOME: join(cwd, '.agents'),
         },
         stdio: ['pipe', 'pipe', 'pipe'],
       },

examples/echo-agent/README.md

@@ -31,4 +31,4 @@ node --expose-internals --import tsx packages/ui/stdio-agent/src/bin.ts examples
 
 Type a message and press Enter. "echo <text>" triggers a tool call round-trip (the mock model requests the `echo` tool, which echoes the text uppercased, and the next model step acknowledges it).
 
-The session is persisted under `.sessions/` relative to the directory you launch the demo from. `pnpm run demo:echo` runs from the repo root, so the logs land in `<repo-root>/.sessions/` (a session with no cwd goes in the `_no-cwd/` bucket, one `.jsonl` log per session). Clean up with: `rm -rf .sessions`
+The session is persisted under `.sessions/` relative to the directory you launch the demo from. `pnpm run demo:echo` runs from the repo root, so the logs land in `<repo-root>/.sessions/cwd-<hash>/` (one `.jsonl` log per session). Clean up with: `rm -rf .sessions`

examples/echo-agent/tests/echo.e2e.ts

@@ -63,7 +63,16 @@ async function runEcho(lines: string[]): Promise<{ stdout: string; code: number
       // requires it (mirrors the `demo:echo` script). The whole point is to boot
       // the example EXACTLY as it really runs, through the bin + Loader.
       ['--expose-internals', '--import', tsxLoader, binScript, configPath],
-      { cwd, env: { ...process.env, TSX_TSCONFIG_PATH: repoTsconfig }, stdio: ['pipe', 'pipe', 'pipe'] },
+      {
+        cwd,
+        env: {
+          ...process.env,
+          TSX_TSCONFIG_PATH: repoTsconfig,
+          DSH_HOME: join(cwd, '.dsh'),
+          DSH_AGENTS_HOME: join(cwd, '.agents'),
+        },
+        stdio: ['pipe', 'pipe', 'pipe'],
+      },
     )
     child = proc
     let stdout = ''

examples/sandbox-acp-agent/tests/acp.snapshot.ts

@@ -1,6 +1,6 @@
 import { dirname, join } from 'node:path'
 import { fileURLToPath } from 'node:url'
-import { defineAcpSnapshotSuite, type Scenario } from '@deepseek-ai/dsh-acp-snapshot'
+import { defineAcpSnapshotSuite, type Scenario, type SnapshotSuiteOptions } from '@deepseek-ai/dsh-acp-snapshot'
 
 /**
  * Snapshot suite for the SANDBOXED composition (`../cordis.yml`, swapped to
@@ -55,6 +55,21 @@ const SCENARIOS: Scenario[] = [
   { name: 'escalation-rejected', hasModelTurn: true, recorded: true },
 ]
 
+function snapshotModeFromEnv(value: string | undefined): SnapshotSuiteOptions['mode'] {
+  switch (value) {
+    case undefined:
+    case '':
+    case 'replay':
+      return 'replay'
+    case 'record':
+      return 'record'
+    case 'refresh':
+      return 'refresh'
+    default:
+      throw new Error(`unknown DSH_SNAPSHOT mode: ${value}`)
+  }
+}
+
 defineAcpSnapshotSuite({
   agent: {
     binScript: fileURLToPath(new URL('../../../packages/ui/acp-agent/src/bin.ts', import.meta.url)),
@@ -63,5 +78,5 @@ defineAcpSnapshotSuite({
   },
   snapshotsDir: join(dirname(fileURLToPath(import.meta.url)), 'snapshots'),
   scenarios: SCENARIOS,
-  mode: process.env.DSH_SNAPSHOT === 'record' ? 'record' : 'replay',
+  mode: snapshotModeFromEnv(process.env.DSH_SNAPSHOT),
 })

examples/sandbox-acp-agent/tests/snapshots/mode-switching/session.jsonl

@@ -2,7 +2,7 @@
 {"type":"turn/start","seq":0,"time":1783613224997,"data":{"turn":1,"trigger":{"kind":"message","source":{"kind":"user"}}}}
 {"type":"user/message","seq":1,"time":1783613224997,"data":{"content":[{"type":"text","text":"Use the bash tool to run exactly: cat notes.txt. Then reply with the single word DONE and stop."}],"source":{"kind":"user"}},"surfaceOp":"append"}
 {"type":"step/start","seq":2,"time":1783613224997,"data":{"turn":1,"step":1}}
-{"type":"request/header","seq":3,"time":1783613224997,"data":{"header":{"config":{"model":"deepseek-v4-flash"},"system":"You are an AI agent powered by the DeepSeek Harness SDK.\n\nYou are a coding assistant powered by the deepseek-v4-flash model. Your working\ndirectory is /var/folders/2g/b32ct0qn1d728l_v6tdkjytr0000gn/T/acp-snap-cwd-mNdf7I. Your bash tool runs under a file sandbox — a\n`[sandbox: file access denied …]` result is policy, not a command bug.\n\nVerify your work by running the code or tests. Keep answers brief and\nfactual.\n\n\nCheck the [exit code: N] marker on every bash result; investigate failures before moving on.\n\n<!-- dsh-user-approval-policy:ask -->","tools":[{"name":"bash","description":"Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Commands may run under a file sandbox; a blocked file operation is reported as `[sandbox: file access denied under <mode> mode]` — a policy denial, not a bug in the command; do not retry another way (a background task reports the same marker via bash_output once it has finished). Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; poll it with `bash_output` and stop it with `bash_kill`. Attempting a command the sandbox may deny is safe and expected: run it and read the marker rather than assuming the denial. When a command IS denied and a wider mode would let it succeed, escalate immediately in the SAME turn — the ONE sanctioned exception to a denial: retry the exact same command once with `sandbox_permissions` (the narrowest wider mode that suffices) plus a one-sentence `justification`. Do not detour through chat to ask permission first — the approval prompt raised by that retry IS how the user consents. If the session states approval prompts are disabled, there is no exception: a denial is final — do not set `sandbox_permissions`. Never escalate speculatively: ground the request in a real denial — normally the one THIS command just hit; escalating up front is fine only when this session already denied the same access. A rejected escalation is final for THAT command — stop and explain, never work around it — but it does not forbid attempting or escalating other commands later.","parameters":{"type":"object","properties":{"command":{"type":"string","description":"The bash command to execute."},"description":{"type":"string","description":"Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"npm install\" → \"Install package dependencies\"."},"timeoutMs":{"type":"number","description":"Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry."},"workdir":{"type":"string","description":"Working directory for this command. Defaults to the session workspace; a relative path is resolved against it."},"run_in_background":{"type":"boolean","description":"Run in the background and return a task id immediately. No timeout applies."},"sandbox_permissions":{"type":"string","description":"The wider sandbox mode this command needs. Only valid as a one-shot retry of a command the sandbox just denied; requires justification and user approval.","enum":["workspace-write","danger-full-access"]},"justification":{"type":"string","description":"Required with sandbox_permissions: one sentence for the user explaining why this exact command needs the wider access."}},"required":["command","description"]}},{"name":"bash_kill","description":"Ask the executor to kill a running background bash task by task id.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}},{"name":"bash_output","description":"Read new output from a background bash task started with `bash` + `run_in_background`. Returns only output produced since the previous bash_output call, plus the task status. Tasks keep running while you do other work; poll again later for more output.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}}]},"reason":"initial"}}
+{"type":"request/header","seq":3,"time":1783613224997,"data":{"header":{"config":{"model":"deepseek-v4-flash"},"system":"You are an AI agent powered by the DeepSeek Harness SDK.\n\nYou are a coding assistant powered by the deepseek-v4-flash model. Your working\ndirectory is /var/folders/2g/b32ct0qn1d728l_v6tdkjytr0000gn/T/acp-snap-cwd-mNdf7I. Your bash tool runs under a file sandbox — a\n`[sandbox: file access denied …]` result is policy, not a command bug.\n\nVerify your work by running the code or tests. Keep answers brief and\nfactual.\n\n\nCheck the [exit code: N] marker on every bash result; investigate failures before moving on.\n\n<!-- dsh-user-approval-policy:ask -->","tools":[{"name":"bash","description":"Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Commands may run under a file sandbox; a blocked file operation is reported as `[sandbox: file access denied under <mode> mode]` — a policy denial, not a bug in the command; do not retry another way (a background task reports the same marker via bash_output once it has finished). Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; poll it with `bash_output` and stop it with `bash_kill`. Attempting a command the sandbox may deny is safe and expected: run it and read the marker rather than assuming the denial. When a command IS denied and a wider mode would let it succeed, escalate immediately in the SAME turn — the ONE sanctioned exception to a denial: retry the exact same command once with `sandbox_permissions` (the narrowest wider mode that suffices) plus a one-sentence `justification`. Do not detour through chat to ask permission first — the approval prompt raised by that retry IS how the user consents. If the session states approval prompts are disabled, there is no exception: a denial is final — do not set `sandbox_permissions`. Never escalate speculatively: ground the request in a real denial — normally the one THIS command just hit; escalating up front is fine only when this session already denied the same access. A rejected escalation is final for THAT command — stop and explain, never work around it — but it does not forbid attempting or escalating other commands later.","parameters":{"type":"object","properties":{"command":{"type":"string","description":"The bash command to execute."},"description":{"type":"string","description":"Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"npm install\" → \"Install package dependencies\"."},"timeoutMs":{"type":"number","description":"Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry."},"workdir":{"type":"string","description":"Working directory for this command. Defaults to the session workspace; a relative path is resolved against it."},"run_in_background":{"type":"boolean","description":"Run in the background and return a task id immediately. No timeout applies."},"sandbox_permissions":{"type":"string","description":"The wider sandbox mode this command needs. Only valid as a one-shot retry of a command the sandbox just denied; requires justification and user approval.","enum":["workspace-write","danger-full-access"]},"justification":{"type":"string","description":"Required with sandbox_permissions: one sentence for the user explaining why this exact command needs the wider access."}},"required":["command","description"]}},{"name":"bash_kill","description":"Ask the executor to kill a running background bash task by task id.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}},{"name":"bash_output","description":"Read new output from a background bash task started with `bash` + `run_in_background`. Returns only output produced since the previous bash_output call, plus the task status. Tasks keep running while you do other work; poll again later for more output.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}},{"name":"skill","description":"Load the full instructions for an available skill. Call this with the exact skill name from the session skill catalog before acting on a task that names or clearly matches that skill.","parameters":{"type":"object","properties":{"name":{"type":"string","description":"The exact skill name from the available skills list."}},"required":["name"]}}]},"reason":"initial"}}
 {"type":"assistant/chunk","seq":4,"time":1783613225437,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":0,"blockType":"reasoning"}}}
 {"type":"assistant/chunk","seq":5,"time":1783613225438,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"The"}}}
 {"type":"assistant/chunk","seq":6,"time":1783613225658,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" user"}}}

packages/README.md

@@ -1,6 +1,6 @@
 # Packages
 
-Harness packages, all under the `@deepseek-ai/dsh-*` scope. Each package is a Cordis plugin (microkernel-style): it exports either a default `Service` subclass or a functional plugin, declares its ctx key/events through declaration merging, and exposes extension points through `ctx.effect()`, `ctx.on()`, and `ctx.waterfall()`. Authoring conventions: [AGENTS.md](AGENTS.md) (subtree) and the root [AGENTS.md](../AGENTS.md) § Conventions.
+Harness packages use the `@deepseek-ai/dsh-*` scope. Each is a Cordis plugin: a default `Service` subclass or functional plugin declaring ctx keys/events through declaration merging and contributing through `ctx.effect()`, `ctx.on()`, or `ctx.waterfall()`. Authoring conventions: [AGENTS.md](AGENTS.md) and root [AGENTS.md](../AGENTS.md) § Conventions.
 
 ## Hierarchy
 
@@ -14,6 +14,7 @@ Packages are grouped by modular role at `packages/<group>/<pkg>/`. The group dir
 | [`code-runtime/`](code-runtime/README.md) | Code-execution capability family: the abstract runtime seam for model-written programs + a worker-thread backend | Product — stable surface |
 | [`sandbox/`](sandbox/README.md) | Process-confinement seam; bwrap/Landlock/Seatbelt backends | Product — stable surface |
 | [`fs/`](fs/README.md) | Filesystem capability family: the abstract seam, a local impl, and the model-facing file tools | Product — stable surface |
+| [`skill/`](skill/README.md) | Skill capability family: the provider registry, local provider, and model-facing catalog/loader | Product — stable surface |
 | [`compact/`](compact/README.md) | Compaction capability family: the abstract seam + a basic backend (tool deferred) | Product — stable surface |
 | [`subagent/`](subagent/README.md) | Subagent capability family: the provider-registry seam and the model-facing delegation tool | Product — stable surface |
 | [`workflow/`](workflow/README.md) | Workflow capability family: the script-engine seam, the worker-thread engine, and the model-facing `workflow` tool | Product — stable surface |

packages/cordis/tool-cordis/src/api-catalog.ts

@@ -56,7 +56,7 @@ export const SERVICE_API: readonly ServiceApiEntry[] = [
     key: 'agentLoop',
     summary: 'The agent-loop plugin (`ctx.agentLoop`): creates ReactLoopAgents, runs their loops, and registers them in `ctx.agents`.',
     methods: [
-      'create(id: AgentId, options: AgentOptions = {}): ReactLoopAgent',
+      'create(id: AgentId, options: AgentOptions = {}, meta: Pick<SessionHeader, \'cwd\'> = {}): ReactLoopAgent',
       'createAgent(options: CreateAgentOptions): AgentHandle',
       'async resume(options: ResumeAgentOptions): Promise<AgentHandle>',
     ],
@@ -162,6 +162,16 @@ export const SERVICE_API: readonly ServiceApiEntry[] = [
       'fork(source: SessionForkSource, boundary?: number, childSessionId?: SessionId): Session',
     ],
   },
+  {
+    key: 'skills',
+    summary: 'Registry of skill providers.',
+    methods: [
+      'registerProvider(provider: SkillProvider): () => void',
+      'register(skill: SkillRegistration): () => void',
+      'async list(options: SkillLookupOptions = {}): Promise<SkillSummary[]>',
+      'async get(name: string, options: SkillLookupOptions = {}): Promise<SkillDefinition | undefined>',
+    ],
+  },
   {
     key: 'subagents',
     summary: 'The `subagents` service: a registry of named SubagentProviders and a capability-checked start surface.',
@@ -341,6 +351,18 @@ export const EVENT_API: readonly EventApiEntry[] = [
     signature: '\'session/flush\'(session: Session): Promise<void> | void',
     summary: 'Awaited durability checkpoint.',
   },
+  {
+    name: 'skill/provider-added',
+    mode: 'emit',
+    signature: '\'skill/provider-added\'(provider: SkillProvider): void',
+    summary: 'A skill provider became resolvable in the `ctx.skills` registry.',
+  },
+  {
+    name: 'skill/provider-removed',
+    mode: 'emit',
+    signature: '\'skill/provider-removed\'(name: string): void',
+    summary: 'A skill provider left the registry because its plugin fiber was disposed.',
+  },
   {
     name: 'subagent/end',
     mode: 'emit',
@@ -753,6 +775,38 @@ export const TYPE_API: readonly TypeApiEntry[] = [
     name: 'SessionId',
     declaration: 'export type SessionId = Branded<\'SessionId\'>;',
   },
+  {
+    name: 'SkillCandidate',
+    declaration: 'export interface SkillCandidate extends SkillSummary {\n    rank: number;\n    locator: unknown;\n    path?: string;\n    metadata?: Record<string, unknown>;\n}',
+  },
+  {
+    name: 'SkillDefinition',
+    declaration: 'export interface SkillDefinition extends SkillSummary {\n    content: string;\n    path?: string;\n    metadata?: Record<string, unknown>;\n}',
+  },
+  {
+    name: 'SkillLookupOptions',
+    declaration: 'export interface SkillLookupOptions {\n    cwd?: string | undefined;\n    signal?: AbortSignal | undefined;\n}',
+  },
+  {
+    name: 'SkillProvider',
+    declaration: 'export interface SkillProvider {\n    name: string;\n    list(options: SkillLookupOptions): Promise<SkillCandidate[]>;\n    get(candidate: SkillCandidate, options: SkillLookupOptions): Promise<SkillDefinition | undefined>;\n}',
+  },
+  {
+    name: 'SkillRegistration',
+    declaration: 'export type SkillRegistration = Omit<SkillDefinition, \'provider\'> & {\n    provider?: string;\n};',
+  },
+  {
+    name: 'SkillResourceBase',
+    declaration: 'export type SkillResourceBase = {\n    kind: \'directory\';\n    path: string;\n} | {\n    kind: \'url\';\n    url: string;\n} | {\n    kind: \'opaque\';\n    description: string;\n};',
+  },
+  {
+    name: 'SkillSource',
+    declaration: 'export type SkillSource = \'project-dsh\' | \'project-agents\' | \'runtime\' | \'user-dsh\' | \'user-agents\' | \'custom\' | (string & {});',
+  },
+  {
+    name: 'SkillSummary',
+    declaration: 'export interface SkillSummary {\n    name: string;\n    description: string;\n    whenToUse?: string;\n    disableModelInvocation?: boolean;\n    source: SkillSource;\n    provider: string;\n    resourceBase?: SkillResourceBase;\n}',
+  },
   {
     name: 'StreamChunk',
     declaration: 'export type StreamChunk = {\n    type: \'block-start\';\n    index: number;\n    blockType: ContentBlockType;\n} | {\n    type: \'text-delta\';\n    index: number;\n    text: string;\n} | {\n    type: \'reasoning-delta\';\n    index: number;\n    text: string;\n} | {\n    type: \'tool-call-delta\';\n    index: number;\n    id: CallId;\n    name?: string;\n    argumentsDelta: string;\n} | {\n    type: \'block-end\';\n    index: number;\n    block: ContentBlock;\n} | {\n    type: \'usage\';\n    usage: TokenUsage;\n} | {\n    type: \'finish\';\n    reason: FinishReason;\n};',

packages/core/README.md

@@ -1,6 +1,6 @@
 # core/ — product API spine
 
-The packages every harness build is assembled from: the session log, the system-prompt assembly, the tool registry, the agent vocabulary, and the one concrete loop that drives them. These are **product** packages — the stable surface plugins and consumers build against.
+The session log, system-prompt assembly, tool registry, agent vocabulary, and concrete loop that form the harness's default control spine. These are **product** packages — the stable surface plugins and consumers build against.
 
 | Package | Role | ctx key |
 |---|---|---|
@@ -9,8 +9,8 @@ The packages every harness build is assembled from: the session log, the system-
 | `tools/` | Tool registry + `tools/pre-execute`/`tools/post-execute` pipeline | `ctx.tools` |
 | `agent/` | Agent interface, registry, `agent/*` event vocabulary | `ctx.agents` |
 | `agent-loop/` | The concrete loop plugin: `ReactLoopAgent` + the loop driver | `ctx.agentLoop` |
-| `agent-core/` | Bundle plugin: the providerless/executor-less/UI-less spine as code | (loads the spine) |
+| `agent-core/` | Bundle plugin: the default executor-less/UI-less spine as code | (loads the spine) |
 
 `agent-loop` is the one concrete implementation of the `agent` seam and lives here because it is the harness's default product loop; everything else in `core/` is interface/vocabulary. Plugins depend on the `agent` vocabulary, never on `agent-loop` directly, so the loop stays swappable.
 
-`agent-core` is the composition counterpart: one bundle plugin that loads the whole providerless spine (`timer` + `llm` + sessions + system-prompt + tools + agents + invariants + `tool-bash` + `agent-loop`) and forwards `agent-loop`'s `agents` list as its own config. App packages (`ui/stdio-agent`, `ui/acp-agent`) consume it and add only a front door; a leaf adds the swappable backends plus any optional product tools it wants to expose. It lives in `core/` because it composes exclusively `core/` + interface packages and ships no provider, executor, or UI of its own.
+`agent-core` is the composition counterpart: one bundle plugin that loads the control spine plus selected default capabilities (`timer` + `llm` + sessions + system-prompt + tools + agents + invariants + the local [skill family](../skill/README.md) + `tool-bash` + `agent-loop`) and forwards `agent-loop`'s `agents` list as its own config. App packages (`ui/stdio-agent`, `ui/acp-agent`) consume it and add only a front door; a leaf adds the swappable backends plus any optional product tools it wants to expose. It lives in `core/` because it composes the shared control spine while leaving executors, LLM adapters, alternate skill providers, and UI front doors outside the bundle.

packages/core/agent-core/README.md

@@ -1,6 +1,6 @@
 # @deepseek-ai/dsh-agent-core
 
-The **providerless, executor-less, UI-less agent spine** as ONE Cordis bundle plugin. It loads the fixed set of services every harness agent needs and forwards the loop's `agents` list as its own config — so an app package composes a working agent by adding only a front door and the swappable backends.
+The **default executor-less, UI-less agent spine** as ONE Cordis bundle plugin. It loads the fixed set of services every harness agent needs, including the local skill provider, and forwards the loop's `agents` list as its own config — so an app package composes a working agent by adding only a front door and the swappable backends.
 
 This is the package to read to see **the whole plugin tree at once** — the teaching role the inlined `echo-agent` `cordis.yml` used to play before the spine moved behind this bundle.
 
@@ -14,9 +14,12 @@ This is the package to read to see **the whole plugin tree at once** — the tea
 @deepseek-ai/dsh-session          event-sourced session log + store
 @deepseek-ai/dsh-system-prompt    prompt-section + tool-schema assembly
 @deepseek-ai/dsh-tools            tool registry + tools/pre-execute/post-execute
+@deepseek-ai/dsh-skill            skill provider registry
+@deepseek-ai/dsh-skill-local      local filesystem skill provider
 @deepseek-ai/dsh-agent            agent registry + agent/* event vocabulary
 @deepseek-ai/dsh-invariants       dev-mode event-contract assertions
 @deepseek-ai/dsh-tool-bash        the model-facing bash/bash_output/bash_kill schemas
+@deepseek-ai/dsh-tool-skill       session-prefix skill catalog + model-facing loader schema
 @deepseek-ai/dsh-agent-loop       THE concrete loop (gets the forwarded `agents`)
                                   (dsh-system-prompt gets the forwarded `persona`)
 ```
@@ -27,6 +30,7 @@ The spine is everything COMMON to every front door. The swappable and front-door
 
 - **the LLM adapter** — the bundle ships the abstract `llm` service; the leaf registers a concrete adapter on `ctx.llm` (`llm-deepseek`, `llm-pi-ai`, `llm-replay`).
 - **the bash executor** — the bundle ships `tool-bash` (the consumer schema); the leaf provides `ctx.bash` (`bash-local` or a sandboxed impl).
+- **non-local skill providers** — the bundle ships the skill registry, the local filesystem provider, and the `skill` tool; deployments can add other providers such as embedded or remote catalogs as siblings.
 - **presentation + per-app infra** — the stdio UI / ACP bridge, a console logger, `hmr`. These form the coupled "front-door cluster" that the app packages ([`dsh-stdio-agent`](../../ui/stdio-agent/README.md), [`dsh-acp-agent`](../../ui/acp-agent/README.md)) bake in. `timer` is in the spine (common to both, stdout-silent); a console logger is NOT (it writes to stdout, which the ACP bridge reserves for JSON-RPC).
 
 This is the [interface/implementation/consumer seam](../../../docs/rfc/implemented/architecture/2026-06-13-capability-seams.md) raised to the composition level: the bundle owns the shared spine, the leaf owns the backends, the app package owns the front door.
@@ -35,11 +39,11 @@ This is the [interface/implementation/consumer seam](../../../docs/rfc/implement
 
 ```ts
 import type { Config } from '@deepseek-ai/dsh-agent-core'
-// { agents?, persona?, toolOrder? } — the schema is z.intersect([AgentLoop.Config, SystemPrompt.Config]),
-// so validation and defaulting can never drift from the owners'.
+// { agents?, persona?, toolOrder?, tools?, skills? } — the schema intersects the owner schemas,
+// so validation and defaulting can never drift from the owners.
 ```
 
-The bundle FORWARDS each field to the child that owns it: `agents` to `agent-loop` (default `[]`), so each app supplies its own pre-created agents — a stdio app pre-creates a `main`; the ACP app pre-creates none (it creates agents on demand at `session/new`) — `persona` to `dsh-system-prompt` (default `''`), the deployment's persona section — and `toolOrder` to `dsh-system-prompt` (absent — lexicographic), the explicit model-facing tool order. Forwarding is exactly why the owners can live in the shared spine even though the apps disagree on what to configure.
+The bundle FORWARDS each field to the child that owns it: `agents` to `agent-loop` (default `[]`), so each app supplies its own pre-created agents — a stdio app pre-creates a `main`; the ACP app pre-creates none (it creates agents on demand at `session/new`) — `persona` and `toolOrder` to `dsh-system-prompt`; `tools` to the tool registry for its presentation mode; and `skills.registry`, `skills.local`, and `skills.tool` to the skill registry, local provider, and model-facing consumer. Forwarding is exactly why the owners can live in the shared spine even though the apps disagree on what to configure.
 
 ## Why a code bundle, not a shared YAML include
 

packages/core/agent-core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deepseek-ai/dsh-agent-core",
-  "description": "The providerless/executor-less/UI-less agent spine as one Cordis bundle plugin (timer + llm + sessions + system-prompt + tools + agents + invariants + tool-bash + agent-loop)",
+  "description": "The default executor-less/UI-less agent spine as one Cordis bundle plugin (timer + llm + sessions + system-prompt + tools + skills + agents + invariants + tool-bash + tool-skill + agent-loop)",
   "version": "0.0.1",
   "private": true,
   "type": "module",
@@ -28,8 +28,11 @@
     "@deepseek-ai/dsh-invariants": "^0.0.1",
     "@deepseek-ai/dsh-llm": "^0.0.1",
     "@deepseek-ai/dsh-session": "^0.0.1",
+    "@deepseek-ai/dsh-skill": "^0.0.1",
+    "@deepseek-ai/dsh-skill-local": "^0.0.1",
     "@deepseek-ai/dsh-system-prompt": "^0.0.1",
     "@deepseek-ai/dsh-tool-bash": "^0.0.1",
+    "@deepseek-ai/dsh-tool-skill": "^0.0.1",
     "@deepseek-ai/dsh-tools": "^0.0.1",
     "cordis": "^4.0.0-rc.6"
   },
@@ -40,8 +43,11 @@
     "@deepseek-ai/dsh-invariants": "workspace:^",
     "@deepseek-ai/dsh-llm": "workspace:^",
     "@deepseek-ai/dsh-session": "workspace:^",
+    "@deepseek-ai/dsh-skill": "workspace:^",
+    "@deepseek-ai/dsh-skill-local": "workspace:^",
     "@deepseek-ai/dsh-system-prompt": "workspace:^",
     "@deepseek-ai/dsh-tool-bash": "workspace:^",
+    "@deepseek-ai/dsh-tool-skill": "workspace:^",
     "@deepseek-ai/dsh-tools": "workspace:^",
     "cordis": "^4.0.0-rc.6"
   },

packages/core/agent-core/src/index.ts

@@ -1,10 +1,10 @@
 /**
- * The providerless, executor-less, UI-less agent spine as ONE bundle plugin.
+ * The default executor-less, UI-less agent spine as ONE bundle plugin.
  *
  * Loads the fixed set of services every harness agent needs — `timer`, the LLM
  * service, the session store, system-prompt assembly, the tool registry, the
- * agent registry, the dev-mode invariants, the model-facing `bash` tool
- * schemas, and the concrete `agent-loop` — and forwards the loop's `agents`
+ * skill registry plus local skill provider, the agent registry, the dev-mode
+ * invariants, the model-facing `bash` and `skill` tool schemas, and the concrete `agent-loop` — and forwards the loop's `agents`
  * list as its OWN config (default `[]`), so each app supplies its own
  * pre-created agents.
  *
@@ -19,6 +19,9 @@
  *    (a console logger, `hmr`) — these are the coupled "front-door cluster" the
  *    app packages ({@link @deepseek-ai/dsh-stdio-agent},
  *    {@link @deepseek-ai/dsh-acp-agent}) bake in, NOT the shared spine.
+ *  - additional SKILL PROVIDERS; the bundle ships the local filesystem provider
+ *    because local skills are default agent behavior, while embedded or remote
+ *    providers remain deployment choices.
  *
  * This is the interface/implementation/consumer seam at the composition level:
  * the bundle owns the shared spine, the leaf owns the backends, the app package
@@ -49,24 +52,37 @@ import LlmService from '@deepseek-ai/dsh-llm'
 import SessionStore from '@deepseek-ai/dsh-session'
 import SystemPrompt, { type Config as SystemPromptConfig } from '@deepseek-ai/dsh-system-prompt'
 import ToolRegistry, { type Config as ToolsConfig } from '@deepseek-ai/dsh-tools'
+import SkillService, { type Config as SkillRegistryConfig } from '@deepseek-ai/dsh-skill'
+import * as SkillLocal from '@deepseek-ai/dsh-skill-local'
 import AgentRegistry from '@deepseek-ai/dsh-agent'
 import * as invariants from '@deepseek-ai/dsh-invariants'
 import * as toolBash from '@deepseek-ai/dsh-tool-bash'
+import * as toolSkill from '@deepseek-ai/dsh-tool-skill'
 import AgentLoop, { type Config as AgentLoopConfig } from '@deepseek-ai/dsh-agent-loop'
 
 export const name = 'agent-core'
 
+/** Skill bundle config forwarded to the registry, local provider, and model-facing consumer. */
+export interface SkillConfig {
+  /** Registry-level discovery cache settings. */
+  registry?: SkillRegistryConfig
+  /** Local filesystem skill provider settings. */
+  local?: SkillLocal.Config
+  /** Model-facing skill catalog and tool settings. */
+  tool?: toolSkill.Config
+}
+
 /**
  * Bundle config: each field forwarded verbatim to the child that owns it —
  * `agents` to the agent loop (an app that pre-creates no agents, like the ACP
  * bridge, simply omits it), `persona` and `toolOrder` to the system-prompt
  * plugin (the deployment's persona section and the explicit model-facing tool
- * order), the `tools` object to the tool registry (its presentation `mode`).
- * Every field is optional INPUT here because each owner's schema
- * supplies the default (`[]` / `''` / absent — lexicographic / `native`); the
- * schema is the INTERSECTION of the owners' own schemas (the registry's
- * nested under its `tools` key), so validation and defaulting can never
- * drift from them.
+ * order), the `tools` object to the tool registry (its presentation `mode`),
+ * and `skills` to the skill registry/local provider/tool consumer. Every field
+ * is optional INPUT here because each owner's schema supplies the default;
+ * the schema is the INTERSECTION of the owners' own schemas (with registry
+ * schemas nested under their bundle keys), so validation and defaulting can
+ * never drift from them.
  */
 export interface Config {
   /** The agent-loop `agents` list (see dsh-agent-loop's `Config`). */
@@ -77,10 +93,23 @@ export interface Config {
   toolOrder?: SystemPromptConfig['toolOrder']
   /** The tool registry's config — its presentation `mode` (see dsh-tools' `Config`). */
   tools?: ToolsConfig
+  /** Skill registry, local provider, and model-facing consumer config. */
+  skills?: SkillConfig
 }
 
-/** Intersect the owners' schemas so validation + defaulting stay identical (the registry's nested under `tools`). */
-export const Config = z.intersect([AgentLoop.Config, SystemPrompt.Config, z.object({ tools: ToolRegistry.Config })]) as unknown as z<Config>
+/** The skill config schema exported for app packages that forward `skills`. */
+export const SkillConfigSchema: z<SkillConfig> = z.object({
+  registry: SkillService.Config,
+  local: SkillLocal.Config,
+  tool: toolSkill.Config,
+})
+
+/** Intersect the owners' schemas so validation + defaulting stay identical. */
+export const Config = z.intersect([
+  AgentLoop.Config,
+  SystemPrompt.Config,
+  z.object({ tools: ToolRegistry.Config, skills: SkillConfigSchema }),
+]) as unknown as z<Config>
 
 /**
  * Load the spine. Each `ctx.plugin(...)` mounts one child of the bundle fiber;
@@ -106,8 +135,11 @@ export function apply(ctx: Context, config: Config): void {
     ...config.toolOrder !== undefined ? { toolOrder: config.toolOrder } : {},
   })
   ctx.plugin(ToolRegistry, config.tools ?? {})
+  ctx.plugin(SkillService, config.skills?.registry ?? {})
+  ctx.plugin(SkillLocal, config.skills?.local ?? {})
   ctx.plugin(AgentRegistry)
   ctx.plugin(invariants)
   ctx.plugin(toolBash)
+  ctx.plugin(toolSkill, config.skills?.tool ?? {})
   ctx.plugin(AgentLoop, { agents: config.agents ?? [] })
 }

packages/core/agent-core/tests/agent-core.spec.ts

@@ -1,13 +1,25 @@
 import { describe, expect, it } from 'vitest'
+import { mkdir, mkdtemp, writeFile } from 'node:fs/promises'
+import { join } from 'node:path'
+import { tmpdir } from 'node:os'
 import { Context } from 'cordis'
 import Loader from '@cordisjs/plugin-loader'
 import { TOOL_ORDER_REST } from '@deepseek-ai/dsh-system-prompt'
 import * as agentCore from '../src/index.ts'
 import { AgentId } from '@deepseek-ai/dsh-agent'
+import type { Message } from '@deepseek-ai/dsh-llm'
+
+async function composePrefix(ctx: Context, cwd: string): Promise<Message[]> {
+  const empty: Message[] = []
+  return await ctx.waterfall(
+    'agent/session-prefix', { session: { header: { cwd } } } as never,
+    empty, new AbortController().signal, () => Promise.resolve(empty),
+  )
+}
 
 /**
  * Unit coverage for the @deepseek-ai/dsh-agent-core bundle: mounting it brings
- * up the whole providerless spine in one `ctx.plugin`, and the forwarded
+ * up the whole default spine in one `ctx.plugin`, and the forwarded
  * `agents` config reaches the loop (default `[]`, or a pre-created agent).
  *
  * The bundle is exercised through `ctx.plugin(agentCore, …)` — the NAMESPACE
@@ -16,16 +28,54 @@ import { AgentId } from '@deepseek-ai/dsh-agent'
  * bin smokes; here we assert the composition + config forwarding.
  */
 async function mount(config?: agentCore.Config): Promise<Context> {
+  const oldDshHome = process.env.DSH_HOME
+  const oldAgentsHome = process.env.DSH_AGENTS_HOME
+  process.env.DSH_HOME = await mkdtemp(join(tmpdir(), 'dsh-agent-core-home-'))
+  process.env.DSH_AGENTS_HOME = await mkdtemp(join(tmpdir(), 'dsh-agent-core-agents-'))
   const ctx = new Context()
-  await ctx.plugin(agentCore, config)
-  // The bundle mounts its children inside apply() (not awaited there); let their
-  // fibers settle so the spine services and any pre-created agent are ready.
-  await new Promise(resolve => setTimeout(resolve, 50))
-  return ctx
+  try {
+    await ctx.plugin(agentCore, config)
+    // The bundle mounts its children inside apply() (not awaited there); let their
+    // fibers settle so the spine services and any pre-created agent are ready.
+    await new Promise(resolve => setTimeout(resolve, 50))
+    return ctx
+  } finally {
+    if (oldDshHome === undefined) {
+      delete process.env.DSH_HOME
+    } else {
+      process.env.DSH_HOME = oldDshHome
+    }
+    if (oldAgentsHome === undefined) {
+      delete process.env.DSH_AGENTS_HOME
+    } else {
+      process.env.DSH_AGENTS_HOME = oldAgentsHome
+    }
+  }
+}
+
+async function withIsolatedSkillHomes<T>(run: () => Promise<T>): Promise<T> {
+  const oldDshHome = process.env.DSH_HOME
+  const oldAgentsHome = process.env.DSH_AGENTS_HOME
+  process.env.DSH_HOME = await mkdtemp(join(tmpdir(), 'dsh-agent-core-home-'))
+  process.env.DSH_AGENTS_HOME = await mkdtemp(join(tmpdir(), 'dsh-agent-core-agents-'))
+  try {
+    return await run()
+  } finally {
+    if (oldDshHome === undefined) {
+      delete process.env.DSH_HOME
+    } else {
+      process.env.DSH_HOME = oldDshHome
+    }
+    if (oldAgentsHome === undefined) {
+      delete process.env.DSH_AGENTS_HOME
+    } else {
+      process.env.DSH_AGENTS_HOME = oldAgentsHome
+    }
+  }
 }
 
 describe('dsh-agent-core bundle', () => {
-  it('brings up the full providerless spine', async () => {
+  it('brings up the full default spine', async () => {
     const ctx = await mount()
     // One service from each layer of the spine proves the children loaded.
     expect(ctx.get('timer')).toBeDefined()
@@ -33,11 +83,22 @@ describe('dsh-agent-core bundle', () => {
     expect(ctx.get('sessions')).toBeDefined()
     expect(ctx.get('systemPrompt')).toBeDefined()
     expect(ctx.get('tools')).toBeDefined()
+    expect(ctx.get('skills')).toBeDefined()
     expect(ctx.get('agents')).toBeDefined()
     expect(ctx.get('agentLoop')).toBeDefined()
     await ctx.fiber.dispose()
   })
 
+  it('includes the skill registry, local provider, and skill tool without builtin skills', async () => {
+    const ctx = await mount()
+
+    expect(ctx.skills).toBeDefined()
+    expect(ctx.tools.schemas().map(tool => tool.name)).toContain('skill')
+    expect(await ctx.skills.list()).toEqual([])
+
+    await ctx.fiber.dispose()
+  })
+
   it('defaults the agents list to empty (no pre-created agents)', async () => {
     const ctx = await mount()
     expect(ctx.get('agents')?.get(AgentId('main'))).toBeUndefined()
@@ -68,6 +129,40 @@ describe('dsh-agent-core bundle', () => {
     await ctx.fiber.dispose()
   })
 
+  it('forwards skill config to the registry, local provider, and model-facing consumer', async () => {
+    const home = await mkdtemp(join(tmpdir(), 'dsh-agent-core-skill-home-'))
+    const agentsHome = await mkdtemp(join(tmpdir(), 'dsh-agent-core-skill-agents-'))
+    const custom = await mkdtemp(join(tmpdir(), 'dsh-agent-core-skill-custom-'))
+    await mkdir(custom, { recursive: true })
+    await writeFile(join(custom, 'custom-skill.md'), '---\nname: custom-skill\ndescription: Custom skill\n---\n\nCustom body.\n')
+    const ctx = await mount({
+      agents: [],
+      skills: {
+        registry: { collectCacheMaxEntries: 4 },
+        local: {
+          dshHome: join(home, '.dsh'),
+          agentsHome: join(agentsHome, '.agents'),
+          customSkillDirs: [custom],
+        },
+        tool: { catalogDescriptionMaxLength: 6 },
+      },
+    })
+    expect((await ctx.skills.list()).map(skill => skill.name)).toEqual(['custom-skill'])
+    expect(JSON.stringify(await composePrefix(ctx, '/tmp'))).toContain('- `custom-skill`: Cus...')
+    await ctx.fiber.dispose()
+  })
+
+  it('uses the default skill config when apply is called directly without skills', async () => {
+    await withIsolatedSkillHomes(async () => {
+      const ctx = new Context()
+      agentCore.apply(ctx, { agents: [] })
+      await new Promise(resolve => setTimeout(resolve, 50))
+      expect(ctx.skills).toBeDefined()
+      expect(await ctx.skills.list()).toEqual([])
+      await ctx.fiber.dispose()
+    })
+  })
+
   it('forwards toolOrder to the system-prompt assembly', async () => {
     const ctx = await mount({ toolOrder: ['zulu', TOOL_ORDER_REST] })
     // The bundle's own bash tools pend on the absent `ctx.bash` executor in
@@ -81,7 +176,7 @@ describe('dsh-agent-core bundle', () => {
       })
     }
     const assembly = await ctx.get('systemPrompt')!.assemble()
-    expect(assembly.tools.map(tool => tool.name)).toEqual(['zulu', 'alpha'])
+    expect(assembly.tools.map(tool => tool.name)).toEqual(['zulu', 'alpha', 'skill'])
     await ctx.fiber.dispose()
   })
 

packages/core/agent-core/tsconfig.json

@@ -17,6 +17,9 @@
     {
       "path": "../../../vendor/timer"
     },
+    {
+      "path": "../../../vendor/schemastery"
+    },
     {
       "path": "../../llm/llm"
     },
@@ -29,6 +32,15 @@
     {
       "path": "../../core/tools"
     },
+    {
+      "path": "../../skill/skill"
+    },
+    {
+      "path": "../../skill/skill-local"
+    },
+    {
+      "path": "../../skill/tool-skill"
+    },
     {
       "path": "../../core/agent"
     },

packages/core/agent-loop/README.md

@@ -8,7 +8,7 @@ This is the only package in the harness that contains concrete loop logic. Every
 
 ### Public API
 
-- `ctx.agentLoop.create(id: string, options?: AgentOptions): ReactLoopAgent` — config-driven create: an agent on a fresh per-run session id `${id}-session-<uuid>` (no cwd). Used for `cordis.yml`-configured agents. The per-run uuid avoids colliding with the on-disk log a prior run materialized once a durable persistence backend is loaded; each run is a new session (a deliberate demo simplification — a real resume-or-create policy is a TODO). Disposed with the calling fiber.
+- `ctx.agentLoop.create(id: string, options?: AgentOptions, meta?: { cwd?: string }): ReactLoopAgent` — config-driven create: an agent on a fresh per-run session id `${id}-session-<uuid>` with optional session metadata. Used for `cordis.yml`-configured agents. The per-run uuid avoids colliding with the on-disk log a prior run materialized once a durable persistence backend is loaded; each run is a new session (a deliberate demo simplification — a real resume-or-create policy is a TODO). Disposed with the calling fiber.
 
 `AgentLoop` also implements the `AgentFactory` seam and registers itself via `ctx.agents.setFactory(this)`, so plugins create/resume agents through `ctx.agents` (the interface):
 
@@ -28,11 +28,12 @@ interface Config {
   agents: Array<{
     id: string                 // required
     model?: string
+    cwd?: string               // optional workspace cwd for the fresh session
   }>
 }
 ```
 
-Agents listed in config are auto-created at startup. (There is no per-agent persona: the deployment persona is `dsh-system-prompt`'s own `persona` config, shared by every agent in the context.) The plugin registers the built-in `model`/`cwd` prompt variables on `ctx.systemPrompt`, resolved per step from the `assemble({ agent })` context — runtime facts of the agents THIS loop drives, unlike the `harness:identity`/`deployment:persona` sections, which live on `dsh-system-prompt` so they survive a swapped loop plugin.
+Agents listed in config are auto-created at startup. `cwd` applies only to fresh config-created sessions; `resumeSessionId` keeps the persisted session header. There is no per-agent persona: the deployment persona is `dsh-system-prompt`'s own `persona` config, shared by every agent in the context. The plugin registers the built-in `model`/`cwd` prompt variables on `ctx.systemPrompt`, resolved per step from the `assemble({ agent })` context — runtime facts of the agents THIS loop drives, unlike the `harness:identity`/`deployment:persona` sections, which live on `dsh-system-prompt` so they survive a swapped loop plugin.
 
 ### Classes
 

packages/core/agent-loop/src/index.ts

@@ -12,7 +12,7 @@ import { randomUUID } from 'node:crypto'
 import z from 'schemastery'
 import type { AgentFactory, AgentHandle, AgentId, AgentOptions, CreateAgentOptions, ResumeAgentOptions, SessionStartSource } from '@deepseek-ai/dsh-agent'
 import type {} from '@deepseek-ai/dsh-llm'
-import { SessionId } from '@deepseek-ai/dsh-session'
+import { SessionId, type SessionHeader } from '@deepseek-ai/dsh-session'
 import type { Session } from '@deepseek-ai/dsh-session'
 import type {} from '@deepseek-ai/dsh-system-prompt'
 import type {} from '@deepseek-ai/dsh-tools'
@@ -38,6 +38,8 @@ export interface Config {
   agents: (AgentOptions & {
     /** Agent id to register under; also seeds the fresh per-run session id (`${id}-session-<uuid>`). */
     id: AgentId
+    /** Optional workspace cwd for the config-created fresh session. */
+    cwd?: string
     /**
      * If set, the config agent RESUMES this persisted session id instead of
      * starting a fresh `${id}-session-<uuid>`. Sourced from an env var in
@@ -77,6 +79,7 @@ export class AgentLoop extends Service implements AgentFactory {
     agents: z.array(z.object({
       id: z.string().required(),
       model: z.string(),
+      cwd: z.string(),
       resumeSessionId: z.string(),
     })).default([]),
   }) as unknown as z<Config>
@@ -96,7 +99,7 @@ export class AgentLoop extends Service implements AgentFactory {
     // (renderPrompt then rejects a persona that claims it — fail loud).
     ctx.systemPrompt.variable('model', context => context.agent?.options.model)
     ctx.systemPrompt.variable('cwd', context => context.agent?.session.header.cwd)
-    for (const { id, resumeSessionId, ...options } of config.agents) {
+    for (const { id, cwd, resumeSessionId, ...options } of config.agents) {
       if (resumeSessionId !== undefined && resumeSessionId !== '') {
         // Resume a prior session instead of starting fresh. resume() needs
         // `ctx.sessionPersistence`, which may load AFTER this plugin (cordis.yml
@@ -115,15 +118,15 @@ export class AgentLoop extends Service implements AgentFactory {
           return () => void fiber.dispose()
         }, `agentLoop.resume(${id})`)
       } else {
-        this.create(id, options)
+        this.create(id, options, cwd === undefined ? {} : { cwd })
       }
     }
   }
 
   /**
    * Config-driven create: an agent on a FRESH, non-colliding session id per run
-   * (`${id}-session-<uuid>`, no cwd). Used for `cordis.yml`-configured agents
-   * and as the shared core for the programmatic factory {@link createAgent}.
+   * (`${id}-session-<uuid>`). Used for `cordis.yml`-configured agents and as
+   * the shared core for the programmatic factory {@link createAgent}.
    *
    * Why a per-run id, not a fixed `${id}-session`: once a durable persistence
    * backend is loaded, a fixed id collides on the second run — the backend
@@ -137,15 +140,16 @@ export class AgentLoop extends Service implements AgentFactory {
    * UI/ACP path owns session selection.
    * @param id - the agent id; also seeds the generated session id.
    * @param options - loop options (model, limits, …); defaults applied per option.
+   * @param meta - optional session metadata for the fresh session.
    * @returns the running agent, owned by the calling fiber (no handle).
    */
-  create(id: AgentId, options: AgentOptions = {}): ReactLoopAgent {
+  create(id: AgentId, options: AgentOptions = {}, meta: Pick<SessionHeader, 'cwd'> = {}): ReactLoopAgent {
     this.assertAgentIdFree(id)
     // Config/programmatic path: prepare the session and let start() fold its
     // lifecycle into the agent's composite effect (so a fiber unload tears the
     // session + agent down as one ordered chain, capturing the loop's closing
     // flush). The whole effect is owned by THIS fiber; no AgentHandle is needed.
-    const session = this.ctx.sessions.prepare(SessionId(`${id}-session-${randomUUID()}`), { meta: {} })
+    const session = this.ctx.sessions.prepare(SessionId(`${id}-session-${randomUUID()}`), { meta })
     const { agent } = this.start(id, options, session, 'startup')
     return agent
   }

packages/core/agent-loop/tests/loop.spec.ts

@@ -916,6 +916,21 @@ describe('agent loop', () => {
     expect(adapter.requests).toHaveLength(1)
   })
 
+  it('attaches config agent cwd to the fresh session header', async () => {
+    const ctx = new Context()
+    await ctx.plugin(LlmService)
+    await ctx.plugin(SessionStore)
+    await ctx.plugin(SystemPrompt)
+    await ctx.plugin(ToolRegistry)
+    await ctx.plugin(AgentRegistry)
+    await ctx.plugin(AgentLoop, {
+      agents: [{ id: AgentId('config-agent'), model: 'mock', cwd: '/work/project' }],
+    })
+
+    const agent = ctx.agents.get(AgentId('config-agent'))! as ReactLoopAgent
+    expect(agent.session.header.cwd).toBe('/work/project')
+  })
+
   it('replays a session log into an identical derived history', async () => {
     const adapter = new MockAdapter([
       toolCallResponse('c1', 'echo', { text: 'x' }),

packages/core/tools/tests/gen-tool-catalog.spec.ts

@@ -35,7 +35,7 @@ describe('gen-tool-catalog collectToolCatalog', () => {
   it('boots every shipped tool package and harvests its model-facing schemas', async () => {
     const catalog = await collectToolCatalog()
     const names = catalog.flatMap(entry => entry.schemas.map(s => s.name)).sort()
-    expect(names).toEqual(['ask_user_question', 'bash', 'bash_kill', 'bash_output', 'cordis_inspect', 'cordis_mount', 'cordis_unmount', 'edit', 'read', 'run_code', 'subagent', 'todo_write', 'web_fetch', 'web_search', 'workflow', 'write'])
+    expect(names).toEqual(['ask_user_question', 'bash', 'bash_kill', 'bash_output', 'cordis_inspect', 'cordis_mount', 'cordis_unmount', 'edit', 'read', 'run_code', 'skill', 'subagent', 'todo_write', 'web_fetch', 'web_search', 'workflow', 'write'])
     // Every tool carries a JSON-Schema `parameters` object (what the model sees).
     for (const entry of catalog) {
       for (const schema of entry.schemas) {

packages/skill/README.md

@@ -0,0 +1,11 @@
+# skill/ - skill capability family
+
+The canonical three-package capability seam for reusable agent instructions: a provider registry, a local implementation, and the model-facing catalog/loader consumer. All are **product** packages.
+
+| Package | Role | ctx key |
+|---|---|---|
+| `skill/` | Provider registry, precedence resolution, stable catalog snapshots, and full-definition lookup | `ctx.skills` |
+| `skill-local/` | Project/custom/user filesystem provider | (registers on `ctx.skills`) |
+| `tool-skill/` | Session-prefix catalog and model-facing `skill` loader | (registers on `ctx.tools`) |
+
+The interface lives at `skill/skill/`. Providers register synchronously and perform asynchronous discovery through `ctx.skills`; `tool-skill` consumes only that interface, so an embedded or remote provider can replace or complement `skill-local` without changing the model-facing contract. `agent-core` loads this family by default, but it remains a capability outside the core control spine, parallel to [`bash/`](../bash/README.md), [`fs/`](../fs/README.md), [`web/`](../web/README.md), and [`subagent/`](../subagent/README.md).

packages/skill/skill-local/README.md

@@ -0,0 +1,37 @@
+# @deepseek-ai/dsh-skill-local
+
+Local filesystem provider for the `ctx.skills` registry.
+
+This package implements one skill source. It scans local project, custom, and user skill roots, parses `SKILL.md` or flat Markdown skill files, and registers the provider on `ctx.skills`. The registry remains in `@deepseek-ai/dsh-skill`; the session-prefix catalog and model-facing loader tool remain in `@deepseek-ai/dsh-tool-skill`.
+
+## Plugin
+
+Requires `ctx.skills` (`inject: ['skills']`).
+
+### Config
+
+| Field | Default | Meaning |
+|---|---|---|
+| `dshHome` | `$DSH_HOME` or `~/.dsh` | DeepSeek Harness config root; scans `skills` under this directory. |
+| `agentsHome` | `$DSH_AGENTS_HOME` or `~/.agents` | Shared agent config root scanned for compatible skills. |
+| `customSkillDirs` | `[]` | Additional local skill roots scanned after project roots and before user roots. |
+
+## Discovery
+
+Default roots are resolved in this provider's rank order:
+
+| Rank | Source | Path |
+|---|---|---|
+| 100 | `project-dsh` | `<projectRoot>/.dsh/skills` |
+| 200 | `project-agents` | `<projectRoot>/.agents/skills` |
+| 300 | `custom` | `Config.customSkillDirs` |
+| 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.
+
+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.
+
+## Skill Format
+
+Skills can be single-level directory bundles (`<name>/SKILL.md`) or flat Markdown files (`<name>.md`). Nested `**/SKILL.md` discovery is intentionally not part of v1. Frontmatter is parsed as YAML with the `yaml` package; it requires `name` and `description`, while `whenToUse`, `disableModelInvocation`, and `metadata` are optional. Names must be kebab-case.

packages/skill/skill-local/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@deepseek-ai/dsh-skill-local",
+  "description": "Local filesystem skill provider for the DeepSeek Harness",
+  "version": "0.0.1",
+  "private": true,
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/types/**/*.d.ts",
+    "lib/types/**/*.d.ts.map",
+    "src"
+  ],
+  "license": "BSD-3-Clause",
+  "peerDependencies": {
+    "@deepseek-ai/dsh-fs": "^0.0.1",
+    "@deepseek-ai/dsh-skill": "^0.0.1",
+    "cordis": "^4.0.0-rc.6"
+  },
+  "dependencies": {
+    "schemastery": "^3.18.0",
+    "yaml": "^2.4.2"
+  },
+  "devDependencies": {
+    "@deepseek-ai/dsh-fs": "workspace:^",
+    "@deepseek-ai/dsh-skill": "workspace:^",
+    "cordis": "^4.0.0-rc.6"
+  }
+}

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

@@ -0,0 +1,424 @@
+/**
+ * Local filesystem skill provider.
+ *
+ * This package is one implementation of the `ctx.skills` provider registry. It
+ * discovers directory-bundle and flat Markdown skills from project, custom, and
+ * user roots, parses YAML frontmatter, and loads bodies through `ctx.fs` when a
+ * filesystem service is present.
+ *
+ * @module @deepseek-ai/dsh-skill-local
+ */
+
+import { access, readdir, readFile, stat } from 'node:fs/promises'
+import { dirname, join, resolve } from 'node:path'
+import { homedir } from 'node:os'
+import type { Context } from 'cordis'
+import z from 'schemastery'
+import type Schema from 'schemastery'
+import { parse as parseYaml } from 'yaml'
+import type { FileSystem, FsDirEntry, FsTarget } from '@deepseek-ai/dsh-fs'
+import {
+  isSkillName,
+  type SkillCandidate,
+  type SkillDefinition,
+  type SkillLookupOptions,
+  type SkillProvider,
+  type SkillSource,
+} from '@deepseek-ai/dsh-skill'
+
+const PROJECT_DSH_RANK = 100
+const PROJECT_AGENTS_RANK = 200
+const CUSTOM_RANK = 300
+const USER_DSH_RANK = 400
+const USER_AGENTS_RANK = 500
+
+export const name = 'skill-local'
+export const inject = ['skills']
+
+/** Local filesystem skill provider configuration. */
+export interface Config {
+  /** DeepSeek Harness config root. Defaults to `$DSH_HOME` or `~/.dsh`. */
+  dshHome?: string
+  /** Shared agent config root. Defaults to `$DSH_AGENTS_HOME` or `~/.agents`. */
+  agentsHome?: string
+  /** Additional skill roots scanned after project roots and before user roots. */
+  customSkillDirs?: string[]
+}
+
+export const Config: Schema<Config> = z.object({
+  dshHome: z.string(),
+  agentsHome: z.string(),
+  customSkillDirs: z.array(z.string()).default([]),
+})
+
+interface SkillRoot {
+  path: string
+  source: SkillSource
+  rank: number
+  skipSystem?: boolean
+}
+
+interface SkillRootEntry {
+  name: string
+  type: 'directory' | 'file' | 'other'
+  path: string
+}
+
+interface ParsedSkill {
+  name: string
+  description: string
+  whenToUse?: string
+  disableModelInvocation?: boolean
+  metadata?: Record<string, unknown>
+  content: string
+}
+
+interface LocalLocator {
+  path: string
+  directory: string
+}
+
+/** Register the local filesystem skill provider on `ctx.skills`. */
+export function apply(ctx: Context, config: Config = {}): void {
+  const provider = new LocalSkillProvider(ctx, config)
+  ctx.skills.registerProvider(provider)
+}
+
+/** Provider that maps local project/user skill roots into `ctx.skills`. */
+export class LocalSkillProvider implements SkillProvider {
+  readonly name = 'local'
+  private readonly dshHome: string
+  private readonly agentsHome: string
+  private readonly customSkillDirs: string[]
+
+  constructor(private readonly ctx: Context, config: Config = {}) {
+    this.dshHome = resolve(config.dshHome ?? process.env.DSH_HOME ?? join(homedir(), '.dsh'))
+    this.agentsHome = resolve(config.agentsHome ?? process.env.DSH_AGENTS_HOME ?? join(homedir(), '.agents'))
+    this.customSkillDirs = (config.customSkillDirs ?? []).map(root => resolve(root))
+  }
+
+  /**
+   * Discover local skill summaries for a cwd-sensitive workspace.
+   * @param options - lookup options; `cwd` selects the project roots to scan.
+   * @returns local provider candidates with stable root ranks.
+   */
+  async list(options: SkillLookupOptions): Promise<SkillCandidate[]> {
+    const roots = await this.roots(options.cwd)
+    const candidates: SkillCandidate[] = []
+    for (const root of roots) {
+      for (const skill of await discoverRoot(root, this.ctx)) {
+        candidates.push(skill)
+      }
+    }
+    return candidates
+  }
+
+  /**
+   * Load a complete local skill body from the candidate's file locator.
+   * @param candidate - the winning candidate returned by this provider.
+   * @param options - lookup options whose signal cancels filesystem reads.
+   * @returns the full local skill, or `undefined` if the file disappeared.
+   */
+  async get(candidate: SkillCandidate, options: SkillLookupOptions): Promise<SkillDefinition | undefined> {
+    const locator = candidate.locator as LocalLocator
+    const parsed = await parseSkillFile(locator.path, this.ctx, options.signal)
+    if (parsed === undefined) return undefined
+    return {
+      name: parsed.name,
+      description: parsed.description,
+      ...parsed.whenToUse !== undefined ? { whenToUse: parsed.whenToUse } : {},
+      ...parsed.disableModelInvocation !== undefined ? { disableModelInvocation: parsed.disableModelInvocation } : {},
+      source: candidate.source,
+      provider: this.name,
+      resourceBase: { kind: 'directory', path: locator.directory },
+      path: locator.path,
+      ...parsed.metadata !== undefined ? { metadata: parsed.metadata } : {},
+      content: parsed.content,
+    }
+  }
+
+  private async roots(cwd: string | undefined): Promise<SkillRoot[]> {
+    const roots: SkillRoot[] = []
+    if (cwd !== undefined) {
+      const projectRoot = await findProjectRoot(resolve(cwd), optionalFileSystem(this.ctx))
+      roots.push(
+        { path: join(projectRoot, '.dsh/skills'), source: 'project-dsh', rank: PROJECT_DSH_RANK },
+        { path: join(projectRoot, '.agents/skills'), source: 'project-agents', rank: PROJECT_AGENTS_RANK },
+      )
+    }
+    roots.push(
+      ...this.customSkillDirs.map(path => ({ path, source: 'custom' as const, rank: CUSTOM_RANK })),
+      { path: join(this.dshHome, 'skills'), source: 'user-dsh', rank: USER_DSH_RANK, skipSystem: true },
+      { path: join(this.agentsHome, 'skills'), source: 'user-agents', rank: USER_AGENTS_RANK },
+    )
+    return roots
+  }
+}
+
+async function discoverRoot(root: SkillRoot, ctx: Context): Promise<SkillCandidate[]> {
+  const skills: SkillCandidate[] = []
+  const entries = await listSkillRootEntries(root, ctx)
+  for (const entry of entries.sort((a, b) => a.name.localeCompare(b.name))) {
+    if (root.skipSystem && entry.name === '.system') continue
+    const locator = entry.type === 'directory'
+      ? { path: join(entry.path, 'SKILL.md'), directory: entry.path }
+      : entry.type === 'file' && entry.name.endsWith('.md')
+        ? { path: entry.path, directory: root.path }
+        : undefined
+    if (locator === undefined) continue
+    const parsed = await parseSkillFile(locator.path, ctx)
+    if (parsed === undefined) continue
+    skills.push({
+      name: parsed.name,
+      description: parsed.description,
+      ...parsed.whenToUse !== undefined ? { whenToUse: parsed.whenToUse } : {},
+      ...parsed.disableModelInvocation !== undefined ? { disableModelInvocation: parsed.disableModelInvocation } : {},
+      provider: 'local',
+      source: root.source,
+      rank: root.rank,
+      locator,
+      resourceBase: { kind: 'directory', path: locator.directory },
+      path: locator.path,
+      ...parsed.metadata !== undefined ? { metadata: parsed.metadata } : {},
+    })
+  }
+  return skills
+}
+
+async function listSkillRootEntries(root: SkillRoot, ctx: Context): Promise<SkillRootEntry[]> {
+  const fs = optionalFileSystem(ctx)
+  if (fs !== undefined) return await listSkillRootEntriesFromFileSystem(root, fs)
+  return await listSkillRootEntriesFromNode(root, ctx)
+}
+
+async function listSkillRootEntriesFromFileSystem(root: SkillRoot, fs: FileSystem): Promise<SkillRootEntry[]> {
+  // Skill roots are optional; an absent or unlistable root contributes no skills.
+  const entries = await fsListDir(fs, root.path).catch(() => undefined)
+  return entries === undefined ? [] : entries.map(entryFromFs)
+}
+
+async function fsListDir(fs: FileSystem, path: string): Promise<FsDirEntry[]> {
+  const target = await fs.resolve(path)
+  return await fs.listDir(target)
+}
+
+function entryFromFs(entry: FsDirEntry): SkillRootEntry {
+  return { name: entry.name, type: entry.type, path: entry.target.displayPath }
+}
+
+async function listSkillRootEntriesFromNode(root: SkillRoot, ctx: Context): Promise<SkillRootEntry[]> {
+  let entries
+  try {
+    entries = await readdir(root.path, { withFileTypes: true, encoding: 'utf8' })
+  } catch {
+    // Missing or unreadable local skill roots are expected in most deployments.
+    return []
+  }
+
+  const result: SkillRootEntry[] = []
+  for (const entry of entries) {
+    const path = join(root.path, entry.name)
+    const type = await nodeEntryKind(path, entry, ctx)
+    result.push({ name: entry.name, type: type ?? 'other', path })
+  }
+  return result
+}
+
+async function parseSkillFile(path: string, ctx: Context, signal?: AbortSignal): Promise<ParsedSkill | undefined> {
+  const raw = await readSkillText(ctx, path, signal)
+  signal?.throwIfAborted()
+  if (raw === undefined) {
+    return undefined
+  }
+  let parsed
+  try {
+    parsed = parseFrontmatter(raw)
+  } catch (error) {
+    ctx.logger.warn(`skill file ${path} ignored: invalid YAML frontmatter: ${errorMessage(error)}`)
+    return undefined
+  }
+  if (!parsed) {
+    ctx.logger.warn(`skill file ${path} ignored: missing YAML frontmatter`)
+    return undefined
+  }
+  const name = stringField(parsed.data, 'name')
+  const description = stringField(parsed.data, 'description')
+  if (name === undefined || description === undefined) {
+    ctx.logger.warn(`skill file ${path} ignored: frontmatter requires name and description`)
+    return undefined
+  }
+  if (!isSkillName(name)) {
+    ctx.logger.warn(`skill file ${path} ignored: invalid skill name "${name}"`)
+    return undefined
+  }
+  return {
+    name,
+    description,
+    ...optionalString(parsed.data, 'whenToUse'),
+    ...optionalBoolean(parsed.data, 'disableModelInvocation'),
+    ...optionalMetadata(parsed.data),
+    content: parsed.body.trim(),
+  }
+}
+
+function optionalFileSystem(ctx: Context): FileSystem | undefined {
+  return ctx.get('fs')
+}
+
+async function readSkillText(ctx: Context, path: string, signal?: AbortSignal): Promise<string | undefined> {
+  signal?.throwIfAborted()
+  const fs = optionalFileSystem(ctx)
+  if (fs !== undefined) {
+    return await readSkillTextFromFileSystem(ctx, fs, path, signal)
+  }
+  try {
+    return await readFile(path, { encoding: 'utf8', signal })
+  } catch {
+    signal?.throwIfAborted()
+    return undefined
+  }
+}
+
+async function readSkillTextFromFileSystem(ctx: Context, fs: FileSystem, path: string, signal?: AbortSignal): Promise<string | undefined> {
+  // A missing or temporarily inaccessible skill file is not fatal to discovery.
+  signal?.throwIfAborted()
+  const target = await fs.resolve(path).catch(() => undefined)
+  signal?.throwIfAborted()
+  if (target === undefined) return undefined
+  let info
+  try {
+    info = await fs.stat(target, signal)
+  } catch (error) {
+    signal?.throwIfAborted()
+    ctx.logger.warn(`skill file ${path} ignored: failed to stat through filesystem service: ${errorMessage(error)}`)
+    return undefined
+  }
+  if (info === undefined || info.type !== 'file') return undefined
+  try {
+    return await fs.readText(target, signal)
+  } catch (error) {
+    signal?.throwIfAborted()
+    ctx.logger.warn(`skill file ${path} ignored: ${fsReadErrorMessage(target, error)}`)
+    return undefined
+  }
+}
+
+function fsReadErrorMessage(target: FsTarget, error: unknown): string {
+  return `failed to read text file at ${target.displayPath}: ${errorMessage(error)}`
+}
+
+async function nodeEntryKind(fullPath: string, entry: { isDirectory(): boolean; isFile(): boolean; isSymbolicLink(): boolean }, ctx: Context): Promise<'directory' | 'file' | undefined> {
+  if (entry.isDirectory()) return 'directory'
+  if (entry.isFile()) return 'file'
+  /* v8 ignore next -- Non-file directory entries such as FIFOs are platform-specific and intentionally skipped. */
+  if (!entry.isSymbolicLink()) return undefined
+  try {
+    const info = await stat(fullPath)
+    if (info.isDirectory()) return 'directory'
+    if (info.isFile()) return 'file'
+    return undefined
+  } catch (error) {
+    ctx.logger.warn(`skill entry ${fullPath} ignored: failed to follow symbolic link: ${errorMessage(error)}`)
+    return undefined
+  }
+}
+
+function parseFrontmatter(raw: string): { data: Record<string, unknown>; body: string } | undefined {
+  const firstLineEnd = raw.indexOf('\n')
+  if (firstLineEnd < 0) return undefined
+  const firstLine = raw.slice(0, firstLineEnd).replace(/\r$/, '')
+  if (firstLine !== '---') return undefined
+  const start = firstLineEnd + 1
+  const closing = findClosingFrontmatter(raw, start)
+  if (closing === undefined) return undefined
+  const yaml = raw.slice(start, closing.start)
+  const parsed = parseYaml(yaml) as unknown
+  if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) return undefined
+  return { data: parsed as Record<string, unknown>, body: raw.slice(closing.bodyStart) }
+}
+
+function findClosingFrontmatter(raw: string, start: number): { start: number; bodyStart: number } | undefined {
+  let lineStart = start
+  while (lineStart <= raw.length) {
+    const nextNewline = raw.indexOf('\n', lineStart)
+    const lineEnd = nextNewline < 0 ? raw.length : nextNewline
+    const line = raw.slice(lineStart, lineEnd).replace(/\r$/, '')
+    if (line === '---') {
+      return { start: lineStart, bodyStart: nextNewline < 0 ? raw.length : nextNewline + 1 }
+    }
+    if (nextNewline < 0) return undefined
+    lineStart = nextNewline + 1
+  }
+}
+
+async function findProjectRoot(cwd: string, fs: FileSystem | undefined): Promise<string> {
+  let current = cwd
+  while (true) {
+    if (await pathExists(join(current, '.git'), fs)) {
+      return current
+    }
+    const parent = dirname(current)
+    if (parent === current) return cwd
+    current = parent
+  }
+}
+
+async function pathExists(path: string, fs: FileSystem | undefined): Promise<boolean> {
+  if (fs !== undefined) {
+    return await pathExistsInFileSystem(path, fs)
+  }
+  return await pathExistsInNode(path)
+}
+
+async function pathExistsInFileSystem(path: string, fs: FileSystem): Promise<boolean> {
+  let target
+  try {
+    target = await fs.resolve(path)
+  } catch {
+    // A backend may reject or hide this candidate; continue walking upward.
+    return false
+  }
+  try {
+    return await fs.stat(target) !== undefined
+  } catch {
+    // Transient stat failures make only this git-root candidate unusable.
+    return false
+  }
+}
+
+async function pathExistsInNode(path: string): Promise<boolean> {
+  try {
+    await access(path)
+    return true
+  } catch {
+    // Missing host paths are expected while walking toward the filesystem root.
+    return false
+  }
+}
+
+function stringField(data: Record<string, unknown>, key: string): string | undefined {
+  const value = data[key]
+  return typeof value === 'string' && value.length > 0 ? value : undefined
+}
+
+function optionalString(data: Record<string, unknown>, key: string): { [K in typeof key]?: string } {
+  const value = data[key]
+  return typeof value === 'string' && value.length > 0 ? { [key]: value } : {}
+}
+
+function optionalBoolean(data: Record<string, unknown>, key: string): { [K in typeof key]?: boolean } {
+  const value = data[key]
+  return typeof value === 'boolean' ? { [key]: value } : {}
+}
+
+function optionalMetadata(data: Record<string, unknown>): { metadata?: Record<string, unknown> } {
+  const value = data.metadata
+  if (typeof value === 'object' && value !== null && !Array.isArray(value)) {
+    return { metadata: value as Record<string, unknown> }
+  }
+  return {}
+}
+
+function errorMessage(error: unknown): string {
+  return String(error)
+}

packages/skill/skill-local/tests/skill-local.spec.ts

@@ -0,0 +1,393 @@
+import { describe, expect, it } from 'vitest'
+import { mkdir, readdir, readFile, stat, symlink, writeFile } from 'node:fs/promises'
+import { dirname, join } from 'node:path'
+import { tmpdir } from 'node:os'
+import { Context } from 'cordis'
+import SkillService from '@deepseek-ai/dsh-skill'
+import { FileSystem, FsVersion, type FsDirEntry, type FsEditOutcome, type FsEditRequest, type FsInfo, type FsTarget, type FsWriteOutcome } from '@deepseek-ai/dsh-fs'
+import * as SkillLocal from '../src/index.ts'
+
+async function tempDir(name: string): Promise<string> {
+  return await import('node:fs/promises').then(fs => fs.mkdtemp(join(tmpdir(), `dsh-${name}-`)))
+}
+
+async function writeSkill(root: string, name: string, description: string, body = 'Use the skill.'): Promise<void> {
+  const dir = join(root, name)
+  await mkdir(dir, { recursive: true })
+  await writeFile(join(dir, 'SKILL.md'), `---\nname: ${name}\ndescription: ${description}\n---\n\n${body}\n`)
+}
+
+async function writeFlatSkill(root: string, name: string, description: string, body = 'Flat body.'): Promise<void> {
+  await mkdir(root, { recursive: true })
+  await writeFile(join(root, `${name}.md`), `---\nname: ${name}\ndescription: ${description}\n---\n\n${body}\n`)
+}
+
+class TestFileSystem extends FileSystem {
+  listDirCalls = 0
+  failResolvePaths = new Set<string>()
+  failStatPaths = new Set<string>()
+  statOverrides = new Map<string, FsInfo | undefined>()
+  statSignals: Array<AbortSignal | undefined> = []
+  readTextSignals: Array<AbortSignal | undefined> = []
+  readTextOverride?: (target: FsTarget, signal?: AbortSignal) => Promise<string>
+
+  override async resolve(path: string): Promise<FsTarget> {
+    if (this.failResolvePaths.has(path)) throw new Error('resolve failed')
+    return { targetKey: path as never, displayPath: path }
+  }
+
+  override async stat(target: FsTarget, signal?: AbortSignal): Promise<FsInfo | undefined> {
+    this.statSignals.push(signal)
+    if (this.failStatPaths.has(target.displayPath)) throw new Error('stat failed')
+    if (this.statOverrides.has(target.displayPath)) return this.statOverrides.get(target.displayPath)
+    try {
+      const fs = await import('node:fs/promises')
+      const info = await fs.stat(target.displayPath)
+      return {
+        version: FsVersion(String(info.mtimeMs)),
+        type: info.isFile() ? 'file' : info.isDirectory() ? 'directory' : 'other',
+        size: info.size,
+      }
+    } catch {
+      return undefined
+    }
+  }
+
+  override async readText(target: FsTarget, signal?: AbortSignal): Promise<string> {
+    this.readTextSignals.push(signal)
+    if (this.readTextOverride !== undefined) return await this.readTextOverride(target, signal)
+    const text = await readFile(target.displayPath, 'utf8')
+    if (text.includes('\uFFFD')) throw new Error('not text')
+    return text
+  }
+
+  override async streamText(_target: FsTarget): Promise<AsyncIterable<string>> {
+    throw new Error('not needed in skill tests')
+  }
+
+  override async listDir(target: FsTarget): Promise<FsDirEntry[]> {
+    this.listDirCalls += 1
+    const entries = await readdir(target.displayPath, { withFileTypes: true, encoding: 'utf8' })
+    const result: FsDirEntry[] = []
+    for (const entry of entries.sort((left, right) => left.name.localeCompare(right.name))) {
+      const childPath = join(target.displayPath, entry.name)
+      let type: FsInfo['type'] = 'other'
+      let size: number | undefined
+      try {
+        const info = await stat(childPath)
+        type = info.isFile() ? 'file' : info.isDirectory() ? 'directory' : 'other'
+        size = info.isFile() ? info.size : undefined
+      } catch {
+        type = 'other'
+      }
+      result.push({
+        name: entry.name,
+        type,
+        target: { targetKey: childPath as never, displayPath: childPath },
+        version: FsVersion('test'),
+        ...(size !== undefined ? { size } : {}),
+      })
+    }
+    return result
+  }
+
+  override async writeText(target: FsTarget, content: string): Promise<FsWriteOutcome> {
+    await mkdir(dirname(target.displayPath), { recursive: true })
+    await writeFile(target.displayPath, content)
+    return { operation: 'create', version: FsVersion('test'), before: null, after: content }
+  }
+
+  override async editText(_target: FsTarget, _request: FsEditRequest): Promise<FsEditOutcome> {
+    throw new Error('not needed in skill tests')
+  }
+}
+
+async function setupLocal(home: string, config: Partial<SkillLocal.Config> = {}): Promise<Context> {
+  const ctx = new Context()
+  await ctx.plugin(SkillService)
+  await ctx.plugin(SkillLocal, {
+    dshHome: join(home, '.dsh'),
+    agentsHome: join(home, '.agents'),
+    ...config,
+  })
+  return ctx
+}
+
+describe('dsh-skill-local plugin exports', () => {
+  it('declares stable plugin metadata', () => {
+    expect(SkillLocal.name).toBe('skill-local')
+    expect(SkillLocal.inject).toEqual(['skills'])
+  })
+})
+
+describe('LocalSkillProvider', () => {
+  it('discovers project, custom, user, and agents skill roots in priority order', async () => {
+    const home = await tempDir('skill-home')
+    const project = await tempDir('skill-project')
+    const custom = await tempDir('skill-custom')
+    await mkdir(join(project, '.git'), { recursive: true })
+
+    await writeSkill(join(home, '.agents/skills'), 'same', 'user agents skill')
+    await writeSkill(join(home, '.dsh/skills'), 'same', 'user dsh skill')
+    await writeSkill(custom, 'same', 'custom skill')
+    await writeSkill(join(project, '.agents/skills'), 'same', 'project agents skill')
+    await writeSkill(join(project, '.dsh/skills'), 'same', 'project dsh skill')
+    await writeSkill(custom, 'custom-only', 'custom only')
+    await writeSkill(join(home, '.dsh/skills/.system'), 'hidden-system', 'hidden system')
+
+    const ctx = await setupLocal(home, { customSkillDirs: [custom] })
+
+    const skills = await ctx.skills.list({ cwd: join(project, 'src') })
+    expect(skills.map(skill => [skill.name, skill.description])).toEqual([
+      ['custom-only', 'custom only'],
+      ['same', 'project dsh skill'],
+    ])
+    expect(skills.find(skill => skill.name === 'same')?.source).toBe('project-dsh')
+    expect(skills.find(skill => skill.name === 'hidden-system')).toBeUndefined()
+
+    const noGit = await tempDir('skill-no-git')
+    await writeSkill(join(noGit, '.dsh/skills'), 'fallback-root', 'Fallback root')
+    expect((await ctx.skills.list({ cwd: noGit })).map(skill => skill.name)).toContain('fallback-root')
+  })
+
+  it('lets project skills override runtime while runtime overrides custom and user skills', async () => {
+    const home = await tempDir('skill-runtime-priority')
+    const project = await tempDir('skill-runtime-project')
+    const custom = await tempDir('skill-runtime-custom')
+    await mkdir(join(project, '.git'), { recursive: true })
+
+    await writeSkill(join(project, '.dsh/skills'), 'project-name', 'Project wins')
+    await writeSkill(custom, 'runtime-name', 'Custom loses')
+    await writeSkill(join(home, '.dsh/skills'), 'runtime-name', 'User loses')
+
+    const ctx = await setupLocal(home, { customSkillDirs: [custom] })
+    ctx.skills.register({
+      name: 'project-name',
+      description: 'Runtime loses to project',
+      content: 'Runtime body.',
+      source: 'runtime',
+    })
+    ctx.skills.register({
+      name: 'runtime-name',
+      description: 'Runtime wins',
+      content: 'Runtime body.',
+      source: 'runtime',
+    })
+
+    expect((await ctx.skills.get('project-name', { cwd: project }))?.description).toBe('Project wins')
+    expect((await ctx.skills.get('runtime-name', { cwd: project }))?.description).toBe('Runtime wins')
+  })
+
+  it('parses flat skills and filters invalid or model-disabled skills from listing', async () => {
+    const home = await tempDir('skill-flat')
+    const root = join(home, '.dsh/skills')
+    await writeFlatSkill(root, 'flat-skill', 'flat description', 'Flat instructions.')
+    await writeFile(join(root, 'rich-skill.md'), [
+      '---',
+      'name: rich-skill',
+      'description: rich description',
+      'whenToUse: For richer local parsing',
+      'disableModelInvocation: false',
+      'metadata:',
+      '  owner: tests',
+      '---',
+      '',
+      'Rich body.',
+    ].join('\n'))
+    await writeFile(join(root, 'bad.md'), '---\nname: Bad_Name\ndescription: bad\n---\n\nbad')
+    await writeFile(join(root, 'missing-description.md'), '---\nname: missing-description\n---\n\nbad')
+    await writeFile(join(root, 'no-frontmatter.md'), 'No frontmatter.')
+    await writeFile(join(root, 'plain-markdown.md'), '# Notes\nNot a skill.')
+    await writeFile(join(root, 'open-frontmatter.md'), '---\nname: open-frontmatter')
+    await writeFile(join(root, 'non-object.md'), '---\n[]\n---\n\nbad')
+    await writeFile(join(root, 'no-trailing-body.md'), '---\nname: no-trailing-body\ndescription: No trailing body\n---')
+    await writeFile(join(root, 'notes.txt'), 'ignored')
+    await mkdir(join(root, 'not-a-skill'), { recursive: true })
+    await writeSkill(root, 'hidden-skill', 'hidden description', 'Hidden.')
+    await writeFile(join(root, 'hidden-skill/SKILL.md'), '---\nname: hidden-skill\ndescription: hidden description\ndisableModelInvocation: true\n---\n\nHidden.\n')
+
+    const ctx = await setupLocal(home)
+    const listedBeforeDelete = await ctx.skills.list()
+    const flatSummary = listedBeforeDelete.find(skill => skill.name === 'flat-skill')
+    if (flatSummary === undefined) throw new Error('expected flat-skill')
+    await writeFile(join(root, 'flat-skill.md'), '')
+
+    expect(listedBeforeDelete.map(skill => skill.name)).toEqual(['flat-skill', 'no-trailing-body', 'rich-skill'])
+    expect(await ctx.skills.get('flat-skill')).toBeUndefined()
+    expect((await ctx.skills.get('hidden-skill'))?.content).toContain('Hidden.')
+    expect(await ctx.skills.get('rich-skill')).toMatchObject({
+      whenToUse: 'For richer local parsing',
+      disableModelInvocation: false,
+      metadata: { owner: 'tests' },
+    })
+    expect(await ctx.skills.get('Bad_Name')).toBeUndefined()
+  })
+
+  it('supports CRLF frontmatter and ignores delimiter-looking text inside YAML values', async () => {
+    const home = await tempDir('skill-frontmatter-crlf')
+    const root = join(home, '.dsh/skills')
+    await mkdir(root, { recursive: true })
+    await writeFile(join(root, 'crlf-skill.md'), [
+      '---',
+      'name: crlf-skill',
+      'description: CRLF skill',
+      'metadata:',
+      '  marker: "----"',
+      '---',
+      '',
+      'CRLF body.',
+    ].join('\r\n'))
+    await writeFile(join(root, 'block-skill.md'), [
+      '---',
+      'name: block-skill',
+      'description: |',
+      '  Includes a ---- marker that is not a delimiter.',
+      '---',
+      '',
+      'Block body.',
+    ].join('\n'))
+
+    const ctx = await setupLocal(home)
+
+    expect((await ctx.skills.get('crlf-skill'))?.content).toBe('CRLF body.')
+    expect((await ctx.skills.get('crlf-skill'))?.metadata).toEqual({ marker: '----' })
+    expect((await ctx.skills.get('block-skill'))?.description).toBe('Includes a ---- marker that is not a delimiter.\n')
+    expect((await ctx.skills.get('block-skill'))?.content).toBe('Block body.')
+  })
+
+  it('skips invalid YAML skill files without hiding valid siblings', async () => {
+    const home = await tempDir('skill-invalid-yaml')
+    const root = join(home, '.dsh/skills')
+    await writeSkill(root, 'good-skill', 'Good skill')
+    await writeFile(join(root, 'bad-yaml.md'), '---\nname: bad-yaml\ndescription: [unclosed\n---\n\nBad body.\n')
+
+    const ctx = await setupLocal(home)
+
+    expect((await ctx.skills.list()).map(skill => skill.name)).toEqual(['good-skill'])
+  })
+
+  it('discovers symlinked skill directories and flat files', async () => {
+    const home = await tempDir('skill-symlink-home')
+    const external = await tempDir('skill-symlink-external')
+    await writeSkill(external, 'linked-dir', 'Linked directory')
+    await writeFlatSkill(external, 'linked-flat', 'Linked flat')
+    await mkdir(join(home, '.dsh/skills'), { recursive: true })
+    await symlink(join(external, 'linked-dir'), join(home, '.dsh/skills/linked-dir'))
+    await symlink(join(external, 'linked-flat.md'), join(home, '.dsh/skills/linked-flat.md'))
+    await symlink(join(external, 'missing'), join(home, '.dsh/skills/broken-link'))
+    await symlink('/dev/null', join(home, '.dsh/skills/device-link'))
+
+    const ctx = await setupLocal(home)
+
+    expect((await ctx.skills.list()).map(skill => skill.name)).toEqual(['linked-dir', 'linked-flat'])
+  })
+
+  it('uses the filesystem service for discovery, reads, and project-root lookup', async () => {
+    const home = await tempDir('skill-read-fs')
+    const project = await tempDir('skill-project-root-backend')
+    const nestedCwd = join(project, 'packages/app')
+    const root = join(home, '.dsh/skills')
+    await mkdir(nestedCwd, { recursive: true })
+    await writeFlatSkill(root, 'text-skill', 'Text skill', 'Text body.')
+    await writeFlatSkill(root, 'resolve-fail', 'Resolve fail', 'Resolve body.')
+    await writeFlatSkill(root, 'stat-fail', 'Stat fail', 'Stat body.')
+    await mkdir(join(root, 'empty-dir'), { recursive: true })
+    await mkdir(join(root, 'directory-skill/SKILL.md'), { recursive: true })
+    await writeFile(join(root, 'binary-skill.md'), Buffer.concat([
+      Buffer.from('---\nname: binary-skill\ndescription: Binary skill\n---\n\n'),
+      Buffer.from([0xff]),
+      Buffer.from('\n'),
+    ]))
+    await writeSkill(join(project, '.agents/skills'), 'backend-root', 'Backend root skill')
+
+    const ctx = new Context()
+    await ctx.plugin(TestFileSystem)
+    const fs = ctx.fs as TestFileSystem
+    fs.failResolvePaths.add(join(root, 'resolve-fail.md'))
+    fs.failStatPaths.add(join(root, 'stat-fail.md'))
+    fs.failResolvePaths.add(join(nestedCwd, '.git'))
+    fs.failStatPaths.add(join(project, 'packages/.git'))
+    fs.statOverrides.set(join(project, '.git'), {
+      version: FsVersion('virtual-git'),
+      type: 'directory',
+      size: 0,
+    })
+    await ctx.plugin(SkillService)
+    await ctx.plugin(SkillLocal, { dshHome: join(home, '.dsh'), agentsHome: join(home, '.agents') })
+
+    expect((await ctx.skills.list({ cwd: nestedCwd })).map(skill => [skill.name, skill.source])).toEqual([
+      ['backend-root', 'project-agents'],
+      ['text-skill', 'user-dsh'],
+    ])
+    expect(fs.listDirCalls).toBeGreaterThan(0)
+    expect(await ctx.skills.get('binary-skill')).toBeUndefined()
+  })
+
+  it('forwards cancellation to filesystem reads while loading a skill', async () => {
+    const home = await tempDir('skill-read-abort')
+    await writeSkill(join(home, '.dsh/skills'), 'abortable-skill', 'Abortable skill')
+
+    const ctx = new Context()
+    await ctx.plugin(TestFileSystem)
+    const fs = ctx.fs as TestFileSystem
+    await ctx.plugin(SkillService)
+    await ctx.plugin(SkillLocal, { dshHome: join(home, '.dsh'), agentsHome: join(home, '.agents') })
+    expect((await ctx.skills.list()).map(skill => skill.name)).toEqual(['abortable-skill'])
+
+    fs.statSignals = []
+    fs.readTextSignals = []
+    const started = Promise.withResolvers<undefined>()
+    fs.readTextOverride = async (_target, signal) => {
+      if (signal === undefined) throw new Error('expected the skill lookup signal')
+      started.resolve(undefined)
+      return await new Promise<string>((_resolve, reject) => {
+        signal.addEventListener('abort', () => {
+          const abortReason = signal.reason as unknown
+          reject(abortReason instanceof Error ? abortReason : new Error(String(abortReason)))
+        }, { once: true })
+      })
+    }
+    const controller = new AbortController()
+    const reason = new Error('turn cancelled')
+    const loading = ctx.skills.get('abortable-skill', { signal: controller.signal })
+    await started.promise
+    controller.abort(reason)
+
+    await expect(loading).rejects.toBe(reason)
+    expect(fs.statSignals).toEqual([controller.signal])
+    expect(fs.readTextSignals).toEqual([controller.signal])
+  })
+
+  it('uses default home root resolution without exposing builtin skills', async () => {
+    const previousDshHome = process.env.DSH_HOME
+    const previousAgentsHome = process.env.DSH_AGENTS_HOME
+    const envHome = await tempDir('skill-env-home')
+    try {
+      process.env.DSH_HOME = join(envHome, '.dsh')
+      process.env.DSH_AGENTS_HOME = join(envHome, '.agents')
+      await writeSkill(join(envHome, '.dsh/skills'), 'env-skill', 'Env skill')
+      const ctx = new Context()
+      await ctx.plugin(SkillService)
+      await ctx.plugin(SkillLocal)
+      expect((await ctx.skills.list()).map(skill => skill.name)).toEqual(['env-skill'])
+
+      process.env.DSH_HOME = join(envHome, 'empty-dsh')
+      process.env.DSH_AGENTS_HOME = join(envHome, 'empty-agents')
+      const empty = new Context()
+      await empty.plugin(SkillService)
+      SkillLocal.apply(empty, {})
+      expect(await empty.skills.list()).toEqual([])
+    } finally {
+      if (previousDshHome === undefined) {
+        delete process.env.DSH_HOME
+      } else {
+        process.env.DSH_HOME = previousDshHome
+      }
+      if (previousAgentsHome === undefined) {
+        delete process.env.DSH_AGENTS_HOME
+      } else {
+        process.env.DSH_AGENTS_HOME = previousAgentsHome
+      }
+    }
+  })
+})

packages/skill/skill-local/tsconfig.json

@@ -0,0 +1,15 @@
+{
+  "extends": "../../../tsconfig.base.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "lib/types"
+  },
+  "include": ["src"],
+  "references": [
+    { "path": "../../../vendor/cosmokit" },
+    { "path": "../../../vendor/cordis" },
+    { "path": "../../../vendor/schemastery" },
+    { "path": "../../fs/fs" },
+    { "path": "../skill" }
+  ]
+}

packages/skill/skill/README.md

@@ -0,0 +1,34 @@
+# @deepseek-ai/dsh-skill
+
+Pure agent skill provider registry.
+
+This package owns the `ctx.skills` interface. It does not know whether skills come from local files, embedded plugin data, HTTP, or another backend; providers register those sources with `ctx.skills.registerProvider(...)`. The shipped local implementation is [`@deepseek-ai/dsh-skill-local`](../skill-local).
+
+## Service: `SkillService` (ctx key: `skills`)
+
+### Public API
+
+- `ctx.skills.registerProvider(provider): () => void` Registers a provider by unique `provider.name`. Duplicate provider names throw, and `runtime` is reserved for `ctx.skills.register(...)`. The registration is effect-scoped and HMR-safe.
+- `ctx.skills.list({ cwd?, signal? })` Returns model-invocable skill summaries for the current workspace, merged across providers and sorted by name.
+- `ctx.skills.get(name, { cwd?, signal? })` Returns the full winning skill, including disabled-for-model skills.
+- `ctx.skills.register(skill): () => void` Registers a runtime embedded skill. Same-name runtime registrations are first-wins: a duplicate logs a warning and gets a no-op disposer.
+
+### Config
+
+| Field | Default | Meaning |
+|---|---|---|
+| `collectCacheMaxEntries` | `128` | Maximum completed cwd/provider catalog snapshots kept in memory. |
+
+## Provider Contract
+
+A provider registers synchronously from its `apply()` and returns `SkillCandidate[]` from `list(options)` when discovery is requested. Remote setup, authentication, and discovery belong in the awaited `list()` call rather than plugin registration. Providers should stop promptly when `options.signal` aborts; the registry also stops awaiting an uncooperative provider so agent cancellation cannot hang prefix composition. The provider later receives the winning candidate back in `get(candidate, options)`. The candidate's `locator` is opaque to the registry, so a local provider can store a file path while a remote provider can store a URL, id, or version token.
+
+The registry validates candidate names, descriptions, ranks, and provider ownership. Candidate contract violations fail fast because the provider plugin is malformed; a provider `list()` rejection is treated as a transient source failure, logged, skipped for that request, and not cached. Only completed catalogs are cached, and a provider/runtime revision change during discovery discards the stale result and retries. Duplicate skill names are resolved first-wins by `rank`, provider registration order, then the provider's own local order. The final summary list is sorted by skill `name` for deterministic consumers.
+
+## Runtime Skills
+
+`ctx.skills.register(...)` is a convenience for embedded runtime skills. Runtime skills use rank `250`: project providers can override them, while they override the shipped local provider's custom and user roots. Runtime registration is also first-wins within runtime contributions, so a duplicate contribution cannot remove the active one through its disposer.
+
+## Consumer boundary
+
+The registry does not render model guidance or register model-facing tools. [`@deepseek-ai/dsh-tool-skill`](../tool-skill) consumes `ctx.skills` to provide the session-prefix catalog and `skill` tool, so providers remain independent of the model surface.

packages/skill/skill/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@deepseek-ai/dsh-skill",
+  "description": "Agent skill provider registry for the DeepSeek Harness",
+  "version": "0.0.1",
+  "private": true,
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/types/**/*.d.ts",
+    "lib/types/**/*.d.ts.map",
+    "src"
+  ],
+  "license": "BSD-3-Clause",
+  "peerDependencies": {
+    "cordis": "^4.0.0-rc.6"
+  },
+  "dependencies": {
+    "schemastery": "^3.18.0"
+  },
+  "devDependencies": {
+    "cordis": "^4.0.0-rc.6"
+  }
+}

packages/skill/skill/src/index.ts

@@ -0,0 +1,461 @@
+/**
+ * Agent skill provider registry.
+ *
+ * This package is the interface third of the skill capability seam. Concrete
+ * providers such as `@deepseek-ai/dsh-skill-local` decide where skills come
+ * from; this service only merges provider catalogs, resolves the winning skill
+ * for a name, and exposes the winning summaries and definitions to consumers.
+ *
+ * @module @deepseek-ai/dsh-skill
+ */
+
+import { Context, Service } from 'cordis'
+import z from 'schemastery'
+import type Schema from 'schemastery'
+
+const SKILL_NAME = /^[a-z0-9]+(?:-[a-z0-9]+)*$/
+const DEFAULT_COLLECT_CACHE_ENTRIES = 128
+const RUNTIME_PROVIDER = 'runtime'
+const RUNTIME_RANK = 250
+
+/**
+ * Return whether a string is a valid kebab-case skill name.
+ * @param name - candidate skill name to validate.
+ * @returns whether the name matches the public skill-name grammar.
+ */
+export function isSkillName(name: string): boolean {
+  return SKILL_NAME.test(name)
+}
+
+/** Origin bucket for a skill contribution. The value is prompt-visible metadata, not precedence by itself. */
+export type SkillSource = 'project-dsh' | 'project-agents' | 'runtime' | 'user-dsh' | 'user-agents' | 'custom' | (string & {})
+
+/** Optional provider-specific base used by loaded skill bodies to resolve relative resources. */
+export type SkillResourceBase =
+  | { kind: 'directory'; path: string }
+  | { kind: 'url'; url: string }
+  | { kind: 'opaque'; description: string }
+
+/** Model-visible skill metadata returned by `ctx.skills.list()` and rendered into request guidance. */
+export interface SkillSummary {
+  /** Kebab-case identifier used with the `skill` tool. */
+  name: string
+  /** Short routing description shown to the model. */
+  description: string
+  /** Optional extra routing guidance shown to the model. */
+  whenToUse?: string
+  /** Whether the skill is hidden from model listings while remaining loadable by trusted callers. */
+  disableModelInvocation?: boolean
+  /** Discovery source that produced this winning skill. */
+  source: SkillSource
+  /** Provider that owns this skill body. */
+  provider: string
+  /** Provider-specific base for relative resources. */
+  resourceBase?: SkillResourceBase
+}
+
+/** Provider catalog entry used by the registry to merge and later load skills. */
+export interface SkillCandidate extends SkillSummary {
+  /** Lower ranks win duplicate skill names before provider registration order is considered. */
+  rank: number
+  /** Opaque provider-owned handle passed back to `provider.get()`. */
+  locator: unknown
+  /** Absolute file path when the provider has one. */
+  path?: string
+  /** Parsed optional metadata object from provider-specific skill frontmatter. */
+  metadata?: Record<string, unknown>
+}
+
+/** Complete parsed skill definition, including the body loaded by `ctx.skills.get()`. */
+export interface SkillDefinition extends SkillSummary {
+  /** Markdown instruction body after any provider-specific metadata removal. */
+  content: string
+  /** Absolute file path when the skill came from disk. */
+  path?: string
+  /** Parsed optional metadata object from frontmatter. */
+  metadata?: Record<string, unknown>
+}
+
+/** Runtime skill contribution accepted by `ctx.skills.register()`. */
+export type SkillRegistration = Omit<SkillDefinition, 'provider'> & { provider?: string }
+
+/** Caller context used for cwd-sensitive and abortable provider work. */
+export interface SkillLookupOptions {
+  cwd?: string | undefined
+  /** Abort discovery or loading work for the current caller. */
+  signal?: AbortSignal | undefined
+}
+
+/** Provider interface for one source of skills, such as local directories or a remote registry. */
+export interface SkillProvider {
+  /** Unique provider name in the `ctx.skills` registry. */
+  name: string
+  /**
+   * List available skill candidates for the current lookup context. Provider
+   * plugins register synchronously during `apply()`; remote initialization,
+   * authentication, and discovery are awaited inside this method. Implementations
+   * should settle promptly when `options.signal` aborts.
+   * @param options - lookup options; `cwd` selects workspace-sensitive skills and `signal` cancels work.
+   * @returns provider candidates with precedence ranks and opaque locators.
+   */
+  list(options: SkillLookupOptions): Promise<SkillCandidate[]>
+  /**
+   * Load a complete skill body for a previously listed candidate.
+   * @param candidate - the winning candidate originally returned by this provider.
+   * @param options - lookup options; `cwd` selects workspace-sensitive skills and `signal` cancels work.
+   * @returns the full skill body, or `undefined` if it is no longer loadable.
+   */
+  get(candidate: SkillCandidate, options: SkillLookupOptions): Promise<SkillDefinition | undefined>
+}
+
+/** Skill registry configuration. */
+export interface Config {
+  /** Maximum number of completed cwd/provider catalog snapshots kept in memory. */
+  collectCacheMaxEntries?: number
+}
+
+declare module 'cordis' {
+  interface Context {
+    skills: SkillService
+  }
+
+  interface Events {
+    /**
+     * A skill provider became resolvable in the `ctx.skills` registry.
+     * Consumers can observe this instead of depending on Cordis plugin load
+     * order, which is concurrent for sibling plugins.
+     * @param provider - the provider that just registered.
+     * @mode emit
+     */
+    'skill/provider-added'(provider: SkillProvider): void
+    /**
+     * A skill provider left the registry because its plugin fiber was disposed.
+     * @param name - the registry name that no longer resolves.
+     * @mode emit
+     */
+    'skill/provider-removed'(name: string): void
+  }
+}
+
+interface IndexedCandidate {
+  candidate: SkillCandidate
+  provider: SkillProvider
+  providerOrder: number
+  localOrder: number
+}
+
+interface CollectResult {
+  entries: IndexedCandidate[]
+  cacheable: boolean
+}
+
+/**
+ * Registry of skill providers. It merges provider catalogs with stable
+ * first-wins duplicate handling, exposes sorted model-visible summaries, and
+ * loads full skill bodies on demand.
+ */
+export class SkillService extends Service {
+  static Config: Schema<Config> = z.object({
+    collectCacheMaxEntries: z.number().default(DEFAULT_COLLECT_CACHE_ENTRIES),
+  })
+
+  private readonly collectCacheMaxEntries: number
+  private readonly providers = new Map<string, { provider: SkillProvider; order: number }>()
+  private readonly runtime = new Map<string, SkillDefinition>()
+  private readonly collectCache = new Map<string, IndexedCandidate[]>()
+  private providerRevision = 0
+  private nextProviderOrder = 0
+  private runtimeRevision = 0
+
+  constructor(ctx: Context, config: Config = {}) {
+    super(ctx, 'skills')
+    this.collectCacheMaxEntries = config.collectCacheMaxEntries ?? DEFAULT_COLLECT_CACHE_ENTRIES
+    assertPositiveInteger('collectCacheMaxEntries', this.collectCacheMaxEntries)
+  }
+
+  /**
+   * Register a skill provider synchronously during the provider plugin's
+   * `apply()`. Throws if another provider already owns the same provider name,
+   * including the reserved runtime provider name. Providers that need remote
+   * initialization do that work inside `list()` after registration. Effect-
+   * scoped and HMR-safe: disposing the caller's fiber unregisters the provider
+   * and invalidates cached catalogs.
+   * @param provider - the provider to register by `provider.name`.
+   * @returns a disposer that unregisters this provider.
+   */
+  registerProvider(provider: SkillProvider): () => void {
+    const dispose = this.ctx.effect(function* (this: SkillService) {
+      if (provider.name === RUNTIME_PROVIDER) {
+        throw new Error(`"${RUNTIME_PROVIDER}" is reserved for runtime skill registrations`)
+      }
+      if (this.providers.has(provider.name)) {
+        throw new Error(`a skill provider named "${provider.name}" is already registered`)
+      }
+      this.providers.set(provider.name, { provider, order: this.nextProviderOrder })
+      this.nextProviderOrder += 1
+      this.invalidateCache()
+      yield () => {
+        this.providers.delete(provider.name)
+        this.invalidateCache()
+        this.ctx.emit('skill/provider-removed', provider.name)
+      }
+      this.ctx.emit('skill/provider-added', provider)
+    }.bind(this), 'skills.registerProvider()')
+    return () => void dispose()
+  }
+
+  /**
+   * Register a runtime skill contribution. Runtime registrations are treated as
+   * embedded provider entries with project-over-user priority. Same-name runtime
+   * registrations are first-wins: a duplicate logs a warning and gets a no-op
+   * disposer so it cannot remove the active contribution.
+   * @param skill - the complete skill definition to expose for discovery.
+   * @returns a disposer that removes this runtime contribution and invalidates caches.
+   */
+  register(skill: SkillRegistration): () => void {
+    const normalized = normalizeRuntimeSkill(skill)
+    const existing = this.runtime.get(normalized.name)
+    if (existing !== undefined) {
+      this.ctx.logger.warn(`runtime skill "${normalized.name}" ignored because it is already registered`)
+      return () => {}
+    }
+    const dispose = this.ctx.effect(function* (this: SkillService) {
+      this.runtime.set(normalized.name, normalized)
+      this.runtimeRevision += 1
+      this.invalidateCache()
+      yield () => {
+        this.runtime.delete(normalized.name)
+        this.runtimeRevision += 1
+        this.invalidateCache()
+      }
+    }.bind(this), 'skills.register()')
+    return () => void dispose()
+  }
+
+  /**
+   * List model-invocable skill summaries for a workspace.
+   * @param options - lookup options; `cwd` selects project roots and `signal` cancels discovery.
+   * @returns sorted summaries, excluding skills disabled for model invocation.
+   */
+  async list(options: SkillLookupOptions = {}): Promise<SkillSummary[]> {
+    return (await this.collect(options))
+      .map(entry => entry.candidate)
+      .filter(skill => skill.disableModelInvocation !== true)
+      .map(toSummary)
+      .sort(compareSkillSummary)
+  }
+
+  /**
+   * Load one full skill definition by name.
+   * @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`.
+   */
+  async get(name: string, options: SkillLookupOptions = {}): Promise<SkillDefinition | undefined> {
+    if (!isSkillName(name)) return undefined
+    const match = (await this.collect(options)).find(entry => entry.candidate.name === name)
+    if (match === undefined) return undefined
+    return await match.provider.get(match.candidate, options)
+  }
+
+  private async collect(options: SkillLookupOptions): Promise<IndexedCandidate[]> {
+    options.signal?.throwIfAborted()
+    while (true) {
+      const providerRevision = this.providerRevision
+      const runtimeRevision = this.runtimeRevision
+      const key = collectCacheKey(options, providerRevision, runtimeRevision)
+      const cached = this.collectCache.get(key)
+      if (cached !== undefined) return cached
+
+      const result = await this.collectFresh(options)
+      options.signal?.throwIfAborted()
+      if (providerRevision !== this.providerRevision || runtimeRevision !== this.runtimeRevision) continue
+      if (result.cacheable) {
+        this.collectCache.set(key, result.entries)
+        if (this.collectCache.size > this.collectCacheMaxEntries) {
+          const oldest = this.collectCache.keys().next() as IteratorYieldResult<string>
+          this.collectCache.delete(oldest.value)
+        }
+      }
+      return result.entries
+    }
+  }
+
+  private async collectFresh(options: SkillLookupOptions): Promise<CollectResult> {
+    const collected = await this.listAllCandidates(options)
+    collected.entries.sort(compareIndexedCandidates)
+    const seen = new Set<string>()
+    const result: IndexedCandidate[] = []
+    for (const entry of collected.entries) {
+      const skill = entry.candidate
+      if (seen.has(skill.name)) {
+        this.ctx.logger.warn(`skill "${skill.name}" from ${skill.source} ignored because a higher-priority skill already exists`)
+        continue
+      }
+      seen.add(skill.name)
+      result.push(entry)
+    }
+    return { entries: result, cacheable: collected.cacheable }
+  }
+
+  private async listAllCandidates(options: SkillLookupOptions): Promise<CollectResult> {
+    options.signal?.throwIfAborted()
+    const candidates: IndexedCandidate[] = []
+    let cacheable = true
+    let runtimeOrder = 0
+    for (const skill of [...this.runtime.values()].sort((a, b) => compareCodePoints(a.name, b.name))) {
+      candidates.push({
+        candidate: runtimeCandidate(skill),
+        provider: RUNTIME_SKILL_PROVIDER,
+        providerOrder: -1,
+        localOrder: runtimeOrder,
+      })
+      runtimeOrder += 1
+    }
+    for (const { provider, order } of [...this.providers.values()]) {
+      let localOrder = 0
+      let listed: SkillCandidate[] | undefined
+      try {
+        listed = await waitWithAbort(provider.list(options), options.signal)
+      } catch (error) {
+        if (options.signal?.aborted === true) throw toError(options.signal.reason)
+        cacheable = false
+        this.ctx.logger.warn(`skill provider "${provider.name}" skipped: ${errorMessage(error)}`)
+      }
+      if (listed === undefined) continue
+      for (const candidate of listed) {
+        validateCandidate(candidate, provider.name)
+        candidates.push({ candidate, provider, providerOrder: order, localOrder })
+        localOrder += 1
+      }
+    }
+    return { entries: candidates, cacheable }
+  }
+
+  private invalidateCache(): void {
+    this.providerRevision += 1
+    this.collectCache.clear()
+  }
+}
+
+const RUNTIME_SKILL_PROVIDER: SkillProvider = {
+  name: RUNTIME_PROVIDER,
+  /* v8 ignore next -- Runtime skills are injected directly by the registry; this provider only owns `get()`. */
+  list() {
+    return Promise.resolve([])
+  },
+  get(candidate) {
+    const skill = candidate.locator as SkillDefinition
+    return Promise.resolve({ ...skill })
+  },
+}
+
+function runtimeCandidate(skill: SkillDefinition): SkillCandidate {
+  return {
+    ...toSummary(skill),
+    rank: RUNTIME_RANK,
+    locator: skill,
+    ...skill.path !== undefined ? { path: skill.path } : {},
+    ...skill.metadata !== undefined ? { metadata: skill.metadata } : {},
+  }
+}
+
+function validateCandidate(candidate: SkillCandidate, providerName: string): void {
+  if (!SKILL_NAME.test(candidate.name)) {
+    throw new Error(`skill provider "${providerName}" returned invalid skill name "${candidate.name}"`)
+  }
+  if (candidate.description.length === 0) {
+    throw new Error(`skill provider "${providerName}" returned skill "${candidate.name}" without a description`)
+  }
+  if (!Number.isFinite(candidate.rank)) {
+    throw new Error(`skill provider "${providerName}" returned skill "${candidate.name}" with an invalid rank`)
+  }
+  if (candidate.provider !== providerName) {
+    throw new Error(`skill provider "${providerName}" returned skill "${candidate.name}" for provider "${candidate.provider}"`)
+  }
+}
+
+function normalizeRuntimeSkill(skill: SkillRegistration): SkillDefinition {
+  if (!SKILL_NAME.test(skill.name)) throw new Error(`invalid skill name "${skill.name}"`)
+  if (skill.description.length === 0) throw new Error(`skill "${skill.name}" requires a description`)
+  return {
+    ...skill,
+    provider: skill.provider ?? RUNTIME_PROVIDER,
+    source: skill.source,
+  }
+}
+
+function toSummary(skill: SkillDefinition | SkillCandidate): SkillSummary {
+  const { name, description, whenToUse, disableModelInvocation, source, provider, resourceBase } = skill
+  return {
+    name,
+    description,
+    ...whenToUse !== undefined ? { whenToUse } : {},
+    ...disableModelInvocation !== undefined ? { disableModelInvocation } : {},
+    source,
+    provider,
+    ...resourceBase !== undefined ? { resourceBase } : {},
+  }
+}
+
+function compareSkillSummary(left: SkillSummary, right: SkillSummary): number {
+  return compareCodePoints(left.name, right.name)
+}
+
+function compareCodePoints(left: string, right: string): number {
+  if (left < right) return -1
+  if (left > right) return 1
+  return 0
+}
+
+function compareIndexedCandidates(left: IndexedCandidate, right: IndexedCandidate): number {
+  return left.candidate.rank - right.candidate.rank
+    || left.providerOrder - right.providerOrder
+    || left.localOrder - right.localOrder
+}
+
+function assertPositiveInteger(name: string, value: number, minimum = 1): void {
+  if (!Number.isInteger(value) || value < minimum) {
+    throw new Error(`skill: ${name} must be an integer greater than or equal to ${minimum}`)
+  }
+}
+
+function collectCacheKey(options: SkillLookupOptions, providerRevision: number, runtimeRevision: number): string {
+  return JSON.stringify({ cwd: options.cwd, providerRevision, runtimeRevision })
+}
+
+function waitWithAbort<T>(promise: Promise<T>, signal: AbortSignal | undefined): Promise<T> {
+  if (signal === undefined) return promise
+  signal.throwIfAborted()
+  return new Promise<T>((resolve, reject) => {
+    const cleanup = (): void => {
+      signal.removeEventListener('abort', onAbort)
+    }
+    const onAbort = (): void => {
+      cleanup()
+      reject(toError(signal.reason))
+    }
+    signal.addEventListener('abort', onAbort, { once: true })
+    void promise.then(
+      (value) => {
+        cleanup()
+        resolve(value)
+      },
+      (error: unknown) => {
+        cleanup()
+        reject(toError(error))
+      },
+    )
+    if (signal.aborted) onAbort()
+  })
+}
+
+function toError(error: unknown): Error {
+  return error instanceof Error ? error : new Error(String(error))
+}
+
+function errorMessage(error: unknown): string {
+  return String(error)
+}
+
+export default SkillService

packages/skill/skill/tests/skill.spec.ts

@@ -0,0 +1,344 @@
+import { describe, expect, it, vi } from 'vitest'
+import { Context } from 'cordis'
+import SkillService, { type SkillCandidate, type SkillDefinition, type SkillLookupOptions, type SkillProvider } from '@deepseek-ai/dsh-skill'
+
+function memorySkill(name: string, description: string, rank: number, body = `${name} body.`): SkillCandidate {
+  return {
+    name,
+    description,
+    provider: 'memory',
+    source: 'memory',
+    rank,
+    locator: { content: body },
+  }
+}
+
+class MemoryProvider implements SkillProvider {
+  readonly name = 'memory'
+  listCalls = 0
+
+  constructor(private candidates: SkillCandidate[]) {}
+
+  async list(_options: SkillLookupOptions): Promise<SkillCandidate[]> {
+    this.listCalls += 1
+    return this.candidates
+  }
+
+  async get(candidate: SkillCandidate): Promise<SkillDefinition | undefined> {
+    const locator = candidate.locator as { content: string }
+    return { ...candidate, content: locator.content }
+  }
+
+  replace(candidates: SkillCandidate[]): void {
+    this.candidates = candidates
+  }
+}
+
+describe('SkillService registry', () => {
+  it('registers providers, resolves duplicates first-wins, and disposes providers', async () => {
+    const ctx = new Context()
+    await ctx.plugin(SkillService)
+    const provider = new MemoryProvider([
+      memorySkill('z-skill', 'Z skill', 20),
+      memorySkill('a-skill', 'A skill', 10),
+      memorySkill('shadowed', 'Lower priority', 20),
+    ])
+    const overrideProvider: SkillProvider = {
+      name: 'override',
+      async list() {
+        return [{
+          name: 'shadowed',
+          description: 'Higher priority',
+          provider: 'override',
+          source: 'override',
+          rank: 5,
+          locator: { content: 'Override body.' },
+        }]
+      },
+      async get(candidate) {
+        return { ...candidate, content: (candidate.locator as { content: string }).content }
+      },
+    }
+    const disposeMemory = ctx.skills.registerProvider(provider)
+    ctx.skills.registerProvider(overrideProvider)
+
+    expect((await ctx.skills.list()).map(skill => [skill.name, skill.description, skill.provider])).toEqual([
+      ['a-skill', 'A skill', 'memory'],
+      ['shadowed', 'Higher priority', 'override'],
+      ['z-skill', 'Z skill', 'memory'],
+    ])
+    expect((await ctx.skills.get('shadowed'))?.content).toBe('Override body.')
+    const sameRankProvider: SkillProvider = {
+      name: 'same-rank',
+      async list() {
+        return [{
+          name: 'same-rank-skill',
+          description: 'Same rank',
+          provider: 'same-rank',
+          source: 'same-rank',
+          rank: 10,
+          locator: { content: 'Same rank body.' },
+        }]
+      },
+      async get(candidate) {
+        return { ...candidate, content: (candidate.locator as { content: string }).content }
+      },
+    }
+    ctx.skills.registerProvider(sameRankProvider)
+    expect((await ctx.skills.list()).find(skill => skill.name === 'same-rank-skill')?.provider).toBe('same-rank')
+    await expect(ctx.plugin({
+      name: 'duplicate-memory',
+      inject: ['skills'],
+      apply(pluginCtx: Context) {
+        pluginCtx.skills.registerProvider(new MemoryProvider([]))
+      },
+    })).rejects.toThrow('already registered')
+    expect(() => ctx.skills.registerProvider({
+      name: 'runtime',
+      async list() {
+        return []
+      },
+      async get() {
+        return undefined
+      },
+    })).toThrow('reserved')
+
+    disposeMemory()
+    expect((await ctx.skills.list()).map(skill => skill.name)).toEqual(['same-rank-skill', 'shadowed'])
+  })
+
+  it('validates provider candidates and invalid registry caps', async () => {
+    const defaultedService = new SkillService(new Context())
+    expect(await defaultedService.list()).toEqual([])
+
+    const ctx = new Context()
+    await ctx.plugin(SkillService)
+    ctx.skills.registerProvider({
+      name: 'bad',
+      async list() {
+        return [memorySkill('Bad_Name', 'bad', 1)]
+      },
+      async get() {
+        return undefined
+      },
+    })
+    await expect(ctx.skills.list()).rejects.toThrow('invalid skill name')
+
+    const invalidCandidates = [
+      { ...memorySkill('empty-description', '', 1), provider: 'empty-description' },
+      { ...memorySkill('bad-rank', 'Bad rank', Number.NaN), provider: 'bad-rank' },
+      { ...memorySkill('wrong-provider', 'Wrong provider', 1), provider: 'different' },
+    ]
+    for (const candidate of invalidCandidates) {
+      const invalid = new Context()
+      await invalid.plugin(SkillService)
+      invalid.skills.registerProvider({
+        name: candidate.name,
+        async list() {
+          return [candidate]
+        },
+        async get() {
+          return undefined
+        },
+      })
+      await expect(invalid.skills.list()).rejects.toThrow('skill provider')
+    }
+
+    await expect(new Context().plugin(SkillService, { collectCacheMaxEntries: 1.5 })).rejects.toThrow('collectCacheMaxEntries')
+  })
+
+  it('sorts model-visible summaries without locale-sensitive collation', async () => {
+    const ctx = new Context()
+    await ctx.plugin(SkillService)
+    ctx.skills.registerProvider(new MemoryProvider([
+      memorySkill('z-skill', 'Z skill', 10),
+      memorySkill('a-skill', 'A skill', 10),
+    ]))
+    const localeCompare = vi.spyOn(String.prototype, 'localeCompare')
+    const sort = vi.spyOn(Array.prototype, 'sort')
+
+    try {
+      const skills = await ctx.skills.list()
+      expect(skills.map(skill => skill.name)).toEqual(['a-skill', 'z-skill'])
+      expect(localeCompare).not.toHaveBeenCalled()
+
+      const summaryComparator = sort.mock.calls.at(-1)?.[0]
+      expect(summaryComparator).toBeTypeOf('function')
+      expect(summaryComparator?.(skills[0], skills[0])).toBe(0)
+    } finally {
+      sort.mockRestore()
+      localeCompare.mockRestore()
+    }
+  })
+
+  it('caches provider discovery, skips failing providers, and invalidates on runtime skills', async () => {
+    const ctx = new Context()
+    await ctx.plugin(SkillService, { collectCacheMaxEntries: 1 })
+    const provider = new MemoryProvider([memorySkill('first-skill', 'First', 10)])
+    ctx.skills.registerProvider(provider)
+
+    expect((await ctx.skills.list()).map(skill => skill.name)).toEqual(['first-skill'])
+    provider.replace([memorySkill('second-skill', 'Second', 10)])
+    expect((await ctx.skills.list()).map(skill => skill.name)).toEqual(['first-skill'])
+
+    const disposeRuntime = ctx.skills.register({
+      name: 'runtime-skill',
+      description: 'Runtime',
+      source: 'runtime',
+      resourceBase: { kind: 'opaque', description: 'runtime memory' },
+      path: 'memory://runtime-skill',
+      metadata: { owner: 'tests' },
+      content: 'Runtime body.',
+    })
+    expect((await ctx.skills.list()).map(skill => skill.name)).toEqual(['runtime-skill', 'second-skill'])
+    expect(await ctx.skills.get('runtime-skill')).toMatchObject({
+      content: 'Runtime body.',
+      path: 'memory://runtime-skill',
+      metadata: { owner: 'tests' },
+    })
+    disposeRuntime()
+    await ctx.skills.list({ cwd: '/tmp/first-cache-key' })
+    await ctx.skills.list({ cwd: '/tmp/second-cache-key' })
+
+    let fail = true
+    let flakyCalls = 0
+    ctx.skills.registerProvider({
+      name: 'flaky',
+      async list() {
+        flakyCalls += 1
+        if (fail) throw new Error('transient discovery failure')
+        return [{ ...memorySkill('flaky-skill', 'Flaky', 10), provider: 'flaky' }]
+      },
+      async get() {
+        return undefined
+      },
+    })
+    expect((await ctx.skills.list()).map(skill => skill.name)).toEqual(['second-skill'])
+    expect(flakyCalls).toBe(1)
+    expect((await ctx.skills.list()).map(skill => skill.name)).toEqual(['second-skill'])
+    expect(flakyCalls).toBe(2)
+    fail = false
+    expect((await ctx.skills.list()).map(skill => skill.name)).toEqual(['flaky-skill', 'second-skill'])
+    expect(flakyCalls).toBe(3)
+    expect((await ctx.skills.list()).map(skill => skill.name)).toEqual(['flaky-skill', 'second-skill'])
+    expect(flakyCalls).toBe(3)
+  })
+
+  it('abandons an in-flight catalog when provider registrations change', async () => {
+    const ctx = new Context()
+    await ctx.plugin(SkillService)
+    let markStarted: (() => void) | undefined
+    let release: (() => void) | undefined
+    const started = new Promise<void>((resolve) => { markStarted = resolve })
+    const gate = new Promise<void>((resolve) => { release = resolve })
+    const dispose = ctx.skills.registerProvider({
+      name: 'delayed',
+      async list() {
+        markStarted?.()
+        await gate
+        return [{ ...memorySkill('stale-skill', 'Stale', 10), provider: 'delayed' }]
+      },
+      async get(candidate) {
+        return { ...candidate, content: 'Stale body.' }
+      },
+    })
+
+    const pending = ctx.skills.list()
+    await started
+    dispose()
+    release?.()
+
+    expect(await pending).toEqual([])
+  })
+
+  it('stops waiting for discovery when its lookup signal aborts', async () => {
+    const ctx = new Context()
+    await ctx.plugin(SkillService)
+    let markStarted: (() => void) | undefined
+    let release: (() => void) | undefined
+    let seenSignal: AbortSignal | undefined
+    const started = new Promise<void>((resolve) => { markStarted = resolve })
+    const held = new Promise<SkillCandidate[]>((resolve) => {
+      release = () => { resolve([]) }
+    })
+    ctx.skills.registerProvider({
+      name: 'uncooperative',
+      list(options) {
+        seenSignal = options.signal
+        markStarted?.()
+        return held
+      },
+      async get() {
+        return undefined
+      },
+    })
+    const controller = new AbortController()
+    const reason = 'discovery cancelled'
+    const pending = ctx.skills.list({ signal: controller.signal })
+    const outcome = pending.then(
+      () => 'resolved',
+      (error: unknown) => error instanceof Error && error.message === reason ? 'aborted' : 'other-error',
+    )
+    await started
+    controller.abort(reason)
+
+    const settled = await Promise.race([
+      outcome,
+      new Promise<'timeout'>(resolve => setTimeout(() => { resolve('timeout') }, 25)),
+    ])
+    release?.()
+    await pending.catch(() => undefined)
+
+    expect(seenSignal).toBe(controller.signal)
+    expect(settled).toBe('aborted')
+  })
+
+  it('does not miss an abort racing listener installation', async () => {
+    const ctx = new Context()
+    await ctx.plugin(SkillService)
+    const reason = new Error('racing abort')
+    let aborted = false
+    const signal = {
+      get aborted() {
+        return aborted
+      },
+      reason,
+      throwIfAborted() {
+        if (aborted) throw reason
+      },
+      addEventListener(_type: string, listener: () => void) {
+        aborted = true
+        listener()
+      },
+      removeEventListener() {},
+    } as unknown as AbortSignal
+    ctx.skills.registerProvider({
+      name: 'racing-abort',
+      list() {
+        return Promise.reject(new Error('late provider failure'))
+      },
+      async get() {
+        return undefined
+      },
+    })
+
+    await expect(ctx.skills.list({ signal })).rejects.toBe(reason)
+    await Promise.resolve()
+  })
+
+  it('rejects invalid runtime skill registrations and ignores duplicates', async () => {
+    const ctx = new Context()
+    await ctx.plugin(SkillService)
+    expect(() => ctx.skills.register({ name: 'Bad_Name', description: 'Bad', source: 'runtime', content: 'bad' })).toThrow('invalid skill name')
+    expect(() => ctx.skills.register({ name: 'no-description', description: '', source: 'runtime', content: 'bad' })).toThrow('requires a description')
+    expect(await ctx.skills.get('missing-skill')).toBeUndefined()
+    expect(await ctx.skills.get('Bad_Name')).toBeUndefined()
+
+    const disposeFirst = ctx.skills.register({ name: 'same-skill', description: 'First', source: 'runtime', content: 'first' })
+    const disposeSecond = ctx.skills.register({ name: 'same-skill', description: 'Second', source: 'runtime', content: 'second' })
+    disposeSecond()
+    expect((await ctx.skills.get('same-skill'))?.description).toBe('First')
+    disposeFirst()
+    expect(await ctx.skills.get('same-skill')).toBeUndefined()
+  })
+})

packages/skill/skill/tsconfig.json

@@ -0,0 +1,13 @@
+{
+  "extends": "../../../tsconfig.base.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "lib/types"
+  },
+  "include": ["src"],
+  "references": [
+    { "path": "../../../vendor/cosmokit" },
+    { "path": "../../../vendor/cordis" },
+    { "path": "../../../vendor/schemastery" }
+  ]
+}

packages/skill/tool-skill/README.md

@@ -0,0 +1,21 @@
+# @deepseek-ai/dsh-tool-skill
+
+The model-facing skill catalog and `skill` tool.
+
+Requires `ctx.tools` and `ctx.skills` (`inject: ['tools', 'skills']`).
+
+## Session-prefix catalog
+
+The plugin contributes one user-role `<system-reminder>` catalog through `agent/session-prefix`. It resolves skills for the calling session's cwd, forwards the prefix abort signal to discovery, and lists only sorted `name` and `description` entries; skill bodies, paths, sources, providers, and `whenToUse` hints remain outside the catalog. The catalog is omitted when no model-invocable skills are available.
+
+`catalogDescriptionMaxLength` controls normalized, XML-escaped catalog descriptions. Its default is `500` and values must be integers of at least `3`, which reserves room for a truncation ellipsis. The [session-prefix RFC](../../../docs/rfc/implemented/feature/2026-07-07-session-prefix.md) defines the request-only, header-logged lifecycle of this message.
+
+## Tool: `skill`
+
+| Arg | Type | Notes |
+|---|---|---|
+| `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.
+
+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/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@deepseek-ai/dsh-tool-skill",
+  "description": "Model-facing skill loading tool for the DeepSeek Harness",
+  "version": "0.0.1",
+  "private": true,
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/types/**/*.d.ts",
+    "lib/types/**/*.d.ts.map",
+    "src"
+  ],
+  "license": "BSD-3-Clause",
+  "peerDependencies": {
+    "@deepseek-ai/dsh-agent": "^0.0.1",
+    "@deepseek-ai/dsh-llm": "^0.0.1",
+    "@deepseek-ai/dsh-skill": "^0.0.1",
+    "@deepseek-ai/dsh-tools": "^0.0.1",
+    "cordis": "^4.0.0-rc.6"
+  },
+  "dependencies": {
+    "schemastery": "^3.18.0"
+  },
+  "devDependencies": {
+    "@deepseek-ai/dsh-agent": "workspace:^",
+    "@deepseek-ai/dsh-llm": "workspace:^",
+    "@deepseek-ai/dsh-skill": "workspace:^",
+    "@deepseek-ai/dsh-skill-local": "workspace:^",
+    "@deepseek-ai/dsh-tools": "workspace:^",
+    "cordis": "^4.0.0-rc.6"
+  }
+}

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

@@ -0,0 +1,152 @@
+/**
+ * Session-prefix skill catalog and model-facing `skill` loader tool.
+ *
+ * @module @deepseek-ai/dsh-tool-skill
+ */
+
+import type { Context } from 'cordis'
+import z from 'schemastery'
+import { defineTool } from '@deepseek-ai/dsh-tools'
+import { assertNever, type Message } from '@deepseek-ai/dsh-llm'
+import { isSkillName, type SkillDefinition, type SkillSummary } from '@deepseek-ai/dsh-skill'
+
+export const name = 'tool-skill'
+export const inject = ['tools', 'skills']
+
+const DEFAULT_CATALOG_DESCRIPTION_MAX_LENGTH = 500
+
+/** Model-facing skill catalog configuration. */
+export interface Config {
+  /** Maximum normalized description length rendered in the session catalog; minimum 3. */
+  catalogDescriptionMaxLength?: number
+}
+
+/** Validate and default the model-facing skill catalog configuration. */
+export const Config: z<Config> = z.object({
+  catalogDescriptionMaxLength: z.number().default(DEFAULT_CATALOG_DESCRIPTION_MAX_LENGTH),
+})
+
+/** Register the session-prefix skill catalog and the model-facing skill loader. */
+export function apply(ctx: Context, config: Config = {}): void {
+  const catalogDescriptionMaxLength = config.catalogDescriptionMaxLength ?? DEFAULT_CATALOG_DESCRIPTION_MAX_LENGTH
+  assertPositiveInteger('catalogDescriptionMaxLength', catalogDescriptionMaxLength, 3)
+
+  ctx.on('agent/session-prefix', async (agent, _prefix, signal, next): Promise<Message[]> => {
+    const skills = await ctx.skills.list({ cwd: agent.session.header.cwd, signal })
+    const rest = await next()
+    if (skills.length === 0) return rest
+    return [renderCatalogMessage(skills, catalogDescriptionMaxLength), ...rest]
+  })
+
+  const skillTool = defineTool({
+    name: 'skill',
+    description: 'Load the full instructions for an available skill. Call this with the exact skill name from the session skill catalog before acting on a task that names or clearly matches that skill.',
+    parameters: {
+      name: { type: 'string', required: true, description: 'The exact skill name from the available skills list.' },
+    },
+    async execute(args, exec) {
+      if (!isSkillName(args.name)) {
+        throw new Error(`invalid skill name "${args.name}"`)
+      }
+      const skill = await ctx.skills.get(args.name, { cwd: exec.agent?.session.header.cwd, signal: exec.signal })
+      if (!skill) {
+        throw new Error(`skill "${args.name}" is unknown or no longer available`)
+      }
+      if (skill.disableModelInvocation === true) {
+        throw new Error(`skill "${args.name}" is not available for model invocation`)
+      }
+      return [{ type: 'text', text: renderSkillContent(skill) }]
+    },
+    presentCall(args) {
+      return { card: 'generic', title: `Load skill ${args.name}`, kind: 'read', rawInput: args.name }
+    },
+  })
+  ctx.tools.register(skillTool)
+}
+
+function renderSkillContent(skill: SkillDefinition): string {
+  const resourceHint = renderResourceHint(skill)
+  return [
+    `<skill_content name="${escapeAttr(skill.name)}">`,
+    '<skill_resources>',
+    ...resourceHint,
+    '</skill_resources>',
+    '',
+    '<skill_instructions>',
+    skill.content,
+    '</skill_instructions>',
+    '</skill_content>',
+  ].join('\n')
+}
+
+function renderResourceHint(skill: SkillDefinition): string[] {
+  const base = skill.resourceBase
+  if (base === undefined) {
+    return [
+      `Resources for this skill are managed by provider "${escapeText(skill.provider)}".`,
+      'Load referenced resources only as needed.',
+    ]
+  }
+  switch (base.kind) {
+    case 'directory':
+      return [
+        `Base directory for this skill: ${escapeText(base.path)}`,
+        'Resolve relative paths mentioned by this skill against the base directory before using them. Load referenced resources only as needed.',
+      ]
+    case 'url':
+      return [
+        `Base URL for this skill: ${escapeText(base.url)}`,
+        'Resolve relative URLs mentioned by this skill against the base URL before using them. Load referenced resources only as needed.',
+      ]
+    case 'opaque':
+      return [
+        `Resources for this skill: ${escapeText(base.description)}`,
+        'Load referenced resources only as needed.',
+      ]
+    default:
+      return assertNever(base, 'SkillResourceBase.kind')
+  }
+}
+
+function renderCatalogMessage(skills: SkillSummary[], descriptionMaxLength: number): Message {
+  const entries = skills.map(skill => `- \`${skill.name}\`: ${catalogDescription(skill.description, descriptionMaxLength)}`)
+  return {
+    role: 'user',
+    content: [{
+      type: 'text',
+      text: [
+        '<system-reminder>',
+        'A skill is a reusable set of task-specific instructions. The following skills are available in this session:',
+        '',
+        '<available_skills>',
+        ...entries,
+        '</available_skills>',
+        '',
+        "If the user names a skill, or the task clearly matches a skill's description, call the `skill` tool with the exact skill name before taking task actions. Load all applicable skills, then follow their full instructions. This catalog contains summaries only; do not infer or follow a skill's instructions until it has been loaded.",
+        '</system-reminder>',
+      ].join('\n'),
+    }],
+  }
+}
+
+function catalogDescription(value: string, maxLength: number): string {
+  const normalized = value.replaceAll(/\s+/g, ' ').trim()
+  const truncated = normalized.length <= maxLength
+    ? normalized
+    : `${normalized.slice(0, maxLength - 3)}...`
+  return escapeText(truncated)
+}
+
+function assertPositiveInteger(name: string, value: number, minimum = 1): void {
+  if (!Number.isInteger(value) || value < minimum) {
+    throw new Error(`tool-skill: ${name} must be an integer greater than or equal to ${minimum}`)
+  }
+}
+
+function escapeAttr(value: string): string {
+  return value.replaceAll('&', '&amp;').replaceAll('"', '&quot;').replaceAll('<', '&lt;')
+}
+
+function escapeText(value: string): string {
+  return value.replaceAll('&', '&amp;').replaceAll('<', '&lt;').replaceAll('>', '&gt;')
+}

packages/skill/tool-skill/tests/tool-skill.spec.ts

@@ -0,0 +1,275 @@
+import { describe, expect, it } from 'vitest'
+import { mkdir, writeFile } from 'node:fs/promises'
+import { join } from 'node:path'
+import { tmpdir } from 'node:os'
+import { Context } from 'cordis'
+import { CallId, type Message } from '@deepseek-ai/dsh-llm'
+import SystemPrompt, { renderPrompt } from '@deepseek-ai/dsh-system-prompt'
+import ToolRegistry from '@deepseek-ai/dsh-tools'
+import SkillService from '@deepseek-ai/dsh-skill'
+import * as SkillLocal from '@deepseek-ai/dsh-skill-local'
+import * as toolSkill from '@deepseek-ai/dsh-tool-skill'
+
+async function tempDir(name: string): Promise<string> {
+  return await import('node:fs/promises').then(fs => fs.mkdtemp(join(tmpdir(), `dsh-${name}-`)))
+}
+
+async function writeSkill(root: string, name: string, description: string, body: string): Promise<void> {
+  const dir = join(root, name)
+  await mkdir(dir, { recursive: true })
+  await writeFile(join(dir, 'SKILL.md'), `---\nname: ${name}\ndescription: ${description}\n---\n\n${body}\n`)
+}
+
+async function setup(home: string, config: toolSkill.Config = {}): Promise<Context> {
+  const ctx = new Context()
+  await ctx.plugin(SystemPrompt)
+  await ctx.plugin(ToolRegistry)
+  await ctx.plugin(SkillService)
+  await ctx.plugin(SkillLocal, { dshHome: join(home, '.dsh'), agentsHome: join(home, '.agents') })
+  await ctx.plugin(toolSkill, config)
+  return ctx
+}
+
+function agentForCwd(cwd: string): never {
+  return { session: { header: { cwd } } } as never
+}
+
+async function composePrefix(ctx: Context, cwd: string, signal = new AbortController().signal): Promise<Message[]> {
+  const empty: Message[] = []
+  return await ctx.waterfall(
+    'agent/session-prefix', agentForCwd(cwd), empty, signal,
+    () => Promise.resolve(empty),
+  )
+}
+
+describe('dsh-tool-skill', () => {
+  it('registers the skill tool schema and removes it on dispose', async () => {
+    const ctx = new Context()
+    await ctx.plugin(SystemPrompt)
+    await ctx.plugin(ToolRegistry)
+    const home = await tempDir('tool-schema')
+    await ctx.plugin(SkillService)
+    await ctx.plugin(SkillLocal, { dshHome: join(home, '.dsh'), agentsHome: join(home, '.agents') })
+    ctx.skills.register({ name: 'lifecycle-skill', description: 'Lifecycle', source: 'runtime', content: 'body' })
+
+    const fiber = await ctx.plugin(toolSkill)
+    expect(ctx.tools.schemas().map(tool => tool.name)).toEqual(['skill'])
+    expect(await composePrefix(ctx, '/workspace')).toHaveLength(1)
+    expect(ctx.tools.get('skill')?.presentCall?.({ name: 'project-skill' })).toEqual({
+      card: 'generic',
+      title: 'Load skill project-skill',
+      kind: 'read',
+      rawInput: 'project-skill',
+    })
+    await fiber.dispose()
+    expect(ctx.tools.schemas()).toEqual([])
+    expect(await composePrefix(ctx, '/workspace')).toEqual([])
+
+    toolSkill.apply(ctx)
+    expect(ctx.tools.schemas().map(tool => tool.name)).toEqual(['skill'])
+  })
+
+  it('forwards the session-prefix abort signal to skill discovery', async () => {
+    const home = await tempDir('tool-prefix-signal')
+    const ctx = await setup(home)
+    let seenSignal: AbortSignal | undefined
+    ctx.skills.registerProvider({
+      name: 'signal-probe',
+      async list(options) {
+        seenSignal = options.signal
+        return []
+      },
+      async get() {
+        return undefined
+      },
+    })
+    const controller = new AbortController()
+
+    await composePrefix(ctx, '/workspace', controller.signal)
+
+    expect(seenSignal).toBe(controller.signal)
+  })
+
+  it('contributes a stable name-and-description catalog through the session prefix', async () => {
+    const home = await tempDir('tool-catalog')
+    const ctx = await setup(home, { catalogDescriptionMaxLength: 50 })
+    ctx.skills.register({
+      name: 'z-skill',
+      description: 'Long   description '.repeat(5),
+      whenToUse: 'Never render this routing hint.',
+      source: 'secret-source',
+      provider: 'runtime',
+      resourceBase: { kind: 'directory', path: '/secret/path' },
+      content: 'Secret body.',
+    })
+    ctx.skills.register({
+      name: 'a-skill',
+      description: 'Use {{placeholder}} <safely> & carefully.',
+      source: 'runtime',
+      provider: 'runtime',
+      content: 'A body.',
+    })
+    ctx.on('agent/session-prefix', async (_agent, _prefix, _signal, next): Promise<Message[]> => [
+      { role: 'user', content: [{ type: 'text', text: 'later contribution' }] },
+      ...await next(),
+    ])
+
+    const prefix = await composePrefix(ctx, '/workspace')
+
+    expect(prefix).toEqual([
+      {
+        role: 'user',
+        content: [{
+          type: 'text',
+          text: [
+            '<system-reminder>',
+            'A skill is a reusable set of task-specific instructions. The following skills are available in this session:',
+            '',
+            '<available_skills>',
+            '- `a-skill`: Use {{placeholder}} &lt;safely&gt; &amp; carefully.',
+            '- `z-skill`: Long description Long description Long descript...',
+            '</available_skills>',
+            '',
+            "If the user names a skill, or the task clearly matches a skill's description, call the `skill` tool with the exact skill name before taking task actions. Load all applicable skills, then follow their full instructions. This catalog contains summaries only; do not infer or follow a skill's instructions until it has been loaded.",
+            '</system-reminder>',
+          ].join('\n'),
+        }],
+      },
+      { role: 'user', content: [{ type: 'text', text: 'later contribution' }] },
+    ])
+    const rendered = JSON.stringify(prefix[0])
+    expect(rendered).not.toContain('whenToUse')
+    expect(rendered).not.toContain('secret-source')
+    expect(rendered).not.toContain('/secret/path')
+    expect(rendered).not.toContain('Secret body')
+    expect(renderPrompt(await ctx.systemPrompt.assemble({ agent: agentForCwd('/workspace') }))).not.toContain('<available_skills>')
+  })
+
+  it('does not contribute a session-prefix message when no skills are available', async () => {
+    const home = await tempDir('tool-empty-catalog')
+    const ctx = await setup(home)
+
+    expect(await composePrefix(ctx, '/workspace')).toEqual([])
+  })
+
+  it('validates the catalog description cap', async () => {
+    const home = await tempDir('tool-invalid-catalog-cap')
+    const ctx = new Context()
+    await ctx.plugin(SystemPrompt)
+    await ctx.plugin(ToolRegistry)
+    await ctx.plugin(SkillService)
+    await ctx.plugin(SkillLocal, { dshHome: join(home, '.dsh'), agentsHome: join(home, '.agents') })
+
+    await expect(ctx.plugin(toolSkill, { catalogDescriptionMaxLength: 2 })).rejects.toThrow('greater than or equal to 3')
+  })
+
+  it('loads a skill for the calling agent cwd', async () => {
+    const home = await tempDir('tool-load')
+    const project = await tempDir('tool-project')
+    await mkdir(join(project, '.git'), { recursive: true })
+    await writeSkill(join(project, '.dsh/skills'), 'project-skill', 'Project skill', 'Project instructions.')
+    const ctx = await setup(home)
+
+    const result = await ctx.tools.execute({
+      callId: CallId('c1'),
+      name: 'skill',
+      arguments: { name: 'project-skill' },
+      agent: { session: { header: { cwd: project } } } as never,
+    })
+
+    expect(result.isError).toBe(false)
+    const block = result.content[0]
+    expect(block?.type).toBe('text')
+    if (block?.type !== 'text') throw new Error('expected text skill result')
+    expect(block.text).toBe([
+      '<skill_content name="project-skill">',
+      '<skill_resources>',
+      `Base directory for this skill: ${join(project, '.dsh/skills/project-skill')}`,
+      'Resolve relative paths mentioned by this skill against the base directory before using them. Load referenced resources only as needed.',
+      '</skill_resources>',
+      '',
+      '<skill_instructions>',
+      'Project instructions.',
+      '</skill_instructions>',
+      '</skill_content>',
+    ].join('\n'))
+    expect(block.text).not.toContain('# Skill:')
+  })
+
+  it('renders provider-managed resource hints for non-local skills', async () => {
+    const home = await tempDir('tool-resource-hints')
+    const ctx = await setup(home)
+    ctx.skills.register({
+      name: 'opaque-skill',
+      description: 'Opaque skill',
+      source: 'runtime',
+      provider: 'runtime',
+      resourceBase: { kind: 'opaque', description: 'runtime memory' },
+      content: 'Opaque instructions.',
+    })
+    ctx.skills.register({
+      name: 'url-skill',
+      description: 'URL skill',
+      source: 'runtime',
+      provider: 'runtime',
+      resourceBase: { kind: 'url', url: 'https://skills.example.test/url-skill' },
+      content: 'URL instructions.',
+    })
+    ctx.skills.register({
+      name: 'provider-skill',
+      description: 'Provider skill',
+      source: 'runtime',
+      provider: 'runtime',
+      content: 'Provider instructions.',
+    })
+
+    const opaque = await ctx.tools.execute({ callId: CallId('c2'), name: 'skill', arguments: { name: 'opaque-skill' } })
+    const url = await ctx.tools.execute({ callId: CallId('c3'), name: 'skill', arguments: { name: 'url-skill' } })
+    const provider = await ctx.tools.execute({ callId: CallId('c4'), name: 'skill', arguments: { name: 'provider-skill' } })
+
+    if (opaque.content[0]?.type !== 'text' || url.content[0]?.type !== 'text' || provider.content[0]?.type !== 'text') {
+      throw new Error('expected text tool results')
+    }
+    expect(opaque.content[0].text).toContain('<skill_resources>\nResources for this skill: runtime memory\nLoad referenced resources only as needed.\n</skill_resources>')
+    expect(url.content[0].text).toContain('<skill_resources>\nBase URL for this skill: https://skills.example.test/url-skill\nResolve relative URLs mentioned by this skill against the base URL before using them. Load referenced resources only as needed.\n</skill_resources>')
+    expect(provider.content[0].text).toContain('<skill_resources>\nResources for this skill are managed by provider "runtime".\nLoad referenced resources only as needed.\n</skill_resources>')
+  })
+
+  it('fails loud on an unknown resource base kind', async () => {
+    const home = await tempDir('tool-resource-assert-never')
+    const ctx = await setup(home)
+    ctx.skills.register({
+      name: 'rogue-resource-skill',
+      description: 'Rogue resource skill',
+      source: 'runtime',
+      provider: 'runtime',
+      resourceBase: { kind: 'future' } as never,
+      content: 'Rogue instructions.',
+    })
+
+    const result = await ctx.tools.execute({ callId: CallId('c5'), name: 'skill', arguments: { name: 'rogue-resource-skill' } })
+
+    expect(result.isError).toBe(true)
+    const block = result.content[0]
+    if (block?.type !== 'text') throw new Error('expected text tool result')
+    expect(block.text).toContain('unreachable variant')
+  })
+
+  it('returns isError for unknown, invalid, and model-disabled skills', async () => {
+    const home = await tempDir('tool-errors')
+    await writeSkill(join(home, '.dsh/skills'), 'hidden-skill', 'Hidden skill', 'Hidden instructions.')
+    await writeFile(join(home, '.dsh/skills/hidden-skill/SKILL.md'), '---\nname: hidden-skill\ndescription: Hidden skill\ndisableModelInvocation: true\n---\n\nHidden instructions.\n')
+    const ctx = await setup(home)
+
+    const unknown = await ctx.tools.execute({ callId: CallId('c1'), name: 'skill', arguments: { name: 'missing' } })
+    const invalid = await ctx.tools.execute({ callId: CallId('c2'), name: 'skill', arguments: { name: 'Bad_Name' } })
+    const disabled = await ctx.tools.execute({ callId: CallId('c3'), name: 'skill', arguments: { name: 'hidden-skill' } })
+
+    expect(unknown.isError).toBe(true)
+    expect(invalid.isError).toBe(true)
+    expect(disabled.isError).toBe(true)
+    const unknownBlock = unknown.content[0]
+    if (unknownBlock?.type !== 'text') throw new Error('expected text tool result')
+    expect(unknownBlock.text).toContain('skill "missing" is unknown or no longer available')
+  })
+})

packages/skill/tool-skill/tsconfig.json

@@ -0,0 +1,17 @@
+{
+  "extends": "../../../tsconfig.base.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "lib/types"
+  },
+  "include": ["src"],
+  "references": [
+    { "path": "../../../vendor/cosmokit" },
+    { "path": "../../../vendor/cordis" },
+    { "path": "../../../vendor/schemastery" },
+    { "path": "../../llm/llm" },
+    { "path": "../../core/agent" },
+    { "path": "../skill" },
+    { "path": "../../core/tools" }
+  ]
+}

packages/support/acp-snapshot/src/harness.ts

@@ -212,6 +212,8 @@ export async function runScenario(input: InputScript, opts: RunOptions): Promise
       DSH_SNAPSHOT: opts.mode,
       DSH_SNAPSHOT_FILE: opts.fixtureFile,
       DSH_SNAPSHOT_SESSIONS_ROOT: sessionsRoot,
+      DSH_HOME: join(cwd, '.dsh'),
+      DSH_AGENTS_HOME: join(cwd, '.agents'),
       ...opts.overrideFile !== undefined ? { DSH_SNAPSHOT_OVERRIDE: opts.overrideFile } : {},
       ...opts.childFiles !== undefined && opts.childFiles.length > 0
         ? { DSH_SNAPSHOT_CHILD_FILES: opts.childFiles.join(delimiter) }

packages/ui/acp-agent/README.md

@@ -1,6 +1,6 @@
 # @deepseek-ai/dsh-acp-agent
 
-The **ACP server app**: a Cordis app plugin that composes the providerless agent spine ([`@deepseek-ai/dsh-agent-core`](../../core/agent-core/README.md)) with the front-door cluster an [Agent Client Protocol](../acp/README.md) server needs, and a `bin` that boots a leaf `cordis.yml` speaking ACP JSON-RPC on stdio.
+The **ACP server app**: a Cordis app plugin that composes the default agent spine ([`@deepseek-ai/dsh-agent-core`](../../core/agent-core/README.md)) with the front-door cluster an [Agent Client Protocol](../acp/README.md) server needs, and a `bin` that boots a leaf `cordis.yml` speaking ACP JSON-RPC on stdio.
 
 It is the structured counterpart to [`@deepseek-ai/dsh-stdio-agent`](../stdio-agent/README.md): both consume the same spine, but this one bakes in the OPPOSITE front-door cluster.
 

packages/ui/acp-agent/src/index.ts

@@ -1,5 +1,5 @@
 /**
- * The ACP server app: the providerless agent spine ({@link
+ * The ACP server app: the default agent spine ({@link
  * @deepseek-ai/dsh-agent-core}) plus the coupled front-door cluster an ACP
  * server needs — JSONL session persistence and the {@link @deepseek-ai/dsh-acp}
  * bridge, and DELIBERATELY NOTHING that writes to stdout.
@@ -60,6 +60,8 @@ export interface Config {
   tools?: ToolsConfig
   /** Directory the JSONL session backend writes under. Defaults to `./.sessions`. */
   persistenceRoot?: string
+  /** Skill registry, local-provider, and model-facing consumer config forwarded to agent-core. */
+  skills?: agentCore.SkillConfig
 }
 
 export const Config: z<Config> = z.object({
@@ -71,6 +73,7 @@ export const Config: z<Config> = z.object({
   toolOrder: z.array(z.string()).default(undefined as unknown as string[]),
   tools: ToolRegistry.Config,
   persistenceRoot: z.string().default('./.sessions'),
+  skills: agentCore.SkillConfigSchema,
 })
 
 /**
@@ -85,6 +88,7 @@ export function apply(ctx: Context, config: Config): void {
     ...config.persona !== undefined ? { persona: config.persona } : {},
     ...config.toolOrder !== undefined ? { toolOrder: config.toolOrder } : {},
     ...config.tools !== undefined ? { tools: config.tools } : {},
+    ...config.skills !== undefined ? { skills: config.skills } : {},
   })
   ctx.plugin(UserInteractionService)
   ctx.plugin(SessionPersistenceJsonl, { root: config.persistenceRoot ?? './.sessions' })

packages/ui/acp-agent/tests/acp-agent.spec.ts

@@ -1,7 +1,11 @@
 import { describe, expect, it } from 'vitest'
+import { mkdtemp } from 'node:fs/promises'
+import { join } from 'node:path'
+import { tmpdir } from 'node:os'
 import { Context } from 'cordis'
 import Loader from '@cordisjs/plugin-loader'
 import { TOOL_ORDER_REST } from '@deepseek-ai/dsh-system-prompt'
+import type { Message } from '@deepseek-ai/dsh-llm'
 import * as acpAgent from '../src/index.ts'
 
 /**
@@ -23,9 +27,47 @@ async function mount(config: acpAgent.Config): Promise<Context> {
   return ctx
 }
 
+async function isolatedSkillsConfig(catalogDescriptionMaxLength?: number): Promise<NonNullable<acpAgent.Config['skills']>> {
+  const home = await mkdtemp(join(tmpdir(), 'dsh-acp-agent-skills-'))
+  return {
+    local: { dshHome: join(home, '.dsh'), agentsHome: join(home, '.agents') },
+    ...catalogDescriptionMaxLength !== undefined ? { tool: { catalogDescriptionMaxLength } } : {},
+  }
+}
+
+async function composePrefix(ctx: Context): Promise<Message[]> {
+  const empty: Message[] = []
+  return await ctx.waterfall(
+    'agent/session-prefix', { session: { header: { cwd: '/tmp' } } } as never,
+    empty, new AbortController().signal, () => Promise.resolve(empty),
+  )
+}
+
+async function withIsolatedSkillHomes<T>(run: () => Promise<T>): Promise<T> {
+  const oldDshHome = process.env.DSH_HOME
+  const oldAgentsHome = process.env.DSH_AGENTS_HOME
+  const home = await mkdtemp(join(tmpdir(), 'dsh-acp-agent-default-skills-'))
+  process.env.DSH_HOME = join(home, '.dsh')
+  process.env.DSH_AGENTS_HOME = join(home, '.agents')
+  try {
+    return await run()
+  } finally {
+    if (oldDshHome === undefined) {
+      delete process.env.DSH_HOME
+    } else {
+      process.env.DSH_HOME = oldDshHome
+    }
+    if (oldAgentsHome === undefined) {
+      delete process.env.DSH_AGENTS_HOME
+    } else {
+      process.env.DSH_AGENTS_HOME = oldAgentsHome
+    }
+  }
+}
+
 describe('dsh-acp-agent composition', () => {
   it('brings up the spine + persistence + the ACP bridge', async () => {
-    const ctx = await mount({ model: 'mock', persona: 'hi', persistenceRoot: '/tmp/dsh-acp-agent-test' })
+    const ctx = await mount({ model: 'mock', persona: 'hi', persistenceRoot: '/tmp/dsh-acp-agent-test', skills: await isolatedSkillsConfig() })
     expect(ctx.get('agents')).toBeDefined()
     expect(ctx.get('sessions')).toBeDefined()
     expect(ctx.get('sessionPersistence')).toBeDefined()
@@ -44,12 +86,30 @@ describe('dsh-acp-agent composition', () => {
     // persistenceRoot, so the runtime fallback is the one that fires.
     const ctx = new Context()
     // No persona: covers the omitted-persona forwarding branch too.
-    acpAgent.apply(ctx, { model: 'mock' })
+    acpAgent.apply(ctx, { model: 'mock', skills: await isolatedSkillsConfig() })
     await new Promise(resolve => setTimeout(resolve, 50))
     expect(ctx.get('sessionPersistence')).toBeDefined()
     await ctx.fiber.dispose()
   })
 
+  it('uses default skill config when apply is called directly without skills', async () => {
+    await withIsolatedSkillHomes(async () => {
+      const ctx = new Context()
+      acpAgent.apply(ctx, { model: 'mock' })
+      await new Promise(resolve => setTimeout(resolve, 50))
+      expect(ctx.skills).toBeDefined()
+      expect(await ctx.skills.list()).toEqual([])
+      await ctx.fiber.dispose()
+    })
+  })
+
+  it('forwards skill config into agent-core', async () => {
+    const ctx = await mount({ model: 'mock', persona: 'hi', skills: await isolatedSkillsConfig(6) })
+    ctx.skills.register({ name: 'acp-skill', description: 'ACP skill', source: 'runtime', content: 'body' })
+    expect(JSON.stringify(await composePrefix(ctx))).toContain('- `acp-skill`: ACP...')
+    await ctx.fiber.dispose()
+  })
+
   it('exposes its plugin shape', () => {
     expect(acpAgent.name).toBe('acp-agent')
     expect(acpAgent.Config).toBeDefined()
@@ -72,7 +132,7 @@ describe('dsh-acp-agent composition', () => {
       })
     }
     const assembly = await ctx.get('systemPrompt')!.assemble()
-    expect(assembly.tools.map(tool => tool.name)).toEqual(['zulu', 'alpha'])
+    expect(assembly.tools.map(tool => tool.name)).toEqual(['zulu', 'alpha', 'skill'])
     await ctx.fiber.dispose()
   })
 

packages/ui/acp-agent/tests/built-bin.e2e.ts

@@ -99,7 +99,7 @@ async function makeConsumer(): Promise<string> {
     '  name: \'@deepseek-ai/dsh-acp-agent\'',
     '  config:',
     '    model: deepseek-v4-flash',
-    '    systemPrompt: \'test agent\'',
+    '    persona: \'test agent\'',
     '',
   ].join('\n'))
   return dir
@@ -120,7 +120,12 @@ describe.skipIf(!existsSync(acpBin))('dsh-acp-agent BUILT bin (node lib/bin.js,
     child = spawn(process.execPath, ['--expose-internals', acpBin, './cordis.yml'], {
       cwd: consumer,
       // Dummy key: initialize never reaches the model, so it is never used.
-      env: { ...process.env, DEEPSEEK_API_KEY: process.env.DEEPSEEK_API_KEY ?? 'sk-dummy-for-boot' },
+      env: {
+        ...process.env,
+        DEEPSEEK_API_KEY: process.env.DEEPSEEK_API_KEY ?? 'sk-dummy-for-boot',
+        DSH_HOME: join(consumer, '.dsh'),
+        DSH_AGENTS_HOME: join(consumer, '.agents'),
+      },
       stdio: ['pipe', 'pipe', 'pipe'],
     })
     const stderr: string[] = []
@@ -180,7 +185,12 @@ function runBinExpectingExit(configArg: string, cwd: string = tmpdir()): Promise
   return new Promise((resolve, reject) => {
     const proc = spawn(process.execPath, ['--expose-internals', acpBin, configArg], {
       cwd,
-      env: { ...process.env, DEEPSEEK_API_KEY: process.env.DEEPSEEK_API_KEY ?? 'sk-dummy-for-boot' },
+      env: {
+        ...process.env,
+        DEEPSEEK_API_KEY: process.env.DEEPSEEK_API_KEY ?? 'sk-dummy-for-boot',
+        DSH_HOME: join(cwd, '.dsh'),
+        DSH_AGENTS_HOME: join(cwd, '.agents'),
+      },
       stdio: ['pipe', 'pipe', 'pipe'],
     })
     child = proc

packages/ui/acp-agent/tests/load-path.e2e.ts

@@ -54,7 +54,7 @@ const CORDIS_YML = `
   name: '@deepseek-ai/dsh-acp-agent'
   config:
     model: deepseek-v4-flash
-    systemPrompt: 'You are a test agent.'
+    persona: 'You are a test agent.'
 `
 
 interface Spawned {
@@ -90,6 +90,8 @@ async function boot(): Promise<Spawned & { cwd: string }> {
         TSX_TSCONFIG_PATH: repoTsconfig,
         // Key-present check only; no prompt is sent, so the model is never called.
         DEEPSEEK_API_KEY: process.env.DEEPSEEK_API_KEY ?? 'keyless-acp-agent-smoke',
+        DSH_HOME: join(cwd, '.dsh'),
+        DSH_AGENTS_HOME: join(cwd, '.agents'),
       },
       stdio: ['pipe', 'pipe', 'pipe'],
     },

packages/ui/stdio-agent/README.md

@@ -1,6 +1,6 @@
 # @deepseek-ai/dsh-stdio-agent
 
-The **terminal stdio chat app**: a Cordis app plugin that composes the providerless agent spine ([`@deepseek-ai/dsh-agent-core`](../../core/agent-core/README.md)) with the front-door cluster a terminal chat needs, and a `bin` that boots a leaf `cordis.yml`.
+The **terminal stdio chat app**: a Cordis app plugin that composes the default agent spine ([`@deepseek-ai/dsh-agent-core`](../../core/agent-core/README.md)) with the front-door cluster a terminal chat needs, and a `bin` that boots a leaf `cordis.yml`.
 
 It is the readline counterpart to [`@deepseek-ai/dsh-acp-agent`](../acp-agent/README.md): both consume the same spine, but each bakes in the OPPOSITE front-door cluster.
 
@@ -11,7 +11,7 @@ A terminal chat always wants the same cluster, so the package owns it rather tha
 | Plugin | Why it is here |
 |---|---|
 | `@cordisjs/plugin-logger-console` | the console logger — stdout is just the terminal here, so logging to it is correct (the ACP app must NOT have this) |
-| `@deepseek-ai/dsh-agent-core` | the spine, pre-creating a `main` agent from this app's `model` and carrying its `persona` |
+| `@deepseek-ai/dsh-agent-core` | the spine, pre-creating a `main` agent from this app's `model` with `process.cwd()` as the fresh session cwd and carrying its `persona` |
 | `@deepseek-ai/dsh-session-persistence-jsonl` | durable JSONL session log under `persistenceRoot` |
 | `@deepseek-ai/dsh-user-interaction` | the human question/answer seam used by confirmation tools |
 | `@deepseek-ai/dsh-tool-ask-user` | the model-facing `ask_user_question` tool |
@@ -32,6 +32,8 @@ The leaf `cordis.yml` supplies only the **swappable backends** — an LLM adapte
 | `welcome` | `ready.` | the stdin-chat banner |
 | `resumeSessionId` | — | resume a persisted session id instead of starting fresh (sourced from an env var in the leaf) |
 
+Fresh stdio sessions use the process launch directory as `session.header.cwd`, so project-scoped features such as skill discovery and default bash workdir follow the directory where `dsh-stdio-agent` was started. Resumed sessions keep the cwd stored in the persisted session header.
+
 ## The bin
 
 `dsh-stdio-agent [path-to-cordis.yml]` (default `./cordis.yml`) loads a gitignored `.env` from the cwd (`DEEPSEEK_API_KEY` / `DEEPSEEK_BASE_URL`), then drives the cordis Loader against the config and awaits the whole plugin tree before returning. Run it under `node --expose-internals`: the cordis Loader resolves the config's bare plugin specifiers (`@deepseek-ai/dsh-*`, npm packages) through its internal module loader, which is only active under that flag. The `demo:echo` / `demo:repl` scripts invoke it that way.

packages/ui/stdio-agent/src/index.ts

@@ -1,5 +1,5 @@
 /**
- * The stdio chat app: the providerless agent spine ({@link
+ * The stdio chat app: the default agent spine ({@link
  * @deepseek-ai/dsh-agent-core}) plus the coupled front-door cluster a terminal
  * chat needs — a console logger, the readline UI (the in-package `stdio-chat`
  * module), JSONL session
@@ -58,7 +58,9 @@ export const name = 'stdio-agent'
  * {@link @deepseek-ai/dsh-agent-core}'s forwarded `agents` list); `persona` is
  * the deployment persona (forwarded to the system-prompt plugin); `toolOrder`
  * is the explicit model-facing tool order (forwarded to the system-prompt plugin);
- * `persistenceRoot` is the JSONL backend's directory; `welcome` is the UI banner.
+ * fresh sessions use `process.cwd()` as their workspace cwd; resumed sessions
+ * keep their persisted cwd. `persistenceRoot` is the JSONL backend's directory;
+ * `welcome` is the UI banner.
  */
 export interface Config {
   /** Model name for the `main` agent (must have a registered adapter). */
@@ -73,6 +75,8 @@ export interface Config {
   persistenceRoot?: string
   /** stdin-chat banner printed once on start. Defaults to `'ready.'`. */
   welcome?: string
+  /** Skill registry, local-provider, and model-facing consumer config forwarded to agent-core. */
+  skills?: agentCore.SkillConfig
   /**
    * If set, the `main` agent RESUMES this persisted session id instead of
    * starting fresh. Sourced from an env var in the leaf `cordis.yml`
@@ -91,6 +95,7 @@ export const Config: z<Config> = z.object({
   tools: ToolRegistry.Config,
   persistenceRoot: z.string().default('./.sessions'),
   welcome: z.string().default('ready.'),
+  skills: agentCore.SkillConfigSchema,
   resumeSessionId: z.string(),
 })
 
@@ -110,8 +115,10 @@ export function apply(ctx: Context, config: Config): void {
     agents: [{
       id: AgentId('main'),
       model: config.model,
+      cwd: process.cwd(),
       ...config.resumeSessionId !== undefined ? { resumeSessionId: SessionId(config.resumeSessionId) } : {},
     }],
+    ...config.skills !== undefined ? { skills: config.skills } : {},
   })
   ctx.plugin(SessionPersistenceJsonl, { root: config.persistenceRoot ?? './.sessions' })
   ctx.plugin(UserInteractionService)

packages/ui/stdio-agent/tests/built-bin.e2e.ts

@@ -92,7 +92,7 @@ async function makeConsumer(welcome: string, disabledBrokenEntry = false): Promi
     '  name: \'@deepseek-ai/dsh-stdio-agent\'',
     '  config:',
     '    model: mock-echo',
-    '    systemPrompt: \'demo\'',
+    '    persona: \'demo\'',
     `    welcome: '${welcome}'`,
     ...disabledBrokenEntry
       ? ['- id: off', '  name: \'./src/does-not-exist.ts\'', '  disabled: true']
@@ -111,7 +111,7 @@ function runBuiltBin(cwd: string, configArg: string, line: string): Promise<{ st
     const child = spawn(process.execPath, ['--expose-internals', stdioBin, configArg], {
       cwd,
       // Mock model: never calls the network, so no key needed.
-      env: { ...process.env },
+      env: { ...process.env, DSH_HOME: join(cwd, '.dsh'), DSH_AGENTS_HOME: join(cwd, '.agents') },
       stdio: ['pipe', 'pipe', 'pipe'],
     })
     let stdout = ''

packages/ui/stdio-agent/tests/stdio-agent.spec.ts

@@ -1,7 +1,11 @@
 import { describe, it, expect } from 'vitest'
+import { mkdtemp } from 'node:fs/promises'
+import { join } from 'node:path'
+import { tmpdir } from 'node:os'
 import { Context } from 'cordis'
 import Loader from '@cordisjs/plugin-loader'
 import { AgentId } from '@deepseek-ai/dsh-agent'
+import type { Message } from '@deepseek-ai/dsh-llm'
 import { TOOL_ORDER_REST } from '@deepseek-ai/dsh-system-prompt'
 import * as stdioAgent from '../src/index.ts'
 
@@ -30,9 +34,47 @@ async function mount(config: stdioAgent.Config): Promise<Context> {
   return ctx
 }
 
+async function isolatedSkillsConfig(catalogDescriptionMaxLength?: number): Promise<NonNullable<stdioAgent.Config['skills']>> {
+  const home = await mkdtemp(join(tmpdir(), 'dsh-stdio-agent-skills-'))
+  return {
+    local: { dshHome: join(home, '.dsh'), agentsHome: join(home, '.agents') },
+    ...catalogDescriptionMaxLength !== undefined ? { tool: { catalogDescriptionMaxLength } } : {},
+  }
+}
+
+async function composePrefix(ctx: Context): Promise<Message[]> {
+  const empty: Message[] = []
+  return await ctx.waterfall(
+    'agent/session-prefix', { session: { header: { cwd: '/tmp' } } } as never,
+    empty, new AbortController().signal, () => Promise.resolve(empty),
+  )
+}
+
+async function withIsolatedSkillHomes<T>(run: () => Promise<T>): Promise<T> {
+  const oldDshHome = process.env.DSH_HOME
+  const oldAgentsHome = process.env.DSH_AGENTS_HOME
+  const home = await mkdtemp(join(tmpdir(), 'dsh-stdio-agent-default-skills-'))
+  process.env.DSH_HOME = join(home, '.dsh')
+  process.env.DSH_AGENTS_HOME = join(home, '.agents')
+  try {
+    return await run()
+  } finally {
+    if (oldDshHome === undefined) {
+      delete process.env.DSH_HOME
+    } else {
+      process.env.DSH_HOME = oldDshHome
+    }
+    if (oldAgentsHome === undefined) {
+      delete process.env.DSH_AGENTS_HOME
+    } else {
+      process.env.DSH_AGENTS_HOME = oldAgentsHome
+    }
+  }
+}
+
 describe('dsh-stdio-agent app', () => {
   it('composes the spine + front-door cluster and pre-creates the main agent', async () => {
-    const ctx = await mount({ model: 'mock', persona: 'hi', persistenceRoot: '/tmp/dsh-stdio-agent-spec' })
+    const ctx = await mount({ model: 'mock', persona: 'hi', persistenceRoot: '/tmp/dsh-stdio-agent-spec', skills: await isolatedSkillsConfig() })
     // The spine services (brought up by the agent-core bundle) are all present.
     expect(ctx.get('agents')).toBeDefined()
     expect(ctx.get('agentLoop')).toBeDefined()
@@ -40,7 +82,9 @@ describe('dsh-stdio-agent app', () => {
     expect(ctx.get('userInteraction')).toBeDefined()
     expect(ctx.get('tools')?.get('ask_user_question')).toBeDefined()
     // The pre-created `main` agent the UI drives.
-    expect(ctx.get('agents')?.get(AgentId('main'))).toBeDefined()
+    const agent = ctx.get('agents')?.get(AgentId('main'))
+    expect(agent).toBeDefined()
+    expect(agent?.session.header.cwd).toBe(process.cwd())
     await ctx.fiber.dispose()
   })
 
@@ -51,13 +95,24 @@ describe('dsh-stdio-agent app', () => {
     // schema-bypassing direct-mount caller.
     const ctx = new Context()
     // No persona: covers the omitted-persona forwarding branch too.
-    stdioAgent.apply(ctx, { model: 'mock' })
+    stdioAgent.apply(ctx, { model: 'mock', skills: await isolatedSkillsConfig() })
     await new Promise(resolve => setTimeout(resolve, 80))
     expect(ctx.get('sessionPersistence')).toBeDefined()
     expect(ctx.get('agents')?.get(AgentId('main'))).toBeDefined()
     await ctx.fiber.dispose()
   })
 
+  it('uses default skill config when apply is called directly without skills', async () => {
+    await withIsolatedSkillHomes(async () => {
+      const ctx = new Context()
+      stdioAgent.apply(ctx, { model: 'mock' })
+      await new Promise(resolve => setTimeout(resolve, 80))
+      expect(ctx.skills).toBeDefined()
+      expect(await ctx.skills.list()).toEqual([])
+      await ctx.fiber.dispose()
+    })
+  })
+
   it('forwards resumeSessionId onto the pre-created agent when set', async () => {
     // A resume id defers agent creation until persistence loads; with no backing
     // session the resume is contained + logged, so no `main` agent registers —
@@ -67,11 +122,19 @@ describe('dsh-stdio-agent app', () => {
       persona: 'hi',
       persistenceRoot: '/tmp/dsh-stdio-agent-spec-resume',
       resumeSessionId: 'no-such-session',
+      skills: await isolatedSkillsConfig(),
     })
     expect(ctx.get('agents')?.get(AgentId('main'))).toBeUndefined()
     await ctx.fiber.dispose()
   })
 
+  it('forwards skill config into agent-core', async () => {
+    const ctx = await mount({ model: 'mock', persona: 'hi', skills: await isolatedSkillsConfig(6) })
+    ctx.skills.register({ name: 'stdio-skill', description: 'Stdio skill', source: 'runtime', content: 'body' })
+    expect(JSON.stringify(await composePrefix(ctx))).toContain('- `stdio-skill`: Std...')
+    await ctx.fiber.dispose()
+  })
+
   it('exposes its name and Config schema', () => {
     expect(stdioAgent.name).toBe('stdio-agent')
     expect(stdioAgent.Config).toBeDefined()
@@ -94,7 +157,7 @@ describe('dsh-stdio-agent app', () => {
       })
     }
     const assembly = await ctx.get('systemPrompt')!.assemble()
-    expect(assembly.tools.map(tool => tool.name)).toEqual(['zulu', 'alpha', 'ask_user_question'])
+    expect(assembly.tools.map(tool => tool.name)).toEqual(['zulu', 'alpha', 'ask_user_question', 'skill'])
     await ctx.fiber.dispose()
   })
 

packages/workflow/workflow-workerthread/src/protocol.ts

@@ -112,4 +112,3 @@ export type WorkerToHostMessage<T extends WorkerToHostType = WorkerToHostType> =
  */
 export type HostToWorkerMessage<T extends HostToWorkerType = HostToWorkerType> =
   { [K in T]: { type: K } & HostToWorkerPayloads[K] }[T]
-

pnpm-lock.yaml

@@ -335,12 +335,21 @@ importers:
       '@deepseek-ai/dsh-session':
         specifier: workspace:^
         version: link:../session
+      '@deepseek-ai/dsh-skill':
+        specifier: workspace:^
+        version: link:../../skill/skill
+      '@deepseek-ai/dsh-skill-local':
+        specifier: workspace:^
+        version: link:../../skill/skill-local
       '@deepseek-ai/dsh-system-prompt':
         specifier: workspace:^
         version: link:../system-prompt
       '@deepseek-ai/dsh-tool-bash':
         specifier: workspace:^
         version: link:../../bash/tool-bash
+      '@deepseek-ai/dsh-tool-skill':
+        specifier: workspace:^
+        version: link:../../skill/tool-skill
       '@deepseek-ai/dsh-tools':
         specifier: workspace:^
         version: link:../tools
@@ -745,6 +754,60 @@ importers:
         specifier: ^4.0.0-rc.6
         version: 4.0.0-rc.6(@cordisjs/plugin-include@1.0.4)(@cordisjs/plugin-loader@1.0.0-rc.4)
 
+  packages/skill/skill:
+    dependencies:
+      schemastery:
+        specifier: ^3.18.0
+        version: 3.18.0
+    devDependencies:
+      cordis:
+        specifier: ^4.0.0-rc.6
+        version: 4.0.0-rc.6(@cordisjs/plugin-include@1.0.4)(@cordisjs/plugin-loader@1.0.0-rc.4)
+
+  packages/skill/skill-local:
+    dependencies:
+      schemastery:
+        specifier: ^3.18.0
+        version: 3.18.0
+      yaml:
+        specifier: ^2.4.2
+        version: 2.9.0
+    devDependencies:
+      '@deepseek-ai/dsh-fs':
+        specifier: workspace:^
+        version: link:../../fs/fs
+      '@deepseek-ai/dsh-skill':
+        specifier: workspace:^
+        version: link:../skill
+      cordis:
+        specifier: ^4.0.0-rc.6
+        version: 4.0.0-rc.6(@cordisjs/plugin-include@1.0.4)(@cordisjs/plugin-loader@1.0.0-rc.4)
+
+  packages/skill/tool-skill:
+    dependencies:
+      schemastery:
+        specifier: ^3.18.0
+        version: 3.18.0
+    devDependencies:
+      '@deepseek-ai/dsh-agent':
+        specifier: workspace:^
+        version: link:../../core/agent
+      '@deepseek-ai/dsh-llm':
+        specifier: workspace:^
+        version: link:../../llm/llm
+      '@deepseek-ai/dsh-skill':
+        specifier: workspace:^
+        version: link:../skill
+      '@deepseek-ai/dsh-skill-local':
+        specifier: workspace:^
+        version: link:../skill-local
+      '@deepseek-ai/dsh-tools':
+        specifier: workspace:^
+        version: link:../../core/tools
+      cordis:
+        specifier: ^4.0.0-rc.6
+        version: 4.0.0-rc.6(@cordisjs/plugin-include@1.0.4)(@cordisjs/plugin-loader@1.0.0-rc.4)
+
   packages/subagent/subagent:
     devDependencies:
       '@deepseek-ai/dsh-agent':

scripts/gen-doc-graphs.ts

@@ -72,6 +72,7 @@ const GROUP_ORDER = [
   'bash',
   'sandbox',
   'fs',
+  'skill',
   'compact',
   'subagent',
   'web',
@@ -123,7 +124,7 @@ const SERVICE_ROLES: ServiceRole[] = [
     pkg: 'tools',
     title: 'Tool registry and execution waterfall',
     mode: 'core',
-    consumers: ['agent-loop', 'tool-ask-user', 'tool-bash', 'tool-cordis', 'tool-fs', 'tool-subagent', 'tool-todo', 'tool-web', 'acp'],
+    consumers: ['agent-loop', 'tool-ask-user', 'tool-bash', 'tool-cordis', 'tool-fs', 'tool-skill', 'tool-subagent', 'tool-todo', 'tool-web', 'acp'],
     note: 'Registers tool definitions, exposes schemas to the prompt, and routes calls through tools/pre-execute and tools/post-execute.',
   },
   {
@@ -135,6 +136,15 @@ const SERVICE_ROLES: ServiceRole[] = [
     consumers: ['tool-ask-user', 'stdio-agent', 'acp'],
     note: 'UI front doors provide the active human-answer provider; tool-ask-user pauses a tool call on the provider-neutral ask() promise.',
   },
+  {
+    key: 'skills',
+    pkg: 'skill',
+    title: 'Skill provider registry',
+    mode: 'seam',
+    implementations: ['skill-local'],
+    consumers: ['tool-skill'],
+    note: 'Merges provider skill catalogs; tool-skill renders the session-prefix catalog and loads complete skill bodies.',
+  },
   {
     key: 'agents',
     pkg: 'agent',

scripts/gen-module-graph.ts

@@ -42,6 +42,7 @@ const GROUP_ORDER = [
   'core',
   'bash',
   'fs',
+  'skill',
   'compact',
   'subagent',
   'web',

scripts/gen-tool-catalog.ts

@@ -47,10 +47,13 @@ import * as WebSearchExa from '@deepseek-ai/dsh-web-search-exa'
 import * as WebFetchLocal from '@deepseek-ai/dsh-web-fetch-local'
 import SubagentService from '@deepseek-ai/dsh-subagent'
 import * as SubagentMock from '@deepseek-ai/dsh-subagent-mock'
+import SkillService from '@deepseek-ai/dsh-skill'
+import * as SkillLocal from '@deepseek-ai/dsh-skill-local'
 import * as ToolAskUser from '@deepseek-ai/dsh-tool-ask-user'
 import * as ToolBash from '@deepseek-ai/dsh-tool-bash'
 import * as ToolCordis from '@deepseek-ai/dsh-tool-cordis'
 import * as ToolFs from '@deepseek-ai/dsh-tool-fs'
+import * as ToolSkill from '@deepseek-ai/dsh-tool-skill'
 import * as ToolTodo from '@deepseek-ai/dsh-tool-todo'
 import * as ToolSubagent from '@deepseek-ai/dsh-tool-subagent'
 import * as ToolWeb from '@deepseek-ai/dsh-tool-web'
@@ -180,6 +183,21 @@ const TOOL_PACKAGES: ToolPackage[] = [
     note:
       'The read-before-write/edit policy is added by `@deepseek-ai/dsh-fs-policy` (an `fs/*` event-gate plugin, no schema change); a deployment that loads these tools is expected to also load it. The tool schemas above are identical with or without the policy plugin.',
   },
+  {
+    pkg: '@deepseek-ai/dsh-tool-skill',
+    dir: 'tool-skill',
+    source: 'packages/skill/tool-skill/src/index.ts',
+    requires: ['ctx.tools', 'ctx.skills'],
+    writes: ['tool/call', 'tool/result'],
+    async mount(ctx) {
+      await ctx.plugin(SkillService)
+      await ctx.plugin(SkillLocal, {
+        dshHome: resolve(root, '.tmp/tool-catalog/.dsh'),
+        agentsHome: resolve(root, '.tmp/tool-catalog/.agents'),
+      })
+      await ctx.plugin(ToolSkill)
+    },
+  },
   {
     pkg: '@deepseek-ai/dsh-tool-subagent',
     dir: 'tool-subagent',

scripts/run-gates.ts

@@ -286,18 +286,28 @@ function demoSmokeGate(options: { needs?: string[] } = {}): Gate {
     ...dependencyOptions,
     verify: async (result) => {
       const output = result.stdout + result.stderr
-      if (!output.includes('[tool call] echo({"text":"ci smoke"})')) {
-        throw new Error('demo smoke did not show the echo tool call.')
+      const sessionsRoot = join(root, '.sessions')
+      try {
+        if (!output.includes('[tool call] echo({"text":"ci smoke"})')) {
+          throw new Error('demo smoke did not show the echo tool call.')
+        }
+        if (!output.includes('[tool result] ECHO: CI SMOKE')) {
+          throw new Error('demo smoke did not show the echo tool result.')
+        }
+        const buckets = await readdir(sessionsRoot, { withFileTypes: true })
+        let found = false
+        for (const bucket of buckets) {
+          if (!bucket.isDirectory() || !bucket.name.startsWith('cwd-')) continue
+          const entries = await readdir(join(sessionsRoot, bucket.name))
+          if (entries.some(entry => /^main-session-.+\.jsonl$/.test(entry))) {
+            found = true
+            break
+          }
+        }
+        if (!found) throw new Error('demo smoke did not create a main-session JSONL log in a cwd bucket.')
+      } finally {
+        await rm(sessionsRoot, { recursive: true, force: true })
       }
-      if (!output.includes('[tool result] ECHO: CI SMOKE')) {
-        throw new Error('demo smoke did not show the echo tool result.')
-      }
-      const sessionDir = join(root, '.sessions', '_no-cwd')
-      const entries = await readdir(sessionDir)
-      if (!entries.some(entry => /^main-session-.+\.jsonl$/.test(entry))) {
-        throw new Error('demo smoke did not create a main-session JSONL log.')
-      }
-      await rm(join(root, '.sessions'), { recursive: true, force: true })
     },
   }
 }

scripts/type-equiv.manifest.json

@@ -95,6 +95,16 @@
     { "doc": "docs/core-data-structures/filesystem.md", "symbol": "FsPolicyExec", "source": "packages/fs/fs-policy/src/types.ts" },
     { "doc": "docs/core-data-structures/filesystem.md", "symbol": "FileReadOutcome", "source": "packages/fs/tool-fs/src/read-render.ts" },
 
+    { "doc": "docs/core-data-structures/skills.md", "symbol": "SkillSource", "source": "packages/skill/skill/src/index.ts" },
+    { "doc": "docs/core-data-structures/skills.md", "symbol": "SkillResourceBase", "source": "packages/skill/skill/src/index.ts" },
+    { "doc": "docs/core-data-structures/skills.md", "symbol": "SkillSummary", "source": "packages/skill/skill/src/index.ts" },
+    { "doc": "docs/core-data-structures/skills.md", "symbol": "SkillCandidate", "source": "packages/skill/skill/src/index.ts" },
+    { "doc": "docs/core-data-structures/skills.md", "symbol": "SkillDefinition", "source": "packages/skill/skill/src/index.ts" },
+    { "doc": "docs/core-data-structures/skills.md", "symbol": "SkillRegistration", "source": "packages/skill/skill/src/index.ts" },
+    { "doc": "docs/core-data-structures/skills.md", "symbol": "SkillLookupOptions", "source": "packages/skill/skill/src/index.ts" },
+    { "doc": "docs/core-data-structures/skills.md", "symbol": "SkillProvider", "source": "packages/skill/skill/src/index.ts" },
+    { "doc": "docs/core-data-structures/skills.md", "symbol": "Config", "source": "packages/skill/skill/src/index.ts" },
+
     { "doc": "docs/core-data-structures/compaction.md", "symbol": "CompactionResult", "source": "packages/compact/compact/src/types.ts" },
 
     { "doc": "docs/core-data-structures/subagent.md", "symbol": "SubagentCapabilities", "source": "packages/subagent/subagent/src/types.ts" },

tsconfig.base.json

@@ -45,6 +45,7 @@
         "./packages/bash/*/src",
         "./packages/code-runtime/*/src",
         "./packages/fs/*/src",
+        "./packages/skill/*/src",
         "./packages/compact/*/src",
         "./packages/guard/*/src",
         "./packages/subagent/*/src",

tsconfig.build.json

@@ -22,6 +22,9 @@
     { "path": "./packages/ui/user-interaction" },
     { "path": "./packages/ui/user-approval" },
     { "path": "./packages/core/tools" },
+    { "path": "./packages/skill/skill" },
+    { "path": "./packages/skill/skill-local" },
+    { "path": "./packages/skill/tool-skill" },
     { "path": "./packages/ui/tool-ask-user" },
     { "path": "./packages/core/agent-loop" },
     { "path": "./packages/core/agent-core" },

tsconfig.json

@@ -33,6 +33,9 @@
     { "path": "./packages/ui/user-interaction" },
     { "path": "./packages/ui/user-approval" },
     { "path": "./packages/core/tools" },
+    { "path": "./packages/skill/skill" },
+    { "path": "./packages/skill/skill-local" },
+    { "path": "./packages/skill/tool-skill" },
     { "path": "./packages/ui/tool-ask-user" },
     { "path": "./packages/core/agent-loop" },
     { "path": "./packages/core/agent-core" },