modular-skills

不适用的情况

• 单文件技能已在其令牌预算范围内（使用 abstract:skill-authoring）
• 惰性加载约定本身（使用 leyline:progressive-loading）

模块化技能设计

概述

此框架将复杂技能拆分为专注的模块，使令牌用量可预测，并避免文件过于庞大。我们采用渐进式披露：先提供基础内容，仅在需要时通过 @include 或 Load: 语句加载更深入的技术细节。这种方法可以避免长时间运行的任务触及上下文限制。

模块化设计可将文件大小控制在建议范围内，通常少于 150 行。依赖关系简单、边界清晰，能简化测试和维护。中心辐射式模型让项目得以扩展，而不会让主要技能文件变得臃肿，从而使专注的模块更易于独立验证，也能更快解析。

核心组件

有三种工具支持模块化技能开发：

• skill-analyzer：检查复杂度，并建议代码拆分位置。
• token-estimator：预测用量，并提出优化建议。
• module_validator：验证结构是否符合项目标准。

设计原则

我们围绕单一职责和松散耦合来设计技能。每个模块专注于一项任务，尽量减少依赖，以保持架构内聚。清晰的边界和定义明确的接口可以防止一个模块的更改破坏其他模块。这遵循 Anthropic 的 Agent Skills 最佳实践：先提供高层概述，再按需呈现细节，以保持上下文效率。

模块归属（重要）

已弃用：skills/shared/modules/ 目录。共享模块更新或移除时，这种模式会导致引用失效。

当前模式：每项技能将自己的模块存放在 skills/<skill-name>/modules/。当多项技能需要相同内容时，由主要归属技能持有该模块，其他技能通过相对路径引用（例如 ../skill-authoring/modules/description-writing.md）。验证器会标记所有剩余的 skills/shared/ 目录。

快速入门

技能分析

使用 scripts/skill_analyzer.py 分析模块化情况。可以设置自定义行数阈值，以识别需要拆分的文件。

python scripts/skill_analyzer.py --file path/to/SKILL.md --threshold 100

在 Python 中，使用 abstract.skill_tools 中的 analyze_skill。

令牌用量规划

估算令牌消耗，确认技能未超出预算。在技能目录中运行：

python scripts/tokens.py

模块验证

部署前，检查结构和模式是否符合要求。

python scripts/abstract_validator.py --scan

工作流与任务

首先使用 skill_analyzer.py 评估复杂度。如果技能超过 150 行，则按照 modules/implementation-patterns.md 中的模式将其拆分为专注的模块。使用 token_estimator.py 检查效率，并使用 abstract_validator.py 验证最终结构。这个迭代过程可以保持模块的可维护性和令牌效率。

质量检查

检查行数，找出需要关注的模块。超过 100 行的模块可以考虑拆分。不要添加目录：锚点列表会重复其下方的标题，并在每次加载时消耗令牌，而且 grep 可以直接找到这些标题。

# Find modules exceeding 100 lines
find modules -name "*.md" -exec wc -l {} + | awk '$1 > 100'

标准合规性

我们的标准优先考虑具体示例和一致的语气。快速入门部分始终应提供实际命令，而非抽象描述。使用第三人称视角（例如“项目”“开发者”），而不是“你”或“你的”。每个代码示例后都应附上验证命令。为便于发现，描述必须包含至少五个具体的触发短语。

资源

共享模块：跨技能模式

用于触发以及判断某项技能是否适用的标准模式：

• 触发模式：参见 enforcement-patterns.md
• 技能选择：参见 skill-selection-judgment.md

特定技能模块

有关实现和维护的详细指南：

• 执行模式：参见 modules/enforcement-patterns.md
• 核心工作流：参见 modules/core-workflow.md
• 实现模式：参见 modules/implementation-patterns.md
• 迁移指南：参见 modules/antipatterns-and-migration.md
• 设计理念：参见 modules/design-philosophy.md
• 故障排除：参见 modules/troubleshooting.md
• 优化技巧：参见 modules/optimization-techniques.md - 通过外置、整合和渐进式加载来缩减大型技能文件

工具

• 工具：../../scripts/ 中的 skill_analyzer.py、token_estimator.py 和 abstract_validator.py

退出标准

• 生成的每个模块文件均不超过 150 行，且 SKILL.md 和模块中均不包含目录。
• 不存在 skills/shared/modules/ 目录；所有模块均位于 skills/<skill-name>/modules/ 下。
• python scripts/abstract_validator.py --scan 在受影响的技能目录中退出代码为 0，且没有结构警告。
• python scripts/tokens.py 报告的估算令牌总数在中心 SKILL.md 声明的 estimated_tokens 预算范围内。