Skill loader returns 'unknown or no longer available' for skills that exist on disk (session catalog snapshot)

[allanyeahhill-dot]

GitHub Issue Draft — deepseek-ai/deepseek-harness

Title: Skill loader intermittently returns skill "X" is unknown or no longer available while the skill exists on disk — session skill catalog appears snapshotted at session start

Summary

The skill loader tool intermittently rejects skills with Error: skill "<name>" is unknown or no longer available, even though the skill's SKILL.md exists under ~/.dsh/skills/<name>/ and other sessions started minutes later load the same skill successfully. All observed failures fall inside a narrow time window in which the skill registry was being modified, which points at the session skill catalog being snapshotted (or scanned) at session start rather than resolved lazily at tool-call time.

Environment

• DSH version: v0.1.0-rc.6 (Windows 11, desktop shell dsh-desktop-electron, DSH_HOME=D:\dsh-home)
• Skills installed under ~/.dsh/skills/ (junctioned in bulk during setup)
• Provider: deepseek-official, model deepseek-v4-flash

Evidence

Failing sessions (both in ~/.dsh/sessions/--C-Users-Allan~0020Hill-AppData-Local-Temp-dsh-test--/):

session	createdAt (local)	occurrences
session-bc2caff8-e081-4959-9649-a253ded168b1	2026-08-14 09:54	9
session-a66ab322-2619-492b-a1b7-235ddfc4f4f1	2026-08-14 09:57	3

Verbatim tool result (role=user, isError: true):

Error: skill "wiki-ops" is unknown or no longer available

The assistant's own on-error observation (recorded in the session log):

"The skill tool says 'wiki-ops' is unknown or no longer available. The filesystem MCP server doesn't have access to ~/.dsh/skills."
"However, the skill loader tool says 'wiki-ops' is unknown or no longer available — meaning the session catalog (from the system reminder) does not include it."

Counter-example — success in a session started ~20 min later (session-117622a0-505a-48b2-9bf1-2d8d929cde3a, 08-14 10:14+):

<skill_content name="wiki-ops">
<skill_resources>
Base directory for this skill: C:\Users\Allan Hill\.dsh\skills\wiki-ops
...

Assistant verdict: "The wiki-ops skill loaded successfully. ✅ Succeeded."

Same skills directory, same machine — only the session start time differs.

Timing correlation

The two failing sessions started 09:54 and 09:57 — during a window when the skill registry on this machine was actively being modified (bulk-importing 69 skills, fixing skill frontmatter, verifying catalog registration). Sessions started after the registry settled load the skill without error. This matches: the skill catalog is built at session start from a registry scan that was mid-mutation (or from cached/stale state), and the loader hard-fails on any name absent from that snapshot — with no on-disk fallback.

Impact

• Intermittent skill unavailability in sessions started during/after registry changes; tasks that depend on a missing-from-catalog skill silently degrade (e.g., quality gates fall back to non-skill paths).
• Very confusing failure mode: the skill clearly exists on disk (SKILL.md readable), but the loader rejects it, and error messages carry no hint about the snapshot mechanism.

Suggested fix candidates

1. On-disk fallback: when the loader misses in the session catalog, scan ~/.dsh/skills/<name>/SKILL.md directly before returning "unknown" (also fixes stale/partial catalogs).
2. Lazy catalog resolution: resolve the skill catalog at tool-call time (or re-scan on miss), rather than trusting a session-start snapshot.
3. Registry mutation hygiene: serialize/exclude skill-registry writes while sessions are being created, or bump a registry version that sessions re-check.

Repro sketch

1. Install or remove a skill under ~/.dsh/skills/ while a DSH session is open (or immediately before starting one).
2. In a fresh session, invoke the skill tool with that skill's name.
3. Observe "unknown or no longer available" although SKILL.md exists on disk; repeat after registry settles → succeeds.

---

Drafted 2026-08-15 by Claude from session-log evidence (see dsh_dream_worker.py cluster #4, ~/.dsh/sessions/ archives). Session files are zstd-compressed JSONL; the quoted excerpts are verbatim.

[denial123789]

这个时间相关性很有价值，但从 rc.6 当前实现看，“catalog 在 session start 固定快照”并不是既定机制，需要先把这个假设与复现分开：

• dsh-tool-skill 在每个 eligible agent/pre-step 调用 ctx.skills.snapshot({cwd, scope: agent})；digest 变化会向同一 session 追加完整 replacement catalog。
• skill tool 每次执行时都会用当前 Agent scope 现场调用 ctx.skills.list()，找到 summary 后再调用 ctx.skills.get() 读取当前 body。
• filesystem provider 默认 watch: true，catalog frontmatter 的新增/删除/修改会 invalidation；完整 body 则每次 load 重新读取。

所以报错能证明的是“该次 live scoped lookup 没有解析出这个 name，或它在 list→get 之间消失”，还不能证明它只信任 session 里的旧 catalog。

这组环境里更值得优先验证：

1. 运行进程实际使用的 DSH_HOME 是否始终是 D:\dsh-home，而不是 UI/子进程落到另一个 home。
2. junction 批量建立期间，watcher/discovery 是否报告 I/O error 或 incomplete snapshot；不要只看目标 SKILL.md 最终存在。
3. frontmatter 在失败时刻是否已经是有效 kebab-case name + 非空 description；malformed entry 会被跳过并记录 warning。
4. 同名 skill 是否被更高 rank 的 project/custom layer shadow，且 winning candidate 在扫描期间变化。
5. 失败发生在第一次 list() miss，还是 summary 已找到但第二次 get() miss；目前两处使用同一句错误文案，session log 本身无法区分。

建议的最小判定测试是：先用一个稳定目录启动 session 并完成一次 step，再原子地加入全新 skill，等待 watcher stability window 后，在同一 session 的下一 step观察 replacement <available_skills>，随后调用它。按设计无需新建 session；如果只有新 session 成功，就是可操作的 hot-refresh 回归证据。

不建议用“miss 后直接读取 ~/.dsh/skills/<name>/SKILL.md”作为通用修复。那会绕过 cwd/project scope、provider precedence、custom roots、disable-model-invocation 和非 filesystem provider，可能把本来不可对模型暴露的 skill 打开。更安全的修复方向是让 live registry lookup 在 incomplete/racing observation 时重试稳定 revision，并把 incomplete discovery、summary vanished before get 与真正 unknown 分成不同诊断。

对应源码与契约：

• Per-step hot refresh:

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

  Lines 216 to 247 in 47f9438

  	): Promise<PreStepDecision> => {
  	const decision = await next()
  	if (decision.kind === 'reject') return decision
  	signal.throwIfAborted()
  	const toolVisible = ctx.tools.get(skillTool.name, agent) === skillTool
  	const snapshot = toolVisible
  	? await ctx.skills.snapshot({ cwd: agent.session.header.cwd, signal, scope: agent })
  	: { skills: [], complete: true }
  	signal.throwIfAborted()
  	if (!snapshot.complete) return decision
  	const skills = snapshot.skills.filter(isModelInvocable)
  	const entries = catalogSourceEntries(skills, catalogDescriptionMaxLength)
  	const digest = digestCatalogEntries(entries)
  	const history = catalogHistory(agent)
  	const existing = catalogMessage(decision.messages)
  	if (history.visibleDigest === digest) {
  	return existing === undefined
  	? decision
  	: { kind: 'enter', messages: decision.messages.filter(message => message.id !== existing.message.id) }
  	}
  	if (existing !== undefined && digestCatalogEntries(existing.entries) === digest) return decision
  	if (!history.published && skills.length === 0) {
  	return existing === undefined
  	? decision
  	: { kind: 'enter', messages: decision.messages.filter(message => message.id !== existing.message.id) }
  	}
  	const catalog = history.published
  	? renderCatalogUpdate(entries)
  	: renderCatalogMessage(entries)
  	return {
  	kind: 'enter',
  	messages: existing === undefined

• Live list→get loader:

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

  Lines 122 to 149 in 47f9438

  	content: { type: 'string', required: true },
  	},
  	},
  	render: (_args, value) => [{ type: 'text', text: renderSkillContent(value) }],
  	},
  	async execute(args, exec) {
  	if (!isSkillName(args.name)) {
  	throw new Error(`invalid skill name "${args.name}"`)
  	}
  	// The agent is its own scope key, so the lookup resolves the layered
  	// registry exactly as this agent's composition sees it.
  	const lookup = { cwd: exec.agent?.session.header.cwd, signal: exec.signal, scope: exec.agent }
  	const summary = (await ctx.skills.list(lookup)).find(skill => skill.name === args.name)
  	if (!summary) {
  	throw new Error(`skill "${args.name}" is unknown or no longer available`)
  	}
  	if (!isModelInvocable(summary)) {
  	throw new Error(`skill "${args.name}" is not available for model invocation`)
  	}
  	const skill = await ctx.skills.get(args.name, lookup)
  	if (!skill) {
  	throw new Error(`skill "${args.name}" is unknown or no longer available`)
  	}
  	if (!isModelInvocable(skill)) {
  	throw new Error(`skill "${args.name}" is not available for model invocation`)
  	}
  	return {
  	name: skill.name,

• Filesystem watcher and current-body contract: https://github.com/deepseek-ai/deepseek-harness/blob/47f943859bef60e4160492346772ded9b24f765a/packages/skill/skill-filesystem/README.md#catalog-change-detection

Handbook 的 Skill discovery / precedence / invocation 图：
https://github.com/sandbaseai/deepseek-harness-handbook/blob/main/docs/en/agent-patterns/skills.md