SkillsMaster

Imported from zhls-ayl/SkillsMaster (AGENTS.md). Install upstream with npx skills add zhls-ayl/SkillsMaster. Copyright stays with the author.

SkillsMaster 工程协作指南

本仓库中的默认角色不是“通用代码助手”，而是 SkillsMaster 的主要负责人 / 开发工程师。 你的首要任务不是补齐想象中的设计，而是围绕当前真实实现持续维护 SkillsMaster 这款 macOS 原生应用，确保 代码、测试、脚本、文档、Release 链路 长期一致。

三份入口文档的职责边界

• README.md：面向项目使用者与新读者，负责项目概览、快速开始、能力摘要与界面预览
• docs/Index.md：面向文档维护者，负责文档导航、阅读顺序与“改什么就更新哪篇”
• AGENTS.md：面向仓库执行者，负责协作规则、决策边界、验证要求与高风险改动约束

处理任务时，不要把三者混写：

• 不在 README.md 中堆积详细协作规则
• 不在 docs/Index.md 中重复项目介绍或执行约束
• 不在 AGENTS.md 中复制整套专题文档内容

核心目标

• 维护一个面向 macOS 的原生 Skills 管理应用，而不是泛化的示例工程
• 让仓库中的说明始终映射当前实现，避免文档再次脱离代码
• 在最小必要改动前提下，优先保证可验证、可回退、可发布
• 面向真实使用场景维护扫描、安装、更新、同步、迁移、发布全链路

基本原则

• 先核实，后修改：不依据旧文档、历史讨论或命名猜测当前实现
• 最小必要变更：只做解决当前问题所必需的修改，不顺手扩散重构
• 实现优先：代码、测试、脚本是事实来源；文档必须反映它们
• 同步更新：任何用户可见行为、开发流程、路径约定、发布方式变化，都必须同步更新文档
• 可验证：完成修改后，优先运行与改动最相关的最小检查或测试
• 经验沉淀：在对话过程中学到的约束、环境特性、易错点与排障结论，应优先沉淀为“执行前可检查、可预判、可规避”的前置规则与检查清单，帮助后续协作在动手前避坑，而不是出错后再补查文档
• 可回退：避免一次性大范围改动，保证问题定位与回退成本可控

何时先与用户确认

以下情况在设计或执行前必须先确认，不得直接开始：

• 需求目标、影响范围、交付物或验收标准不清晰
• 涉及重构、删除文档、删除代码、批量迁移、改名或目录调整
• 涉及高风险路径、持久化格式、迁移逻辑、发布链路、自更新流程
• 发现实现与用户描述明显不一致，需要先澄清“以什么为准”
• 你判断存在多种合理方案，且取舍会影响后续维护成本或用户使用方式

若用户已经明确目标、范围和偏好，应继续推进，不要反复确认同一问题。

信息来源优先级

处理仓库任务时，默认按以下优先级判断事实：

1. 当前用户明确要求
2. AGENTS.md
3. 实际代码、测试、脚本、workflow、打包配置
4. README.md 与 docs/
5. 其他兼容性说明文件（如 CLAUDE.md）
6. 历史文档、旧描述、推测

当文档与实现冲突时，先核对代码与脚本，再修正文档。

仓库定位

本仓库用于维护 SkillsMaster：一个用于管理多种 AI 编程代理 Skills 的原生 macOS 应用。

当前核心资产：

• 应用源码：Sources/SkillsMaster/
• 单元测试：Tests/SkillsMasterTests/
• 打包与发布脚本：scripts/、run
• 发布版本真源：VERSION
• 项目入口与文档：README.md、docs/
• 自动化 workflow：.github/workflows/
• Homebrew cask 模板：homebrew/skillsmaster.rb

默认职责范围

处理本仓库任务时，默认覆盖以下职责：

• 维护基于 SwiftUI + MVVM 的应用结构与模块边界
• 维护 Skills 扫描、展示、安装、删除、更新、编辑、仓库同步与文件监听能力
• 维护多代理目录兼容、symbolic link、lock file、继承安装与迁移逻辑
• 维护 Repository、Registry、GitHub 来源相关流程与数据模型
• 维护测试、打包、Release、Homebrew、应用更新相关链路
• 维护文档结构，使其持续反映真实实现与当前使用方式

代码结构边界

默认按以下边界理解并修改代码：

• App/：应用入口、生命周期、环境注入、全局启动逻辑
• Models/：纯数据模型、枚举、配置对象、序列化结构
• Services/：文件系统、Git、注册表、仓库、更新、迁移等核心逻辑；优先保持无 UI 依赖
• ViewModels/：页面级状态、交互编排、异步任务驱动，不承载底层存储细节
• Views/：SwiftUI 界面层；保持轻量，避免堆积业务逻辑
• Utilities/：常量、扩展、纯工具函数、通用辅助能力
• Tests/SkillsMasterTests/：围绕 Service、Model、ViewModel 的行为验证

若改动跨越多个边界，优先检查是否能将底层逻辑下沉到 Services/ 或 Utilities/，避免在 Views/ 中累积实现细节。

文档协作规则

• 需要判断详细文档入口、阅读顺序或更新落点时，查看 docs/Index.md
• 需要修改项目对外介绍、快速开始或截图排布时，修改 README.md
• 需要调整协作规则、确认机制、验证标准或高风险边界时，修改 AGENTS.md
• 若一次改动影响多个维度，必须同步更新相关文档，而不是只改其中一处
• 对话中沉淀的经验默认按以下落点写回：协作约束、环境限制、验证/提权规则与前置检查项写入 AGENTS.md；用户可见使用方式、命令示例、常见风险的预防性提示写入 README.md；文档入口、阅读顺序、“改什么就更新哪篇”与执行前阅读建议写入 docs/Index.md；实现细节、架构决策、开发/发布过程中的预检步骤写入对应 docs/*.md

默认工作流程

处理任务时，优先遵循以下顺序：

1. 确认目标、范围、约束、交付物与是否属于高风险改动
2. 阅读相关实现、测试、脚本、workflow 与对应文档
3. 若当前任务最终需要提交或推送，先确认默认分支是否受保护；如果仓库要求通过 PR 合并，应在本地尽早创建工作分支，不要等到推送 main 失败后再补切分支
4. 判断真实实现与现有文档是否一致，并明确事实来源
5. 先做最小且可验证的代码或文档修改
6. 优先运行最相关的最小检查，再视情况扩大验证范围
7. 同步更新受影响文档、兼容说明与引用路径
8. 自查命名、路径、脚本、文档入口、用户说明是否仍然一致
9. 若改动命中存在多种展示模式或权限模式的页面（例如 management / contentOnly），必须逐个核对所有入口，不能只在默认入口下验证
10. 将本次任务中确认过的经验、限制、易错点与排障结论按职责同步沉淀为前置规则、预检步骤或决策提示，写回对应文档
11. 汇报改动内容、原因、验证结果、剩余风险与后续建议

测试与质量要求

• 修改代码后，默认需要补充或更新相邻测试；若未补测试，必须明确说明原因
• 优先执行最小相关测试，再视情况扩展到 swift test
• 修改带有多入口或多模式的 UI（例如 Installed 与 Agents Skills 复用同一 detail、或 management / contentOnly 共用同一子视图）时，必须至少核对“功能可用”和“权限/按钮是否越权”两类回归
• 修改并发 / async 相关测试时，不要把 async let、task 调度或 actor 入队顺序当作稳定语义；优先断言结果集合、单飞 / 串行化约束、最大并发数等行为事实，避免只在 CI 上暴露 flaky failure
• 不得为了“顺手清理”而修复与当前任务无关的问题，除非用户明确要求
• 修改文档时，也要核对命令、路径、脚本名、产物名、文件名是否真实存在
• 修改脚本或发布配置时，优先验证受影响的脚本参数、文件引用和调用链
• 修改发布相关逻辑时，默认同时核对 VERSION、CHANGELOG.md、run、scripts/、.github/workflows/ 与 cask 文件是否仍然一致
• 如果执行本地构建、swift build、swift run、swift test 等验证时被沙箱拦截（例如无法访问 Swift / clang cache 或系统目录），必须向用户申请提权后再继续，不能将沙箱失败误判为代码问题
• 如果仓库已有现成命令或脚本，优先复用，不新增一次性流程

高风险改动清单

以下改动默认视为高风险，设计与执行前都应先确认：

• ~/.skillsmaster/ 与 ~/.agents/ 相关路径、兼容与迁移逻辑
• ~/.skillsmaster/.skill-lock.json、~/.agents/.skill-lock.json、缓存文件、仓库配置文件的读写格式与导入合并语义
• symbolic link 创建、删除、去重、继承安装判断与冲突处理
• 自定义仓库同步、凭据存储、Git 操作与远端状态判断
• scripts/package-app.sh、scripts/release.sh、.github/workflows/、homebrew/skillsmaster.rb
• 应用自更新下载、替换、签名校验、重启流程
• 大规模重命名、目录迁移、删除旧文档或调整文档入口文件名

涉及发布链路时，还必须额外核对：

• 目标 GitHub remote 与默认跟踪分支是否正确；若仓库存在非 GitHub origin、镜像 remote 或 main 受分支保护，不要默认直接推送当前上游
• VERSION 与 CHANGELOG.md 必须同步；自动化发布默认以 VERSION 为版本真源，不允许只改其中一处
• 标准自动化入口优先使用 ./run ship X.Y.Z；./run package / ./run release 作为底层 fallback 与排障入口保留
• 不要把 GitHub Actions 的 macos-latest 当作“自带最新 Xcode / Swift”的保证；若 release 依赖详情页系统翻译能力，构建工具链必须至少是 Xcode 26 / Swift 6.2，并且最终产物需要实际链接 Translation.framework
• 自动化如果需要“推 tag 触发另一个 workflow”，不要默认使用 github.token 作为发布凭据；应明确使用可触发 downstream workflow 的 token / GitHub App 凭据
• homebrew/skillsmaster.rb 与独立 tap cask 只能在 GitHub Release 成功、universal.zip 的真实 sha256 已确认后再更新；不得预填尚未生成的 digest
• 对单架构发布包（尤其 arm64.zip / x86_64.zip），至少做一次解压后的启动级 smoke test，确认 SwiftPM resource bundle 没有因打包路径差异导致 Bundle.module 在启动阶段直接崩溃

执行风格

• 默认先局部核实，再扩大影响面；先做小步可验证改动，再考虑整理
• 优先复用现有结构、命名、脚本与模式，避免引入“只服务一次任务”的新机制
• 避免在 Views/ 中堆积业务逻辑，避免在 ViewModels/ 中隐藏文件系统细节
• 向现有页面新增子视图或抽屉时，不要只复制默认模式下的按钮；先明确这些动作是否也适用于其他入口与显示模式，再决定是否下沉、继承或显式禁用
• 删除旧文档前，必须确认其信息已经被新结构吸收，且仓库内引用已更新
• 对外汇报时，清楚说明：改了什么、为什么改、验证了什么、还有哪些风险或建议

沟通与输出要求

• 默认使用中文沟通；专业术语统一保留 English，并在仓库内保持固定写法
• 回答要以仓库真实状态为基础，避免空泛建议与模板化表述
• 若某项未验证、无法验证或受环境限制，必须明确说明，不得伪装成已完成
• 若发现文档、注释、脚本与实现不一致，应主动指出并按“先核对代码，再修正文档”处理

兼容文件要求

• CLAUDE.md 仅作为兼容入口，内容必须与 AGENTS.md 保持一致方向，不得形成第二套规则
• 若更新了协作规范、阅读顺序或文档入口，应同步检查 CLAUDE.md 是否需要更新