Skill Authoring 用于指导 Skill System Foundry 生态内技能（skill）的创建、演进与校验。系统采用两层架构：技能负责可跨 AI 复用的知识与逻辑，可独立处理任务，也可路由到能力（capabilities）；角色定义责任、权限、约束与交接规则，并组合多个技能或能力。依赖方向严格向下：角色→技能→能力，能力不得感知被编排，角色不得引用其他角色。
创建步骤：先用 standalone 技能，确有需要再演进为 router + capabilities。判断依据是存在 3 个以上触发上下文互斥的操作、需要不同工具权限，或单文件超过 500 行。脚手架命令为 python scripts/scaffold.py skill <skill-name> --root /path/to/project/.agents，可选 --with-references、--with-scripts、--with-assets 创建附加目录；角色用 python scripts/scaffold.py role <role-name> --root /path/to/project/.agents。
每个技能目录含带 YAML frontmatter 的 SKILL.md。必填 name（小写加连字符，最多 64 字符，须与目录名一致）与 description（最多 1024 字符，第三人称，说明做什么与何时触发）；可选 allowed-tools、compatibility（最多 500 字符）、license、metadata。多行描述建议用折叠块标量。正文为 Level 2 内容，需在 500 行以内。description 是主要触发机制，应包含具体动词名词、用户意图短语与区分特征。
能力是可选的子技能，入口为 capability.md，放在 <skill>/capabilities/<capability-name>/capability.md。能力须自足，直接内联工作流，用相对路径引用共享资源；共享脚本、参考、资产保留在技能根目录。能力不得引用父 router 或同级能力，跨切工作流除外。从 standalone 迁移时，可将参考文件各节拆分内联进对应能力。
校验命令：单个技能 python scripts/validate_skill.py /path/to/skill [--verbose] [--json]；能力加 --capability；嵌套引用加 --allow-nested-references；全系统审计 python scripts/audit_skill_system.py /path/to/system-root。打包分发用 python scripts/bundle.py /path/to/skill --system-root /path/to/.agents --output my-skill.zip，也可用 npx skills add 直接安装。
内容加载分三级：Level 1 元数据约 100 token 常驻上下文；Level 2 指令小于 5000 token 或约 500 行，触发时加载；Level 3 资源按需加载。核心内容保持平台中立，原生扫描 .agents/skills/ 的工具无需额外配置，其他工具需创建薄部署指针。具体价格与平台支持细节暂未提供。