singularity-forge/docs/zh-CN/user-docs/skills.md

技能

技能（Skills）是当当前 task 匹配时由 SF 加载的专用指令集。它们为 LLM 提供领域化指导，例如编码模式、框架惯用法、测试策略和工具使用方式。

Skills 遵循开放的 Agent Skills 标准，并且不是 SF 专属格式。它们同样适用于 Claude Code、OpenAI Codex、Cursor、GitHub Copilot、Windsurf 以及其他 40+ agent。

技能目录

SF 会按优先级顺序从两个位置读取技能：

位置	范围	说明
~/.agents/skills/	全局	对所有项目和所有兼容 agent 共享
.agents/skills/（项目根目录）	项目级	项目专用技能，可提交到版本控制

如果出现同名技能，全局技能优先于项目技能。

从 ~/.sf/agent/skills/ 迁移： 升级后首次启动时，SF 会自动把旧版 ~/.sf/agent/skills/ 中的技能复制到 ~/.agents/skills/。旧目录会保留，以兼容旧流程。

安装技能

技能通过 skills.sh CLI 安装：

# 交互式：选择要安装的技能以及目标 agent
npx skills add dpearson2699/swift-ios-skills

# 非交互方式安装指定技能
npx skills add dpearson2699/swift-ios-skills --skill swift-concurrency --skill swiftui-patterns -y

# 安装仓库中的全部技能
npx skills add dpearson2699/swift-ios-skills --all

# 检查更新
npx skills check

# 更新已安装技能
npx skills update

入门技能目录

在执行 sf init 时，SF 会检测项目技术栈并推荐合适的技能包。对于 brownfield 项目，检测是自动的；对于 greenfield 项目，则由用户选择技术栈。

这个精选目录维护在 src/resources/extensions/sf/skill-catalog.ts。每一条目都会把一个技术栈映射到一个 skills.sh 仓库，以及其中的具体技能名称。

可用技能包

Swift（检测到任意 Swift 项目，例如 Package.swift 或 .xcodeproj）：

• SwiftUI：布局、导航、动画、手势、Liquid Glass
• Swift Core：Swift 语言、并发、Codable、Charts、Testing、SwiftData

iOS（仅当 .xcodeproj 目标通过 SDKROOT 指向 iphoneos 时）：

• iOS App Frameworks：App Intents、Widgets、StoreKit、MapKit、Live Activities
• iOS Data Frameworks：CloudKit、HealthKit、MusicKit、WeatherKit、Contacts
• iOS AI & ML：Core ML、Vision、端侧 AI、语音识别
• iOS Engineering：网络、安全、可访问性、本地化、Instruments
• iOS Hardware：Bluetooth、CoreMotion、NFC、PencilKit、RealityKit
• iOS Platform：CallKit、EnergyKit、HomeKit、SharePlay、PermissionKit

Web：

• React & Web Frontend：React 最佳实践、Web 设计、组合模式
• React Native：跨平台移动开发模式
• Frontend Design & UX：前端设计与可访问性

语言：

• Rust：Rust 模式与最佳实践
• Python：Python 模式与最佳实践
• Go：Go 模式与最佳实践

通用：

• Document Handling：PDF、DOCX、XLSX、PPTX 的创建和处理

维护目录

技能目录定义位于 src/resources/extensions/sf/skill-catalog.ts。新增或更新一个技能包时：

1. 在 SKILL_CATALOG 数组中新增一个 SkillPack 条目，包含 repo、skills 和匹配条件
2. 基于语言检测做匹配时，使用 matchLanguages（取值来自 detection.ts 中的 LANGUAGE_MAP）
3. 基于 Xcode 平台做匹配时，使用 matchXcodePlatforms（例如 ["iphoneos"]，取自 project.pbxproj 中的 SDKROOT）
4. 基于文件存在与否做匹配时，使用 matchFiles（对照 detection.ts 中的 PROJECT_FILES）
5. 如果这个技能包需要在 greenfield 选项中出现，把它加入 GREENFIELD_STACKS
6. 如果多个技能包共享同一个 repo，它们会被合并为一次 npx skills add 调用

技能发现

skill_discovery 偏好控制 SF 在自动模式中如何发现技能：

模式	行为
auto	自动查找并应用技能
suggest	识别技能，但需要确认（默认）
off	关闭技能发现

技能偏好

你可以通过偏好设置控制使用哪些技能：

---
version: 1
always_use_skills:
  - debug-like-expert
prefer_skills:
  - frontend-design
avoid_skills:
  - security-docker
skill_rules:
  - when: task involves Clerk authentication
    use: [clerk]
  - when: frontend styling work
    prefer: [frontend-design]
---

解析顺序

技能可以通过以下几种方式引用：

1. 裸名称：例如 frontend-design，会扫描 ~/.agents/skills/ 和项目内的 .agents/skills/
2. 绝对路径：例如 /Users/you/.agents/skills/my-skill/SKILL.md
3. 目录路径：例如 ~/custom-skills/my-skill，会在其中查找 SKILL.md

全局技能（~/.agents/skills/）优先于项目技能（.agents/skills/）。

自定义技能

你可以通过新增一个包含 SKILL.md 的目录来创建自己的技能：

~/.agents/skills/my-skill/
  SKILL.md           — 给 LLM 的指令
  references/        — 可选参考文件

SKILL.md 中写的是当技能启用时，LLM 应遵循的指令。参考文件可由技能按需加载。

项目本地技能

如果想为某个项目提供专用指导，可以把技能放在项目里：

.agents/skills/my-project-skill/
  SKILL.md

项目本地技能可以提交到版本控制中，让团队成员共享同一套技能。

技能生命周期管理

SF 会跨自动模式会话跟踪技能表现，并提供健康度数据，帮助你持续维护技能质量。

技能遥测

每个自动模式工作单元都会记录哪些技能可用、哪些技能实际加载。这些数据和现有的 token / 成本数据一起存入 metrics.json。

技能健康度面板

通过 /sf skill-health 查看技能表现：

/sf skill-health              # 总览表：名称、使用次数、成功率、token、趋势、最近使用时间
/sf skill-health rust-core    # 查看单个技能的详细信息
/sf skill-health --stale 30   # 查看 30+ 天未使用的技能
/sf skill-health --declining  # 查看成功率在下降的技能

该面板会标出可能需要关注的技能：

• 最近 10 次使用的成功率低于 70%
• Token 使用量比上一个窗口上升 20% 以上
• 过期技能：超过设定阈值未使用

过期检测

长时间未使用的技能会被标记为 stale，并可自动降低优先级：

---
skill_staleness_days: 60   # 默认 60；设为 0 表示关闭
---

过期技能会被排除在自动匹配之外，但仍然可以通过 read 显式调用。

Heal-Skill（单元后分析）

如果把它配置为 post-unit hook，SF 可以分析 agent 在执行中是否偏离了某个技能的指令。如果检测到明显漂移（例如 API 模式过时、指导错误），它会把建议修复写到 .sf/skill-review-queue.md，供人工审核。

一个关键设计原则是：技能永远不会被自动修改。研究表明，人工策展的技能明显优于自动生成技能，因此保留人工审核是必要的。