skills-manager

用途

Skills Manager（智能路由器）是 anyproto/anytype-swift 项目中的一个元技能，用于对技能（skills）与钩子（hooks）进行上下文感知的路由与管理。它帮助排查技能激活问题、微调关键词，并管理自动化文档系统。

自动激活时机

讨论技能激活或钩子时
创建新技能时
调试技能为何未激活或激活错误时

关键词包括：skill activation、hook、troubleshoot、fine-tune、keyword、skill-rules.json、create skill、new skill、agentskills。

关键规则

日志是首要排查依据：始终先检查 .claude/logs/skill-activations.log
修改后必须测试：对 skill-rules.json 的任何修改都要验证是否生效
校验 JSON：提交前用 jq 校验 skill-rules.json
关键词应具体：过于宽泛的关键词会导致误报

快速诊断流程

问题：技能未激活

检查日志：tail -20 .claude/logs/skill-activations.log
查看当前关键词：cat .claude/hooks/skill-rules.json | jq '.skills."SKILL-NAME".promptTriggers.keywords'
添加缺失关键词：可让 Claude 执行“Add 'KEYWORD' to SKILL-NAME”，或直接编辑 .claude/hooks/skill-rules.json
测试：echo '{"prompt":"test prompt"}' | .claude/hooks/skill-activation-prompt.sh

问题：技能在不该激活时激活

定位触发源：查看日志确认匹配了哪个关键词
删除或使其更具体：如“Remove 'text' from localization-developer”，或将“text”替换为“localized text”
验证：tail .claude/logs/skill-activations.log

常见任务

添加关键词：可让 Claude 执行“Add 'refactoring' to ios-dev-guidelines keywords”，或手动编辑 skill-rules.json 的 keywords 数组
删除关键词：可让 Claude 执行“Remove 'text' from localization-developer, it's too broad”，或手动编辑删除
查看激活情况：tail -20 .claude/logs/skill-activations.log，关注“✓ Matched: skill-name”或“No matches found”
手动测试激活：echo '{"prompt":"add feature flag"}' | .claude/hooks/skill-activation-prompt.sh，若匹配则输出技能建议

自动学习功能

当较长提示（100+ 字符或 3+ 行）未激活任何技能时，系统会提示可用技能，并根据反馈自动更新关键词。流程：提交较长提示 → 无技能激活 → 系统询问“Should any of these skills be activated?” → 用户回复如“Yes, localization-developer should activate” → Claude 从提示中提取关键词 → 执行 .claude/hooks/utils/add-keywords-to-skill.sh localization-developer <keywords> → 更新 skill-rules.json → 未来类似提示自动激活。

手动提取关键词示例：

# 测试关键词提取
echo "Update space settings localization for membership tiers" | .claude/hooks/utils/extract-keywords.sh
# 输出: membership, settings, localization, tiers, update

# 手动添加关键词
.claude/hooks/utils/add-keywords-to-skill.sh localization-developer "membership" "tiers"

相关日志：未激活记录 .claude/logs/skill-activations-missed.log；学习更新 .claude/logs/skill-learning.log。

系统组件

钩子（自动化）

位置：.claude/hooks/

skill-activation-prompt.sh - 根据提示建议技能
post-tool-use-tracker.sh - 跟踪文件编辑
swiftformat-post-edit.sh - 编辑后立即自动格式化 Swift 文件
notification-alert.sh - Claude 需要输入时发送 macOS 通知

技能（路由器）

位置：.claude/skills/*/SKILL.md

共 7 个技能：

ios-dev-guidelines - Swift/iOS 模式
localization-developer - 本地化
code-generation-developer - 功能开关、make generate
design-system-developer - 图标、排版、颜色
skills-manager - 本技能（元技能）
code-review-developer - 代码审查标准
feature-toggle-developer - 功能开关移除、清理检测

配置

位置：.claude/hooks/skill-rules.json

包含：每个技能的关键词、意图模式（正则）、文件路径模式、优先级设置。

配置结构示例：

{
  "skills": {
    "skill-name": {
      "type": "domain",
      "priority": "high",
      "description": "Smart router to...",
      "promptTriggers": {
        "keywords": ["keyword1", "keyword2"],
        "intentPatterns": ["(create|add).*?something"]
      },
      "fileTriggers": {
        "pathPatterns": ["**/*.swift"],
        "contentPatterns": ["SomePattern"]
      }
    }
  },
  "config": {
    "maxSkillsPerPrompt": 2,
    "logActivations": true
  }
}

创建新技能（agentskills.io 规范）

技能必须遵循 agentskills.io 规范。每个 SKILL.md 必须以 YAML frontmatter 开头：

---
name: skill-name
description: What this skill does and when to use it (max 1024 chars).
---

# Skill Title

## Purpose
...

名称字段规则：1-64 字符；仅小写 a-z、0-9、-；首尾不能有连字符；不能有连续连字符；必须与目录名一致。

描述字段：1-1024 字符；必须说明做什么以及何时使用；包含有助于代理识别相关任务的关键词。

可选 frontmatter 字段：license、compatibility、metadata（如 author、version）。

目录结构：

skill-name/
├── SKILL.md          # 必需 - 主技能文件
├── scripts/          # 可选 - 可执行脚本
├── references/       # 可选 - 附加文档
└── assets/           # 可选 - 模板、图片

新技能快速检查清单：目录名与 name 字段一致；YAML frontmatter 含 name 和 description；名称小写且仅含连字符；描述说明做什么和何时用；SKILL.md 少于 500 行（细节放 references/）；已加入 skill-rules.json 并配置关键词；用示例提示测试激活。

常见问题

钩子未执行：症状为无激活消息、日志为空。修复：chmod +x .claude/hooks/*.sh，并用 ls -l .claude/hooks/*.sh 验证权限。
JSON 无效：症状为钩子静默失败。修复：jq . .claude/hooks/skill-rules.json 校验，若有错误可让 Claude 修复。
误报过多：症状为技能激活过于频繁。修复：使关键词更具体，如“text”改为“localized text”。

健康检查命令

# 检查钩子权限
ls -l .claude/hooks/*.sh

# 校验配置
jq . .claude/hooks/skill-rules.json

# 查看最近激活
tail -20 .claude/logs/skill-activations.log

# 按技能统计激活次数
grep "Matched:" .claude/logs/skill-activations.log | sort | uniq -c

# 测试特定提示
echo '{"prompt":"your test"}' | .claude/hooks/skill-activation-prompt.sh

实用提示

让 Claude 检查日志：“Check the logs for my last prompt”
用日志进行调优：定期查看以发现模式
从宽泛开始：先加宽泛关键词，误报过多再收窄
一切都要测试：修改 skill-rules.json 后务必测试
记录变更：在 skill-rules.json 中添加注释

技能介绍

用途