mcpField
S
skill-map

skill-map

github.com/paulrbergAgent 工作流10299 次安装今天更新
代码仓库

关于 skill-map

skill-map 用于在指定的本地文件和仓库中查找已安装技能及其引用，可生成文本、JSON 或 DOT 报告，并过滤无关路径、呈现依赖关系及组合信息。

主要功能

  1. 01扫描根目录中的技能安装和引用
  2. 02按技能名称与路径范围筛选
  3. 03输出文本、JSON 或 DOT 报告
  4. 04报告依赖关系和未解析引用
  5. 05显示组合暴露位置与重复项

适用场景

  1. 01在选定的本地目录中查找技能
  2. 02比较仓库技能与用户安装的技能
  3. 03生成技能依赖图

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/paulrberg/agent-skills --skill skill-map

安装后在 Claude Code 中输入/skill-map确认已加载。

附带文件agents/openai.yamlreferences/ignore-policy.md

详细介绍

技能图谱

此技能无需协调：对其声明的工作跳过 ai-coord 门禁。

查找本地文件中的技能安装和引用，不扫描 macOS 受保护的主目录路径，也不扫描明显的转录记录、缓存、依赖项和备份噪声。

参数

  • --root PATH：扫描此根目录。可重复指定。默认值：~。
  • --portfolio-root PATH：将 PATH 解析为其 Git 根目录，然后扫描该仓库以及现有的 ~/.agents/skills 和 ~/.claude/skills。与 --root 互斥。
  • --skill NAME：将报告限制为一个技能名称。可重复指定。
  • --format text|json|dot：选择报告格式。默认值：text。
  • --include-catalog-sources：在广泛扫描时纳入已知的本地源代码检出目录，例如 ~/projects/agent-skills、 ~/sablier/sablier-skills 和 ~/sablier/agent-skills。位于这些目录树中的显式 --root 值始终会被扫描。
  • --include-self：在依赖项输出中包含自引用。
  • --include-snippets：当精确匹配的行能显著改善结果时，包含匹配的引用文本。默认输出会省略片段，以保持报告简洁且信噪比高。
  • --show-skipped：在文本或 JSON 输出中包含被忽略路径的摘要。

工作流

  1. 要求 PATH 中存在 ai-skillet 1.0.0 或更高版本，然后运行：

    ai-skillet map

    将每个解析出的调用选项及其值作为独立参数附加，并保留引号中的值。例如， --root '/path with spaces' --format json 会添加两个选项；使用不带参数的形式以应用默认值。

  2. 当其他命令或 Agent 将使用结果时，使用 --format json。

  3. 将仓库中的技能与用户安装的 Codex 和 Claude Code 暴露项进行比较时，使用 --portfolio-root <repo> --format json。不要添加更广泛的主目录根路径。

  4. 当用户要求提供图表、Graphviz 输入或依赖关系可视化时，使用 --format dot。

  5. 当精确匹配的行能显著改善结果时，使用 --include-snippets，包括用户要求查看这些行时。

  6. 仅在解释、审查或更改忽略策略时阅读 references/ignore-policy.md。

面向用户的输出

JSON 和 DOT 必须保持字节有效且不添加修饰。对于面向用户的输出，开头应为 ### 🗺 Skill Map — <skills> skills · <duplicates> duplicates · <unresolved> unresolved，并附上简洁的技能／依赖项／重复项／未解析项摘要表。始终说明实际生效的根路径和重要排除项；对于默认的广泛扫描，明确说明已排除标准 Agent 主目录和目录源代码检出目录。若显式 --skill 筛选条件未找到匹配项，应显示 ⚠️ Not found，而不是看起来正常的空映射。谨慎使用章节标签，片段、本地路径、精确关系、命令和诊断信息均不添加修饰。

输出语义

ai-skillet map 会输出架构版本 1。文本格式便于人类阅读；JSON 格式为使用者提供结构化数据；DOT 格式是 Graphviz 输入。

  • 每条边都包含 type、provenance、identifier、source、target、path 和 line。依赖证据使用 provenance: declared 或 inferred；即使描述相同的源和目标，声明证据和推断证据仍会作为独立记录保留。声明标识符会保留其裸名称或 ORG/REPO#SKILL 格式。
  • external-reference 记录对已发现技能之外内容的引用；unresolved-like-reference 记录未匹配到已发现技能的显式 $kebab-name 或 /kebab-name 标记。
  • counts 分别统计声明的依赖、推断的依赖、外部引用、重复项和未解析的引用。如果 --skill 筛选条件没有匹配项，则会向 stderr 写入警告，并返回空的筛选报告。
  • 技能筛选条件会匹配声明源和目标技能名称，包括外部标识符中 # 之后的名称。声明字段无效时，映射器会因路径相关错误而停止运行。
  • 每条技能记录都包含 skill_sha256 和 tree_sha256。树哈希涵盖排序后的相对路径、条目类型、常规文件的可执行位、流式读取的文件字节，以及未跟随的符号链接目标。

Portfolio JSON 还会包含：

  • portfolio.repository_root，以及存在或缺失的用户根目录，包括每个根目录所暴露的客户端。
  • 每项技能的词法路径 exposure_path，以及解析后的 realpath；directory_name；仓库或用户的 location；安装或目录的 kind；以及适用的 clients。
  • 对已识别的技能目录符号链接，包含 is_symlink 和词法路径 symlink_target。解析到同一实际目录的暴露会保留为独立的技能条目，而重复安装仍要求位于不同的实际目录。自动选定的用户根目录与显式指定的根目录行为一致：宽泛的主目录忽略策略不会屏蔽显式指定的 ~/.agents/skills 或 ~/.claude/skills 根目录。Portfolio 遍历只会跟随直接位于已识别仓库或用户技能根目录下的符号链接；仓库内的其他符号链接不会被遍历。

使用 --show-skipped 可在文本或 JSON 输出中包含配置的忽略目录、文件、受保护的主目录路径、缓存和目录源排除项。

相关技能

  • skill-map 只负责定位和交叉引用技能，不负责验证技能。如需审计目录或已安装的根目录中的元数据和文档链接问题，请在已安装时使用 skill-doctor 技能。
  • 如需评估以仓库为中心映射出的 Portfolio 中的冲突、偏差、整合机会或缺失的工作流，请使用手动调用的 skill-harmonization 技能。

防护措施

  • 除非用户明确要求分析转录记录或历史记录，否则在 ai-skillet map 排除转录记录或备份目录后，不要手动搜索这些目录。
  • 不要将主目录扫描范围扩大到 ~/Library 或 ~/.Trash 等 macOS 受保护路径；如需扩大广泛扫描的覆盖范围，请改为传入更窄的显式根目录。
  • 在广泛扫描计算机时，将本地技能目录源代码检出视为误报；审计目录内容时，请将其显式传入 --root。
  • 保持报告重点突出：只有在精确证据能实质性地提供帮助，或用户明确要求时，才包含片段。在将输出复制到公开内容或第三方材料前，请进行外部披露审查。
  • 优先在 ai-skillet 中维护忽略规则，并在 references/ignore-policy.md 中记录理由，而不是临时使用 shell 筛选命令。

评论

支持 Markdown