Knowledge Extension Ecosystem Skills And Custom Commands

Module Structure

Skills 与自定义命令共享“Markdown + frontmatter”的扩展形态，但加载与执行模型不同： Skills 启动时只暴露元数据并按需读取正文，命令发现时即读取正文并在调用时展开动态内容。

Directory Layout

• packages/cli/src/skills/ — Skill 解析、发现、安装、元数据注入与注册表
• packages/cli/src/slash-commands/custom/ — 自定义命令发现、解析、执行与注册表
• packages/cli/src/tools/builtin/system/skill.ts — 模型调用 Skill 的工具适配
• packages/cli/src/tools/builtin/system/slashCommand.ts — 模型调用自定义命令的工具适配
• .blade/skills/ — 当前仓库的项目级 Skills
• .blade/commands/ — 当前仓库的项目级自定义命令

Key Entry Points

• SkillRegistry.initialize() in packages/cli/src/skills/SkillRegistry.ts — 按来源优先级发现 Skill 元数据
• SkillRegistry.loadContent() in packages/cli/src/skills/SkillRegistry.ts — 调用时加载完整 Skill 正文
• CustomCommandRegistry.initialize() in packages/cli/src/slash-commands/custom/CustomCommandRegistry.ts — 建立 Workspace 命令视图
• CustomCommandRegistry.executeCommand() in packages/cli/src/slash-commands/custom/CustomCommandRegistry.ts — 展开命令正文
• snapshotWorkspaceAgentResources() in packages/cli/src/agent/resources/WorkspaceAgentResources.ts — 将两类注册表冻结到 Session

API Surface

SkillRegistry

• initialize() — 安装默认 Skill fallback、扫描来源并返回发现错误
• loadContent(name) — 对文件系统 Skill 延迟重读 SKILL.md，内置 Skill 走内存内容
• getModelInvocableSkills() — 排除 disable-model-invocation
• getUserInvocableSkills() — 仅返回 user-invocable: true
• generateAvailableSkillsList() — 生成稳定排序、描述有界的 Prompt 元数据
• snapshot() — 深拷贝元数据和插件 Skill，形成 Session 私有视图

CustomCommandRegistry

• initialize(workspaceRoot) — 发现命令并按 Workspace Trust 过滤项目来源
• executeCommand(name, context) — 执行参数、Shell 和文件引用展开
• executePluginCommand(name, context) — 将 namespaced plugin command 适配为普通命令执行
• generateCommandListDescription(charBudget) — 为 SlashCommand 工具生成有预算的目录
• snapshot() — 复制命令、插件命令和最近发现结果

Loaders

• loadSkillMetadata() / loadSkillContent() — 分离 Skill 元数据与正文读取(packages/cli/src/skills/SkillLoader.ts)
• CustomCommandLoader.discover() — 递归读取四个命令来源(packages/cli/src/slash-commands/custom/CustomCommandLoader.ts)

Usage Examples

冻结到 Session 资源快照 (packages/cli/src/agent/resources/WorkspaceAgentResources.ts)

return {
  projectRoot: path.resolve(projectRoot),
  subagents: resources.subagents.snapshot(),
  skills: resources.skills.snapshot(),
  commands: resources.commands.snapshot(),
  hooks: snapshotHookConfig(config),
};

将 Session 注册表注入工具 (packages/cli/src/tools/builtin/index.ts)

const skillRegistry = opts?.agentResources?.skills ?? getSkillRegistry({ cwd: resourceRoot });
const commandRegistry =
  opts?.agentResources?.commands ?? CustomCommandRegistry.getInstance(resourceRoot);
createSkillTool(skillRegistry);
createSlashCommandTool(commandRegistry);

把可由用户调用的 Skill 路由为 slash command (packages/cli/src/slash-commands/index.ts)

const skill = resources.skills
  .getUserInvocableSkills()
  .find((candidate) => candidate.name === command);
if (skill) {
  return createSkillSlashCommand(skill).handler(args, context);
}

Gotchas

• Skill 覆盖顺序最终以 .blade/skills 最高，而命令最终以 .claude/commands 最高；两套看似对称的目录不能套用同一优先级假设(packages/cli/src/skills/SkillRegistry.ts, packages/cli/src/slash-commands/custom/CustomCommandLoader.ts)
• 未信任 workspace 下，SkillRegistry 根本不扫描项目 Skill 目录；命令 loader 会先读取项目 Markdown，再由 Registry 过滤项目来源，二者的信任边界发生在不同阶段(packages/cli/src/skills/SkillRegistry.ts, packages/cli/src/slash-commands/custom/CustomCommandRegistry.ts)
• 活动 Session 持有注册表快照；调用 /skills 刷新 Workspace 注册表和插件资源不会改变已创建 Session 已看到的 Skill/命令集合(packages/cli/src/agent/resources/WorkspaceAgentResources.ts, packages/cli/src/slash-commands/skills.ts, git:f6a82242)
• Skill 工具 schema 接受 args，但当前实现只按名称加载正文，没有把参数插入 Skill 指令；不要把 argument-hint 当作运行时参数传递保证(packages/cli/src/tools/builtin/system/skill.ts)
• Skill 运行时解析器只识别 allowed-tools、argument-hint、user-invocable 和 disable-model-invocation 等 kebab-case key；使用文档示例中的 camelCase key 会被静默忽略(packages/cli/src/skills/SkillLoader.ts, docs/guides/skills.md)
• Skill 的 disable-model-invocation 只影响 available list，createSkillTool() 本身不再次拒绝已知名称；自定义命令工具则在执行前显式检查该字段(packages/cli/src/skills/SkillRegistry.ts, packages/cli/src/tools/builtin/system/skill.ts, packages/cli/src/tools/builtin/system/slashCommand.ts)
• 自定义命令的 ! Shell 嵌入由 execSync 在正文送给模型前直接执行，不经过 ToolExecutor 的常规工具权限、Hook 和调度；其安全前提是命令来源本身已受信(packages/cli/src/slash-commands/custom/CustomCommandExecutor.ts)
• 自定义命令的 @path 使用 path.resolve(workspaceRoot, value)，当前没有强制 workspace containment；命令作者可引用父目录或绝对解析结果，不能把它视为受限 Read 工具(packages/cli/src/slash-commands/custom/CustomCommandExecutor.ts)
• 命令解析异常在 CustomCommandParser.parse() 内记录后返回 null，不会进入 loader 的结构化 errors；发现结果为空不代表没有解析错误日志(packages/cli/src/slash-commands/custom/CustomCommandParser.ts, packages/cli/src/slash-commands/custom/CustomCommandLoader.ts)
• 内置 slash command 的解析优先级高于自定义命令、插件命令和 user-invocable Skill；同名扩展不会覆盖内置命令(packages/cli/src/slash-commands/index.ts)
• 插件 Skill/命令短名只有在唯一时才解析；有多个插件提供同名资源时必须使用完整 plugin:name，否则返回未找到而非任选一个(packages/cli/src/skills/SkillRegistry.ts, packages/cli/src/slash-commands/custom/CustomCommandRegistry.ts)
• 默认 Skill 安装失败只追加 discovery error，内置 skill-creator 和 update-config 仍作为离线 fallback，启动不会因此中断(packages/cli/src/skills/SkillRegistry.ts, packages/cli/src/skills/SkillInstaller.ts)