refactor: split skill providers

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 + prompt listing
+@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       the model-facing skill 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,12 @@ This is the [interface/implementation/consumer seam](../../../docs/rfc/implement
 
 ```ts
 import type { Config } from '@deepseek-ai/dsh-agent-core'
-// { agents?, persona? } — the schema is z.intersect([AgentLoop.Config, SystemPrompt.Config]),
-// so validation and defaulting can never drift from the owners'.
+// { agents?, persona?, skills? } — the schema is z.intersect([AgentLoop.Config,
+// SystemPrompt.Config, { skills }]), 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`) — and `persona` to `dsh-system-prompt` (default `''`), the deployment's persona section. 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` to `dsh-system-prompt` (default `''`), and `skills.registry` / `skills.local` to the skill registry and local provider. 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",
@@ -29,6 +29,7 @@
     "@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",
@@ -43,6 +44,7 @@
     "@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:^",

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
- * skill registry, 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`
+ * 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,7 +52,8 @@ 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 from '@deepseek-ai/dsh-tools'
-import SkillService, { type Config as SkillConfig } from '@deepseek-ai/dsh-skill'
+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'
@@ -58,12 +62,20 @@ import AgentLoop, { type Config as AgentLoopConfig } from '@deepseek-ai/dsh-agen
 
 export const name = 'agent-core'
 
+/** Skill bundle config forwarded to the registry and the local provider. */
+export interface SkillConfig {
+  /** Registry-level prompt/cache settings. */
+  registry?: SkillRegistryConfig
+  /** Local filesystem skill provider settings. */
+  local?: SkillLocal.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` to the system-prompt plugin (the
- * deployment's persona section), and `skills` to the skill service. All three
- * are optional INPUT here because each owner's schema supplies the default
+ * deployment's persona section), and `skills` to the skill registry/local
+ * provider. All three are optional INPUT here because each owner's schema supplies the default
  * (`[]` / `''` / the DSH skill roots); the schema is the INTERSECTION of the
  * owners' own schemas, so validation and defaulting can never drift from them.
  */
@@ -72,12 +84,15 @@ export interface Config {
   agents?: AgentLoopConfig['agents']
   /** The deployment persona (see dsh-system-prompt's `Config`). */
   persona?: SystemPromptConfig['persona']
-  /** Skill discovery roots, system-skill installation, and prompt/cache bounds. */
+  /** Skill registry and local provider config. */
   skills?: SkillConfig
 }
 
 /** The skill config schema exported for app packages that forward `skills`. */
-export const SkillConfigSchema = SkillService.Config
+export const SkillConfigSchema: z<SkillConfig> = z.object({
+  registry: SkillService.Config,
+  local: SkillLocal.Config,
+})
 
 /** Intersect the owners' schemas so validation + defaulting stay identical. */
 export const Config = z.intersect([
@@ -105,12 +120,11 @@ export function apply(ctx: Context, config: Config): void {
   // introduce different ones.
   ctx.plugin(SystemPrompt, { persona: config.persona ?? '' })
   ctx.plugin(ToolRegistry)
-  ctx.plugin(SkillService, config.skills ?? {})
+  ctx.plugin(SkillService, config.skills?.registry ?? {})
+  ctx.plugin(SkillLocal, config.skills?.local ?? {})
   ctx.plugin(AgentRegistry)
   ctx.plugin(invariants)
   ctx.plugin(toolBash)
   ctx.plugin(toolSkill)
   ctx.plugin(AgentLoop, { agents: config.agents ?? [] })
 }
-
-export type { SkillConfig }

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

@@ -1,5 +1,5 @@
 import { describe, expect, it } from 'vitest'
-import { mkdtemp } from 'node:fs/promises'
+import { mkdir, mkdtemp, writeFile } from 'node:fs/promises'
 import { join } from 'node:path'
 import { tmpdir } from 'node:os'
 import { Context } from 'cordis'
@@ -9,7 +9,7 @@ import { AgentId } from '@deepseek-ai/dsh-agent'
 
 /**
  * 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
@@ -65,7 +65,7 @@ async function withIsolatedSkillHomes<T>(run: () => Promise<T>): Promise<T> {
 }
 
 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()
@@ -79,15 +79,12 @@ describe('dsh-agent-core bundle', () => {
     await ctx.fiber.dispose()
   })
 
-  it('includes the default skill system and skill tool', async () => {
+  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()).map(skill => skill.name)).toEqual(expect.arrayContaining([
-      'dsh-plugin-creator',
-      'dsh-skill-creator',
-    ]))
+    expect(await ctx.skills.list()).toEqual([])
 
     await ctx.fiber.dispose()
   })
@@ -122,18 +119,25 @@ describe('dsh-agent-core bundle', () => {
     await ctx.fiber.dispose()
   })
 
-  it('forwards skill config to the skill service', async () => {
+  it('forwards skill config to the registry and local provider', 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: {
-        dshHome: join(home, '.dsh'),
-        agentsHome: join(agentsHome, '.agents'),
-        installSystemSkills: false,
+        registry: { promptFieldMaxLength: 6 },
+        local: {
+          dshHome: join(home, '.dsh'),
+          agentsHome: join(agentsHome, '.agents'),
+          customSkillDirs: [custom],
+        },
       },
     })
-    expect(await ctx.skills.list()).toEqual([])
+    expect((await ctx.skills.list()).map(skill => skill.name)).toEqual(['custom-skill'])
+    expect(await ctx.skills.renderModelListing()).toContain('description: Cus...')
     await ctx.fiber.dispose()
   })
 
@@ -143,10 +147,7 @@ describe('dsh-agent-core bundle', () => {
       agentCore.apply(ctx, { agents: [] })
       await new Promise(resolve => setTimeout(resolve, 50))
       expect(ctx.skills).toBeDefined()
-      expect((await ctx.skills.list()).map(skill => skill.name)).toEqual(expect.arrayContaining([
-        'dsh-plugin-creator',
-        'dsh-skill-creator',
-      ]))
+      expect(await ctx.skills.list()).toEqual([])
       await ctx.fiber.dispose()
     })
   })

packages/core/agent-core/tsconfig.json

@@ -35,6 +35,9 @@
     {
       "path": "../../core/skill"
     },
+    {
+      "path": "../../core/skill-local"
+    },
     {
       "path": "../../core/tool-skill"
     },