mcpField
S
skills-management

skills-management

github.com/codealive-aiAgent 工作流16753 次安装今天更新
代码仓库

关于 skills-management

skills-management 是面向 Agent 技能维护者的命令行管理工具，涵盖技能发现、审查、迁移、测试与迭代优化，并可检查不同 Agent 环境中的重复项。

主要功能

  1. 01列出、查看、审查和删除技能
  2. 02在用户与项目范围间迁移技能
  3. 03检测重复项并管理 Agent 副本
  4. 04通过任务评估优化技能
  5. 05测试触发条件与跨 Agent 迁移

适用场景

  1. 01审查技能并按建议改进
  2. 02安装前检查技能名称是否重复
  3. 03使用代表性任务评估技能变更

安装

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

$npx skills add https://github.com/codealive-ai/ai-driven-development --skill skills-management

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

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

prompts/
analyst_error.md
analyst_success.md
blind_comparator.md
grader.md
merge_failure.md
merge_final.md
merge_success.md
meta_skill.md
ranking.md
slow_update.md
references/
01-introduction.md
02-fundamentals.md
03-planning-and-design.md
04-testing-and-iteration.md
05-distribution-and-sharing.md
06-patterns-and-troubleshooting.md
07-resources-and-references.md
opencode-skills.md
optimization-artifacts-schemas.md
optimization-grading-checklist.md
ref-a-quick-checklist.md
ref-b-yaml-frontmatter.md
ref-c-complete-skill-examples.md
remote-skill-assessment.md
skill-deduplication.md
skill-optimization.md
scripts/
agents.py
aggregate_runs.py
audit_skill_duplicates.py
blind_comparator.py

详细介绍

技能管理器

快速参考

任务命令
列出全部python3 scripts/list_skills.py
按范围列出python3 scripts/list_skills.py -s user 或 -s project
查看详情python3 scripts/show_skill.py <name>
审核技能python3 scripts/review_skill.py <name>
删除python3 scripts/delete_skill.py <name>
从 Agent 中删除python3 scripts/delete_skill.py <name> --all-agents --force
移至用户范围python3 scripts/move_skill.py <name> user
移至项目范围python3 scripts/move_skill.py <name> project
审计重复名称python3 scripts/audit_skill_duplicates.py
预检安装python3 scripts/audit_skill_duplicates.py --candidate /path/to/skill --fail-on-conflict
新建使用 /skill-creator
优化与迭代（SkillOpt 风格）
规划优化python3 scripts/optimize_skill.py <name> --tasks tasks.jsonl --dry-run
运行优化python3 scripts/optimize_skill.py <name> --tasks tasks.jsonl --output-dir runs/r1
记录手动编辑python3 scripts/log_skill_edit.py <name> --reason "..." --snapshot
列出最近的编辑python3 scripts/log_skill_edit.py <name> --list --since 7d
与上一个快照比较差异python3 scripts/diff_skill_versions.py <name> --log --format stats
比较提交之间的差异python3 scripts/diff_skill_versions.py <name> --git HEAD~3 HEAD
触发测试python3 scripts/trigger_test.py <name> --cases cases.yaml
生成触发用例python3 scripts/trigger_test.py <name> --generate > cases.yaml
迁移测试python3 scripts/transfer_test.py <name> --all
汇总运行结果python3 scripts/aggregate_runs.py runs/*
比较运行结果python3 scripts/aggregate_runs.py runs/r1 runs/r2 --compare
基于断言评分的运行python3 scripts/optimize_skill.py <name> --tasks tasks.jsonl --verifier assertions
多次运行方差python3 scripts/optimize_skill.py <name> --tasks tasks.jsonl --runs-per-task 3
盲测 A/B 对比python3 scripts/blind_comparator.py --skill-a runs/r1/initial_skill.md --skill-b runs/r1/best_skill.md --tasks tasks.jsonl --output-dir cmp/
HTML 查看器python3 scripts/eval_viewer.py runs/r1
比较两次运行（HTML）python3 scripts/eval_viewer.py runs/r1 runs/r2 --compare
发现与安装
查找技能npx skills find [query]
审核远程技能获取 skills.sh 页面，并使用评估框架进行评估
列出生态系统技能npx skills list 或 npx skills ls
从 GitHub 安装npx skills add <owner/repo@skill> -g -y
移除生态系统技能npx skills remove <name> -g -y 或 npx skills rm
检查已安装版本读取锁定元数据和上游状态；不要假定 npx skills check 是只读操作
更新全部npx skills update
在线浏览skills.sh
多 Agent
检测 Agentpython3 scripts/detect_agents.py
列出 Agent 技能python3 scripts/list_agent_skills.py --agent cursor
安装到 Agentpython3 scripts/install_skill.py /path --agent cursor
在 Agent 之间复制python3 scripts/copy_skill.py <name> --from claude-code --to cursor
在 Agent 之间移动python3 scripts/move_skill_agent.py <name> --from claude-code --to cursor

范围与副本唯一性原则

技能发现因使用方而异。Codex 使用 $HOME/.agents/skills 存放用户技能， 从当前工作目录（CWD）向上扫描 .agents/skills，直到仓库根目录，并会跟随符号链接。其他 Agent 使用 scripts/agents.py 中的路径；插件则会添加一层单独管理的命名空间。

每种使用方拓扑中，同一个 frontmatter name 只能有一个生效的实现。指向同一个真实目录的别名不算独立副本；可能需要保留完全相同的 Agent 专属副本，但全局／仓库／插件之间存在差异的副本，则需要确定规范来源。 安装、去重、迁移或解决插件与独立版本之间的冲突前，请阅读 skill-deduplication.md。

操作

列出技能
python3 scripts/list_skills.py              # All skills
python3 scripts/list_skills.py -s user      # User scope only
python3 scripts/list_skills.py -f json      # JSON output
查看技能详情
python3 scripts/show_skill.py <name>           # Basic info
python3 scripts/show_skill.py <name> --files   # Include file listing
python3 scripts/show_skill.py <name> -f json   # JSON output
审查技能

根据最佳实践审查技能并提出改进建议：

python3 scripts/review_skill.py <name>         # Review with text output
python3 scripts/review_skill.py <name> -f json # JSON output for programmatic use

检查项目：

  • 名称格式（小写、连字符、最多 64 个字符、动名词形式）
  • 名称与目录名一致
  • 描述质量（触发条件、否定触发条件、第三人称、具体程度）
  • frontmatter 中的 XML 尖括号（安全性）
  • 禁止的文档文件（README.md、CHANGELOG.md）
  • 正文长度（超过 500 行时发出警告）
  • Token 占用（每项技能的目标为 300–2000 个 token，符合 SkillOpt；达到 2000 时发出警告，达到 4000 时扣分）
  • 过程性（实例专属标记——文件名、具体数字、任务引用——应尽量少）
  • 补丁友好性（锚点密度：需要 ##／### 标题和 **标签：** 标记，才能可靠地进行 insert_after 编辑）
  • 慢更新区段完整性（/ 标记必须成对且不能嵌套）
  • 时效性内容
  • 路径格式（不得使用 Windows 反斜杠）
  • 引用深度（应为一层）
  • 长文件的目录

**审查后：**阅读技能的 SKILL.md，并直接应用建议的修正。

删除技能

**重要：**删除前务必使用 AskUserQuestion 确认：“确定要删除技能‘[name]’吗？此操作无法撤销。”

python3 scripts/delete_skill.py <name>              # Claude Code only, with confirmation
python3 scripts/delete_skill.py <name> --force      # Skip confirmation prompt
python3 scripts/delete_skill.py <name> -s project   # Target specific scope
python3 scripts/delete_skill.py <name> -a cursor    # Delete from specific agent
python3 scripts/delete_skill.py <name> --all-agents --force  # Delete from all agents

**多 Agent 删除：**通过 npx skills add 安装的技能可能存在于多个 Agent 目录中。默认模式（不带标志）仅从 Claude Code 删除，并会在其他 Agent 中仍有副本时发出警告。使用 --all-agents 可一次性从所有检测到的 Agent 中删除技能。

对于通过生态系统安装的技能，优先使用 npx skills remove <name> -g -y。手动清理时，可将 delete_skill.py --all-agents 作为后备方案。

移动技能
python3 scripts/move_skill.py <name> user      # Project → User (personal)
python3 scripts/move_skill.py <name> project   # User → Project (share with team)
python3 scripts/move_skill.py <name> user -f   # Overwrite if exists
修改技能
  1. 运行 python3 scripts/show_skill.py <name> 定位技能
  2. 直接在返回的路径中编辑 SKILL.md
创建新技能

使用 /skill-creator 技能，按照规范结构引导创建。

优化技能（SkillOpt 风格）

将技能视为可训练的文本制品：有界编辑 + 留出集验证门槛 + 已拒绝编辑缓冲区 + 按轮次进行慢更新。完整方法请参阅 references/skill-optimization.md（Microsoft、arXiv 2605.23904，2026 年 5 月）。

适用情形：

  • 技能已存在，但在可衡量的任务集上表现不佳
  • 你已有（或可以编写）验证器——精确匹配、输出评分或 LLM 评审器
  • 你可以生成 20–100 个有代表性的任务及参考答案

不适用情形：

  • 任务没有可衡量的成功信号——有界文本优化需要验证门槛
  • 从零开始创建技能——先用 /skill-creator 编写 v0 版本
  • 只有 1–5 个任务可用——该流程需要成批证据
运行该流程
# 1. Dry-run to see the plan (splits, schedule, prompt previews)
python3 scripts/optimize_skill.py <name> \
    --tasks tasks.jsonl --epochs 4 --edit-budget 4 \
    --output-dir runs/r1 --dry-run

# 2. Real run
python3 scripts/optimize_skill.py <name> \
    --tasks tasks.jsonl --output-dir runs/r1 \
    --optimizer-cmd "claude -p --model claude-opus-4-7" \
    --target-cmd  "claude -p --model claude-haiku-4-5-20251001"

# 3. Inspect
cat runs/r1/optimization_report.md
python3 scripts/diff_skill_versions.py <name> --files \
    runs/r1/initial_skill.md runs/r1/best_skill.md --format stats

该流程会生成 best_skill.md、optimization_report.md、edit_apply_report.json、rejected_buffer.json 和 meta_skill.json（仅供优化器使用，不随技能发布）。

手动编辑审计记录

对于在流程外完成的编辑（手动微调、错误修复后的跟进），请保留一份简要日志：

# After saving an edit
python3 scripts/log_skill_edit.py <name> \
    --reason "tightened insert_after target" \
    --source from-bug --ref "issue #42" --snapshot

python3 scripts/log_skill_edit.py <name> --list --since 30d
python3 scripts/diff_skill_versions.py <name> --log

--snapshot 会在 <skill>/.skill_snapshots/SKILL.<sha8>.md 下保存副本，以便差异辅助工具显示实际内容，而不只是哈希值。

受保护的慢速更新区域

经过迭代优化的技能应包含一个用标记围栏括起的区域，用于提供长期指导：

scripts/review_skill.py 会标记不匹配或嵌套的标记。scripts/optimize_skill.py 会拒绝应用针对该区域内内容的步骤级编辑。

触发与迁移测试
# Auto-generate candidate trigger cases from the skill's description
python3 scripts/trigger_test.py <name> --generate > cases.yaml
# Curate, then run
python3 scripts/trigger_test.py <name> --cases cases.yaml --threshold 0.8

# Verify skill lands and parses in other agents
python3 scripts/transfer_test.py <name> --all --scope global
丰富的评分：断言验证器

传入 --verifier assertions，根据 tasks.jsonl 中声明式的 assertions[] 对每次运行进行评分。评分器会返回每条断言的通过/失败结果及证据、提取的主张，还会对断言本身进行评析（eval_feedback）——这一元层会标记薄弱或无法区分的检查项。optimization_report.md 会将这些内容汇总到“断言评析”部分。

// tasks.jsonl entry for --verifier assertions
{"id":"t1","prompt":"...","assertions":["The output is a valid JSON array","Each item has a name field"]}
方差：每个任务运行多次

传入 --runs-per-task 3，即可让每个任务运行 N 次。rollouts.jsonl 会记录 score_mean 和 score_stddev；验证门槛使用平均分。如果验证器结果不稳定，或 Agent 的行为具有非确定性，可使用此选项。

盲测 A/B 对比

独立判断 best_skill.md 是否确实优于 initial_skill.md——这一点很重要，因为 SkillOpt 门槛使用的是提出编辑建议时所用的同一验证器，可能导致自我确认。

python3 scripts/blind_comparator.py \
    --skill-a runs/r1/initial_skill.md \
    --skill-b runs/r1/best_skill.md \
    --tasks tasks.jsonl \
    --output-dir cmp/r1

针对每个任务：让两种技能使用相同的提示词运行，将输出作为 X/Y 提交给独立评审，并随机分配标签。结果汇总至 comparison_report.{json,md}。

运行结果的 HTML 查看器
python3 scripts/eval_viewer.py runs/r1                    # opens in browser
python3 scripts/eval_viewer.py runs/r1 runs/r2 --compare  # side-by-side

单页静态 HTML：每轮图表、已接受/已拒绝编辑时间线、慢速更新历史记录、按任务划分且带评分的运行结果，以及从初始版本到最佳版本的差异。无 JS / CSS 依赖。

发现和安装技能

通过 Skills CLI（npx skills）在开源 Agent 技能生态中搜索和安装技能。可在 skills.sh 浏览。

查找技能
npx skills find [query]              # Interactive search
npx skills find react performance    # Keyword search
npx skills find pr review            # Search by task
从生态中安装

**强制预检：**确定候选项 frontmatter 中的 name，并在安装前运行重复项审计。如果该名称已存在，请更新/复用规范副本。对于有意创建的跨 Agent 副本，记录其必要性，并且仅在审核后使用 install_skill.py --allow-duplicate-name。

对于本地维护的规范源，优先使用 install_skill.py --link：所有 Agent 都会看到同一个真实目录，后续编辑也不会导致复制安装版本出现偏差。只有在使用方无法跟随符号链接，或确实需要隔离快照时，才使用副本。

npx skills add <owner/repo@skill> -g -y    # Install globally, skip prompts
npx skills add vercel-labs/agent-skills@vercel-react-best-practices -g -y
列出生态中的技能
npx skills list                      # List all installed ecosystem skills
npx skills ls                        # Alias
npx skills list -g                   # Global skills only
npx skills list -a cursor            # Skills for a specific agent
移除生态中的技能

卸载通过 npx skills add 安装的技能。对于本地创建的技能，请改用 python3 scripts/delete_skill.py。

**重要：**移除前务必征得用户确认。

npx skills remove <name> -g -y       # Remove a global skill, skip prompt
npx skills rm <name>                 # Alias, with confirmation prompt
npx skills remove <name> -a cursor   # Remove from specific agent
npx skills remove --all -g -y        # Remove all global ecosystem skills
检查和更新
npx skills check                     # Check for available updates
npx skills update                    # Update all installed skills

请将 npx skills check 视为可能会修改内容的命令：某些 CLI 版本会在 check 期间执行更新，而 check --help 也可能进入同一工作流。除非用户已授权更新，否则不要运行该命令进行只读检查。只读检查新鲜度时，优先使用仓库 HEAD、管理器锁定元数据和已安装哈希。任何托管更新完成后，都要重新运行重复项审计，因为过时的锁定条目可能会重新创建已移除的副本。

何时搜索

在以下情况下，使用 npx skills find：

  • 用户询问“如何完成 X”，且 X 是常见任务
  • 用户说“找一个用于 X 的技能”或“有没有用于 X 的技能”
  • 用户需要专业能力（设计、测试、部署等）
常见搜索类别
类别示例查询
Web 开发react, nextjs, typescript, tailwind
测试testing, jest, playwright, e2e
DevOpsdeploy, docker, kubernetes, ci-cd
文档docs, readme, changelog, api-docs
质量review, lint, refactor, best-practices
设计ui, ux, design-system, accessibility
效率workflow, automation, git
审查和比较结果

搜索后始终建议审查找到的技能。 展示搜索结果后，询问用户是否希望你在安装前审查并比较最匹配的候选项。

当结果不少于 2 个时，主动提出获取并评估最匹配的候选项。这由 Agent 驱动——对 https://skills.sh/<owner>/<repo>/<skill> 页面使用 WebFetch，并作出判断。

以下情况始终提供审查：

  • 任何搜索返回结果时（询问：“要我在安装前审查这些技能吗？”）
  • 返回结果不少于 3 个时——审查尤其有价值
  • 多个结果名称相似或描述重叠时
  • 用户要求比较、审查、评估或选出最佳项时
  • 某个结果的指标可疑时（小众主题却有很高的安装量）

流程：

  1. 先概述搜索结果
  2. 询问用户是否希望你审查／比较最匹配的候选项
  3. 如果愿意：获取排名靠前的 3-6 个候选项的 skills.sh 页面
  4. 评估质量信号：安装量、Agent 分布、创建时间、描述、相关性、与已安装技能的重叠情况
  5. 给出结论：推荐／可考虑／跳过
  6. 按排名概述评估结果，并为每项提供 1-2 句评价

完整的评估框架（包括风险信号和评分指标）请参阅 references/remote-skill-assessment.md。

没有结果时

如果未找到技能：提出可以直接提供帮助，然后建议使用 npx skills init <name> 创建自定义技能。

多 Agent 操作

管理 40 种受支持的 AI 编码 Agent 的技能。完整注册表请访问 skills.sh。

受支持的 Agent

受支持 Agent 及发现路径的权威注册表位于 scripts/agents.py。使用 detect_agents.py --all 打印该注册表，而不是将表格复制到说明中，以免路径过时。

检测已安装的 Agent
python3 scripts/detect_agents.py              # List detected agents
python3 scripts/detect_agents.py --all        # Show all supported agents
python3 scripts/detect_agents.py -f json      # JSON output
列出任意 Agent 的技能
python3 scripts/list_agent_skills.py --agent cursor           # Single agent
python3 scripts/list_agent_skills.py --agent goose -s global  # Specific scope
python3 scripts/list_agent_skills.py --all                    # All detected agents
python3 scripts/list_agent_skills.py --agent amp -f json      # JSON output
将技能安装到 Agent
python3 scripts/install_skill.py /path/to/skill --agent cursor              # Single agent
python3 scripts/install_skill.py /path/to/skill --agent cursor --agent amp  # Multiple agents
python3 scripts/install_skill.py /path/to/skill --all                       # All detected
python3 scripts/install_skill.py /path/to/skill --agent goose -s global     # Global scope
python3 scripts/install_skill.py /path/to/skill --agent cursor --force      # Overwrite
python3 scripts/install_skill.py /path/to/skill --agent cursor --link --allow-duplicate-name  # Canonical alias
在 Agent 之间复制技能
python3 scripts/copy_skill.py my-skill --from claude-code --to cursor
python3 scripts/copy_skill.py my-skill --from claude-code --to cursor --to-scope global
python3 scripts/copy_skill.py my-skill --from claude-code --from-scope project --to amp
python3 scripts/copy_skill.py my-skill --from claude-code --to cursor --force
在 Agent 之间移动技能
python3 scripts/move_skill_agent.py my-skill --from claude-code --to cursor
python3 scripts/move_skill_agent.py my-skill --from claude-code --to goose --force

重要说明

  • 新增顶层目录需要重启：如果创建的顶层 skills/ 目录在会话开始时尚不存在，则需要重启 Claude Code 才能监视该目录
  • 实时变更检测（Claude Code，2026）：在 ~/.claude/skills/、项目的 .claude/skills/ 或 --add-dir 目录中的 .claude/skills/ 下添加、编辑或移除技能，会在当前 Claude Code 会话中生效——无需重启
  • 编辑立即生效：修改现有技能内容无需重启
  • Agent 检测：通过配置目录是否存在来检测已安装的 Agent
  • 每种发现拓扑只安装一次：优先使用一个共享的规范根目录或符号链接。仅当使用者无法读取该根目录时，才创建特定于 Agent 的副本，并在复制后进行审核。
  • 自定义命令已并入技能（Claude Code，2026）：.claude/commands/deploy.md 中的文件和 .claude/skills/deploy/SKILL.md 中的技能都会创建 /deploy。现有 .claude/commands/ 文件仍可使用；技能还提供了用于支持文件、frontmatter 和自动调用的目录。
  • 插件技能使用命名空间，格式为 plugin-name:skill-name，且不会与用户／项目技能冲突

OpenCode 专属说明

OpenCode（anomalyco/opencode v1.14.x）除了原生路径外，还会从多个兼容位置读取技能：

  • 项目：.opencode/skills/、.claude/skills/、.agents/skills/ — 全部都会加载
  • 全局：~/.config/opencode/skills/、~/.claude/skills/、~/.agents/skills/ — 全部都会加载
  • 从 CWD 向上遍历至 git worktree 根目录，并沿途收集技能

这意味着，同一个 Anthropic 格式的 SKILL.md 技能可在 Claude Code、Codex 和 OpenCode 中直接通用，无需修改。OpenCode 用户还可以选择进行以下优化：

  • 在 frontmatter 中添加 compatibility: opencode,claude-code,codex
  • 如果技能正文会调用工具，请使用小写工具名称（bash、edit、read，而非 Bash/Edit/Read）

可通过 opencode.json 中的 permission.skill 区块，按名称控制技能的访问权限：

{ "permission": { "skill": { "*": "allow", "internal-*": "deny" } } }

完整的 OpenCode 技能参考请参阅 references/opencode-skills.md。

参考资料 — Claude 技能构建完整指南

审核技能或提供有关技能结构和最佳实践的建议时，请参考以下资料。

文件描述
references/01-introduction.md技能是什么、本指南面向哪些读者、两种学习路径
references/02-fundamentals.md技能结构、渐进式披露、可组合性、MCP 集成
references/03-planning-and-design.md使用场景、类别、成功标准、YAML frontmatter、编写说明
references/04-testing-and-iteration.md触发测试、功能测试、性能对比、skill-creator 的使用
references/05-distribution-and-sharing.md分发模式、API 使用、GitHub 托管、定位
references/06-patterns-and-troubleshooting.md7 种工作流模式（包括 SkillOpt 风格的验证式迭代优化）、常见错误及修复方法
references/07-resources-and-references.md官方文档、示例技能、工具、支持渠道
references/ref-a-quick-checklist.md构建前、开发、上传和上传后检查清单
references/ref-b-yaml-frontmatter.md必需/可选字段、安全限制
references/ref-c-complete-skill-examples.md可用于生产环境的技能示例链接
references/remote-skill-assessment.md安装前评估生态系统技能的框架
references/skill-deduplication.md规范来源选择、重复项分类、插件处理、安装前检查和验证
references/skill-optimization.mdSkillOpt 风格的训练循环：有界编辑、验证关卡、拒绝缓冲区、慢速/meta 更新（Microsoft，arXiv 2605.23904）
references/optimization-artifacts-schemas.mdoptimize_skill.py 和 log_skill_edit.py 写入的所有工件的 JSON 架构（拆分、状态、rollout、提案、决策、edit_apply_report、rejected_buffer、meta_skill 等）
references/optimization-grading-checklist.md优化运行完成后的审计检查清单 — 发布前应检查 best_skill.md、edit_apply_report.json、rejected_buffer.json 中的哪些内容
prompts/analyst_error.md、analyst_success.md优化器的失败/成功分析提示词规范
prompts/merge_failure.md、merge_success.md、merge_final.md分层编辑合并规范
prompts/ranking.md编辑排序与选择规范
prompts/slow_update.md、meta_skill.md周期边界慢速更新与优化器侧元技能规范
prompts/grader.md面向 --verifier assertions 的详细评分规范（逐项断言通过/失败 + 声明 + eval_feedback 评述）
prompts/blind_comparator.md面向 blind_comparator.py 的独立 A/B 评审规范

致谢

多 Agent 支持基于 Vercel Labs 的 Skills CLI（npx skills）。欢迎在 skills.sh 浏览开源 Agent 技能生态。

评论

支持 Markdown