const SKILL_NAME = /^[a-z0-9]+(?:-[a-z0-9]+)*$/const DEFAULT_COLLECT_CACHE_ENTRIES = 128const MAX_COLLECT_ATTEMPTS = 2const RUNTIME_PROVIDER = 'runtime'const RUNTIME_RANK = 250/** Standard precedence rank for packaged skill providers and local bundled roots. */export const BUNDLED_SKILL_RANK = 600/** Return whether a string is a valid kebab-case skill name. */export function isSkillName(name: string): boolean {  return SKILL_NAME.test(name)}/** Origin bucket for a skill contribution — prompt-visible metadata, not precedence by itself. */export type SkillSource = 'project-dsh' | 'project-agents' | 'runtime' | 'user-dsh' | 'user-agents' | 'custom' | 'bundled' | (string & {})

/** Invocation controls shared by skill discovery consumers. */export interface SkillInvocationPolicy {  /** Whether model-facing catalogs and loaders include this skill. */  readonly modelInvocable: boolean  /** Whether human-facing command catalogs and loaders include this skill. */  readonly userInvocable: boolean}/** Invocation-neutral skill metadata returned by `ctx.skills.list()`. */export interface SkillSummary {  readonly name: string  readonly description: string  readonly whenToUse?: string  readonly invocation: SkillInvocationPolicy  readonly source: SkillSource  readonly provider: string  readonly 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. */  readonly rank: number  /** Opaque provider-owned handle passed back to `provider.get()`. */  readonly locator: unknown  readonly path?: string  readonly metadata?: Readonly<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. */  readonly content: string  readonly path?: string  readonly metadata?: Readonly<Record<string, unknown>>}

/** 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. */  readonly name: string  /**   * List available skill candidates for the current lookup context.   * @returns provider candidates as a complete-array shorthand, or an explicit   *   observation when usable candidates came from incomplete discovery.   */  readonly list: (options: SkillLookupOptions) => Promise<readonly SkillCandidate[] | SkillProviderObservation>  /**   * Load a complete skill body for a previously listed candidate.   * @returns the full skill body, or `undefined` if it is no longer loadable.   */  readonly get: (candidate: SkillCandidate, options: SkillLookupOptions) => Promise<SkillDefinition | undefined>}

registerProvider(create: (control: SkillProviderControl) => SkillProvider): () => void {    const lifecycle = new AbortController()    let registration: { layer: SkillLayer; name: string } | undefined    let provider: SkillProvider    const control: SkillProviderControl = {      signal: lifecycle.signal,      invalidate: () => {        const active = registration        if (active !== undefined && active.layer.providers.get(active.name)?.provider === provider) {          this.invalidateCache()        }      },    }    try {      provider = create(control)      const name = provider.name      if (name === RUNTIME_PROVIDER) {        throw new Error(`"${RUNTIME_PROVIDER}" is reserved for runtime skill registrations`)      }      const order = this.nextProviderOrder      this.nextProviderOrder += 1      return this.layers.effect(        this.ctx,        (layer) => {          const undo = layer.providers.insert(name, { provider, order })          registration = { layer, name }          return () => {            registration = undefined            undo()            lifecycle.abort(new Error(`skill provider "${name}" disposed`))          }        },        { label: 'skills.registerProvider()' },      )    } catch (error) {      lifecycle.abort(error)      throw error    }  }

private async collect(options: SkillViewOptions): Promise<CollectResult> {    throwIfAborted(options.signal)    let attempt = 1    while (true) {      const revision = this.revision      // The chain is part of the key rather than assumed stable: a blank-session      // recompose re-parents an existing scope without touching this registry,      // and only a chain-bearing key makes the next read see the new preset.      const key = this.collectCacheKey(options.cwd, scopeChainOf(options.scope), revision)      const cached = this.collectCache.get(key)      if (cached !== undefined) return { entries: cached, cacheable: true }      const result = await this.collectFresh(options)      throwIfAborted(options.signal)      if (revision !== this.revision) {        if (attempt < MAX_COLLECT_ATTEMPTS) {          attempt += 1          continue        }        return { entries: result.entries, cacheable: false }      }      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    }  }

private async collectFresh(options: SkillViewOptions): Promise<CollectResult> {    // Global first, then existing chain overlays farthest ancestor first and    // the exact scope last, so the nearest layer's same-name entry replaces    // the farther ones — the tools registry's shadowing rule. Rank decides    // duplicates only within one layer.    const layers = [this.layers.global, ...this.layers.chainLayers(options.scope)]    const merged = new Map<string, IndexedCandidate>()    let cacheable = true    for (const layer of layers) {      const collected = await this.collectLayer(layer, options)      if (!collected.cacheable) cacheable = false      for (const entry of collected.entries) merged.set(entry.candidate.name, entry)    }    return { entries: merged, cacheable }  }

private async listLayerCandidates(layer: SkillLayer, options: SkillLookupOptions): Promise<LayerCollectResult> {    throwIfAborted(options.signal)    const candidates: IndexedCandidate[] = []    let cacheable = true    for (const { provider, order } of [...layer.providers.values()]) {      let localOrder = 0      let output: unknown      try {        output = 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 (output === undefined) continue      const observation = normalizeProviderObservation(output, provider.name)      if (!observation.complete) cacheable = false      for (const candidate of observation.candidates) {        validateCandidate(candidate, provider.name)        candidates.push({ candidate, provider, providerOrder: order, localOrder, layer })        localOrder += 1      }    }    return { entries: candidates, cacheable }  }

async get(name: string, options: SkillViewOptions = {}): Promise<SkillDefinition | undefined> {    if (!isSkillName(name)) return undefined    const collected = await this.collect(options)    throwIfAborted(options.signal)    const match = collected.entries.get(name)    if (match === undefined) return undefined    const definition = await waitWithAbort(      match.provider.get(match.candidate, options),      options.signal,    )    if (definition === undefined) return undefined    validateDefinition(definition)    if (definition.name !== match.candidate.name) {      this.invalidateEntry(match)      return undefined    }    return definition  }

const PROJECT_DSH_RANK = 100const PROJECT_AGENTS_RANK = 200const CUSTOM_RANK = 300const USER_DSH_RANK = 400const USER_AGENTS_RANK = 500const DEFAULT_WATCH_STABILITY_THRESHOLD_MS = 200const DEFAULT_WATCH_POLL_INTERVAL_MS = 100const DEFAULT_WATCH_MAX_PROJECTS = 128

private async roots(cwd: string | undefined): Promise<SkillRoot[]> {    const roots: SkillRoot[] = []    if (this.includeDefaultRoots && 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, projectRoot },        { path: join(projectRoot, '.agents/skills'), source: 'project-agents', rank: PROJECT_AGENTS_RANK, projectRoot },      )    }    roots.push(...this.customSkillDirs.map(path => ({ path, source: 'custom' as const, rank: CUSTOM_RANK })))    if (this.includeDefaultRoots) {      roots.push(        { 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 },      )    }    if (this.bundledSkillDir !== undefined) {      roots.push({ path: this.bundledSkillDir, source: 'bundled', rank: BUNDLED_SKILL_RANK, trustedHost: true })    }    return roots  }

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 parseInvocationPolicy(data: Record<string, unknown>): SkillInvocationPolicy {  rejectLegacyInvocationKey(data, 'disableModelInvocation', 'disable-model-invocation')  rejectLegacyInvocationKey(data, 'modelInvocable', 'disable-model-invocation')  rejectLegacyInvocationKey(data, 'userInvocable', 'user-invocable')  const disableModelInvocation = frontmatterBoolean(data, 'disable-model-invocation')  const userInvocable = frontmatterBoolean(data, 'user-invocable')  return {    modelInvocable: disableModelInvocation !== true,    userInvocable: userInvocable !== false,  }}

private async openStableWatcher(state: RootWatchState): Promise<WatchHandle | undefined> {    while (!this.closing && state.owners.size > 0) {      const mode = await resolveRootWatchMode(state.root.path, this.config.followSymlinks)      const watcher = mode.kind === 'ancestor'        ? this.openAncestorWatcher(state, mode)        : await this.openRootWatcher(state, mode)      const current = await resolveRootWatchMode(state.root.path, this.config.followSymlinks)      if (sameWatchMode(mode, current)) return watcher      await this.closeWatcher(watcher)    }    return undefined  }

private handleWatchEvent(state, mode, event, path): void {    const target = resolve(path)    if (this.closing || !isRelevantWatchEvent({ ...state.root, path: mode.anchor }, event, target)) return    this.queueInvalidation()    if (target === mode.anchor && event === 'unlinkDir') {      state.unhealthy = true      this.scheduleRewatch(state)    }  }

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`)      }      return { name: skill.name, provider: skill.provider, content: skill.content }    },

function digestCatalogEntries(entries: SkillCatalogSource['entries']): string {  // JSON per entry rather than a separator character: every separator is itself  // a legal description character, so only quoting makes the boundary exact.  const canonical = entries.map(entry => JSON.stringify([entry.name, entry.description])).join('\n')  return createHash('sha256').update(canonical).digest('hex')}

ctx.on('agent/pre-step', async ({ agent, signal }, next): 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 }    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(m => m.id !== existing.message.id) }    }

const SKILL_GESTURE = /(^|\s)\/([a-z0-9]+(?:-[a-z0-9]+)*)(?=\s|$)/gfunction invokedSkillNames(messages: readonly UserMessage[]): string[] {  const names: string[] = []  for (const message of messages) {    if ((message.source as { kind?: unknown }).kind !== 'user') continue    for (const block of message.content) {      if (block.type !== 'text') continue      for (const match of block.text.matchAll(SKILL_GESTURE)) {        const name = match[2]        if (name !== undefined && !names.includes(name)) names.push(name)      }    }  }  return names}

export function renderSkillContent(skill): 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')}

/** Escape model-facing prose embedded inside skill markup so provider-supplied text cannot open or close framing tags. */export function escapeText(value: string): string {  return value.replaceAll('&', '&amp;').replaceAll('<', '&lt;').replaceAll('>', '&gt;')}

skill({name}) / /name 手势 全链路

① tool-skill 的 pre-step 监听器：digest 比对，目录变化才注入/替换 <system-reminder>

② 模型看到目录摘要（name+description），决定调用 skill 工具 / 用户写 /name

③ execute()：scope=agent，ctx.skills.list() → collect()（缓存键含 scope 链+revision）

④ collectFresh()：全局层→scope 链合并，最近层同名胜出；单层内 rank→order→localOrder

⑤ isModelInvocable(summary) 检查（仅用户可调的技能在此被拒）

⑥ ctx.skills.get()：传回 locator → provider.get() 重读正文（waitWithAbort 竞争 signal）

⑦ validateDefinition + 名字一致性校验（改名则失效重发现）

⑧ renderSkillContent()：<skill_content>+<skill_resources>+<skill_instructions>，escapeText 防标签逃逸

⑨ 模型按正文指令执行；watcher 监听文件变更 → invalidateCache() → 下步 digest 变化重发目录