项目概览（Project Overview）

一、项目定位与目标

agent-skills 是由 tech-leads-club 维护的开源项目，旨在为 AI 编程代理（coding agents）提供一套可复用、可版本化、面向工程实践的技能（Skills）目录。这些技能以 Markdown 文件和结构化元数据的形式存在，能够被 AI 代理在合适的场景中自动发现并加载，从而引导代理完成特定任务，例如编写技术设计文档、规划架构分解、执行规格驱动开发等。资料来源：README.md

项目的核心价值在于：

• 标准化工程流程：将"分解单体"、"识别领域"、"驱动规格"等工程方法论沉淀为可执行技能。
• 跨语言支持：技能说明和示例覆盖英语、葡萄牙语与西班牙语，降低非英语用户的使用门槛。资料来源：create-technical-design-doc/README.md
• 可扩展目录结构：通过分类目录（如 creation、architecture、development、quality）组织技能，便于贡献者按主题添加新条目。资料来源：react-best-practices/README.md

二、仓库与架构

项目采用 Nx Monorepo 结构管理多个包与库，根级 package.json 与 nx.json 定义了统一的脚本、依赖与构建图。核心组成包括：

资料来源：nx.json、packages/marketplace/README.md、libs/core/src/lib/types.ts

技能目录下的每个子目录通常以括号包围的主题词作为顶层分类，例如 (architecture) 包含 decomposition-planning-roadmap、domain-identification-grouping、component-identification-sizing、component-flattening-analysis、component-common-domain-detection 等面向单体分解与领域驱动设计的技能。资料来源：decomposition-planning-roadmap/README.md

三、核心数据流

技能的加载与渲染流程可概括为：技能 Markdown → parseMarkdown 解析为 token 流 → 视图组件按 token 渲染为页面。MarkdownToken 联合类型支持 heading、paragraph、list-item、code-block、hr、blank 等块级元素，配合 InlineSegment 表达粗体、斜体与行内代码。资料来源：libs/core/src/lib/services/markdown-parser.service.ts、libs/core/src/lib/types.ts

SkillsMode 类型（'local' | 'remote'）允许消费方在本地目录与远程注册中心之间切换技能来源；DeprecatedEntry 则用于在注册中心显式标注已弃用技能及其替代方案。资料来源：libs/core/src/lib/types.ts

flowchart LR
    A[技能 Markdown<br/>SKILL.md / README.md] --> B[stripFrontmatter]
    B --> C[parseMarkdown]
    C --> D[MarkdownToken 流]
    D --> E[技能查看器 / Marketplace 页面]
    F[SkillsMode<br/>local / remote] --> C
    G[DeprecatedEntry] --> E

四、典型技能示例

• create-technical-design-doc：交互式引导代理编写技术设计文档（TDD），根据项目规模、类型自动调整必选/可选章节，并对支付、鉴权类项目强制要求安全、回滚与监控章节。资料来源：create-technical-design-doc/README.md
• decomposition-planning-roadmap：协调 component-identification-sizing → component-flattening-analysis → component-dependency-analysis → domain-identification-grouping 等前置技能，输出分阶段路线图、优先级工作项与架构故事。资料来源：decomposition-planning-roadmap/README.md
• domain-identification-grouping：将组件按业务领域分组，建议命名空间重构，并提供 validateDomainNamespaces 等适应性函数（fitness functions）持续守护边界。资料来源：domain-identification-grouping/README.md
• tlc-spec-driven：通过 Specify → Discuss → Design → Tasks → Implement 五个阶段管理功能开发，并支持 Map codebase、Pause/Resume 等项目级操作。资料来源：tlc-spec-driven/README.md
• react-best-practices：基于规则文件（rules/）+ pnpm build 的流程，将分散的 React 最佳实践编译为统一的 AGENTS.md，供代理在编写 React 代码时引用。资料来源：react-best-practices/README.md

五、社区关注的重点

根据近期 Issue 反馈，社区主要关注以下方面：

1. 安全合规：Issue #57 报告 MCP Go SDK 中 serialize-javascript 存在 RCE 漏洞（CVE-2026-27896），提示项目在引入新依赖时需关注传递性漏洞。资料来源：SECURITY.md
2. CLI 体验：Issue #42 反馈安装技能时 --skill/-s 标志未被识别，提示 CLI 参数解析可能存在兼容性问题。资料来源：packages/skills-catalog/skills/(architecture)/decomposition-planning-roadmap/README.md
3. 目录扩展性：Issue #38 提议新增 (marketing) 分类并整合 agent-gtm-skills 18 个技能文件，扩展技能覆盖范围。资料来源：CHANGELOG.md
4. 贡献流程：Issue #135 指出 CONTRIBUTING.md 建议通过 Fork + PR 贡献，但仓库设置限制了非协作者，与文档存在冲突。资料来源：CONTRIBUTING.md
5. 文档完整性：Issue #134 反映 tlc-spec-driven 的 README 缺少 mermaid-studio 与 codenavi 的真实集成链接，导致 AI 代理误判为外部包。资料来源：tlc-spec-driven/README.md

最新发布 skills-catalog-v0.14.3（2026-04-28）新增了 tactical-ddd 技能并优化其描述，展示了项目持续以"按主题新增技能"的方式演进。资料来源：CHANGELOG.md

六、See Also

• 技能目录结构与贡献指南：CONTRIBUTING.md
• 安全漏洞披露策略：SECURITY.md
• 面向 AI 代理的总体说明：AGENTS.md
• 版本演进记录：CHANGELOG.md
• Markdown 解析与共享类型：libs/core/src/lib/services/markdown-parser.service.ts

概述与设计目标

agent-skills 是一个面向 AI 编码代理的可复用"技能"(skill) 仓库与发布平台。它通过 Nx monorepo 将技能内容、共享核心库与静态站点整合在一起，使技能既能被人阅读，也能被 LLM 解析与调用。系统的核心设计目标包括：技能可发现、技能可组合、技能可发布。

顶层结构（Monorepo 布局）

仓库按"包"(package) 与"库"(library) 两类组织：

• packages/skills-catalog/：技能内容源，所有技能按 (类别) 命名的目录组织，例如 (architecture)/、(creation)/、(development)/、(quality)/、(cloud)/。每个技能包含 SKILL.md 描述文件以及可附带的 references/、README.md 等子资源。资料来源：packages/skills-catalog/skills/(architecture)/component-identification-sizing/README.md:1-15
• packages/marketplace/：技能展示站点，使用 Next.js 静态导出构建，对外域名 agent-skills.techleads.club，提供 SEO、暗色模式与目录浏览能力。资料来源：packages/marketplace/README.md:1-30
• libs/core/：跨包共享的核心能力，导出工具与服务（如 markdown 解析器）。资料来源：libs/core/src/lib/services/markdown-parser.service.ts:1-40

graph LR
  A[skills-catalog<br/>技能源] --> B[核心库 libs/core<br/>markdown-parser / types / ports]
  A --> C[marketplace<br/>Next.js 静态站点]
  B --> C
  C --> D[用户 / AI 代理<br/>agent-skills.techleads.club]

技能的分类与组合模式

技能目录使用括号前缀 (category) 实现自描述分组，无需额外元数据即可被目录读取器识别。基于已纳入的技能族系，可以识别出三类主要协作模式：

1. 架构分解链路：六个架构分解模式按顺序衔接，从"识别与度量组件" → "检测公共领域组件" → "扁平化分析" → "依赖分析" → "领域识别与分组" → "分解规划与路线图"，由路线图技能统一编排。资料来源：packages/skills-catalog/skills/(architecture)/decomposition-planning-roadmap/README.md:1-60、packages/skills-catalog/skills/(architecture)/component-identification-sizing/README.md:1-30
2. 规约驱动开发（spec-driven）：以 .specs/ 目录为单一事实源，包含 PROJECT.md、ROADMAP.md、STATE.md 以及按需生成的 codebase/ 七份棕地文档与 features/[name]/ 子目录；通过四阶段自适应流程（Specify → Design → Tasks → Implement）支持新建与遗留项目。资料来源：packages/skills-catalog/skills/(development)/tlc-spec-driven/README.md:1-40
3. 质量与运维知识：以独立技能形式沉淀，例如 react-best-practices 提供基于 metadata.json 与 rules/ 的可编译规则库，输出 AGENTS.md 供 LLM 消费。资料来源：packages/skills-catalog/skills/(quality)/react-best-practices/README.md:1-25

核心库与服务接口

libs/core 提供技能运行与站点渲染所需的底层能力。markdown-parser.service.ts 通过 parseMarkdown() 将原始 Markdown（包括 YAML frontmatter、围栏代码块、标题、列表与水平线）规整为紧凑的 token 序列，供技能查看器复用，避免在每个技能与页面中重复实现解析逻辑。资料来源：libs/core/src/lib/services/markdown-parser.service.ts:15-50

站点与分发

packages/marketplace 负责技能的对外发布。它基于 Next.js 静态导出（output: 'export'），启用尾斜杠并禁用图片优化以适配静态托管；技能新增只需在 skills/ 下创建含 SKILL.md 的目录并在 skills/categories.json 中登记即可被自动发现。资料来源：packages/marketplace/README.md:1-35

已知约束与社区关注点

• 贡献流程受阻：社区报告仓库设置阻止非协作者发起 PR，与 CONTRIBUTING.md 描述的"Fork → 分支 → PR"流程冲突（issue #135），这是架构外的协作约束，但会影响技能生态扩张。
• CLI 标志兼容：社区报告 --skill / -s 标志未被识别（issue #42），表明技能安装入口与 CLI 参数解析仍需对齐 skills-catalog 的发现规则。
• 依赖安全：issue #57 揭示 MCP Go SDK 中 serialize-javascript 的 CVE-2026-27896，提醒在扩展技能运行时需关注第三方依赖的传递性漏洞。

See Also

• Skills Catalog Overview
• Marketplace Site
• Spec-Driven Development
• Decomposition Planning Roadmap

CLI, Core Services & Workflows

面向专业 AI 编码 Agent 的安全、经过校验的技能注册中心，让您可以放心地为 Antigravity、Claude Code、Cursor、Copilot 等扩展能力。

一、概述与定位

agent-skills 是一个面向 AI 编程代理的可插拔技能（skills）市场与运行时。它由三个相互关联的核心子系统组成：

该项目的核心理念是把"技能"打包成结构化的指令与资源，从而扩展 AI 助理的工作流。README.md 中将其描述为"插件式扩展"：每个技能由主说明文件、模板（templates/）与按需文档（references/）构成，并随分类目录进行分组（如 (architecture)、(development)、(cloud)、(creation)、(security) 等）。资料来源：README.md

二、架构与目录布局

项目采用 monorepo 结构，主要目录如下：

graph LR
    A["Skills Catalog<br/>packages/skills-catalog/skills/"] --> B["SKILL.md"]
    A --> C["references/"]
    A --> D["templates/"]
    B --> E["Markdown Parser<br/>libs/core/markdown-parser.service.ts"]
    C --> F["按需文档<br/>(progressive disclosure)"]
    E --> G["MCP Server<br/>packages/mcp/"]
    G --> H["read_skill 工具<br/>tools/skill-tool.ts"]
    H --> I["AI Agent"]

技能以分类命名的文件夹组织，例如：

packages/skills-catalog/skills/
  (creation)/create-technical-design-doc/SKILL.md
  (cloud)/cloudflare-deploy/references/static-assets/
  (architecture)/component-identification-sizing/SKILL.md

每个技能根目录下的 SKILL.md 是主要指令入口，而 references/ 子目录中的文档（如 configuration.md、api.md、patterns.md、gotchas.md）只在代理需要时按需加载，以节省上下文窗口。资料来源：packages/skills-catalog/skills/(cloud)/cloudflare-deploy/references/static-assets/README.md

三、MCP Server 与渐进式披露

packages/mcp/package.json 定义了 @tech-leads-club/agent-skills-mcp 这个 Node.js 二进制包，要求 node >= 24，依赖 fastmcp 和 fuse.js。它的运行流程被刻意设计为"三步走"：

1. search_skills —— 通过模糊搜索（fuse.js）定位候选技能
2. read_skill —— 读取目标技能的 SKILL.md 完整指令，并列出可用引用文件路径
3. fetch_skill_files —— 仅当代理需要时，按需抓取被引用的 references/ 与 assets/

tools/skill-tool.ts 中 read_skill 的实现展示了"先返回主文件、再返回可用引用清单"的模式：

*"Returns: [0] The skill's main instructions (SKILL.md). [1] A list of available reference file paths (scripts/, references/, assets/)."*

该策略避免了把整个仓库塞进上下文，体现了渐进式披露（progressive disclosure）原则。资料来源：packages/mcp/src/tools/skill-tool.ts、packages/mcp/package.json

四、CLI 与本地安装

README.md 中描述的交互式向导为本地安装流程：选择动作（安装/更新） → 浏览分类或搜索 → 选择目标代理（Cursor、Claude Code、VS Code 等） → 选择安装方式（复制或软链接） → 选择作用域（全局或项目级）。每个步骤都提供 ← Back 回退选项。

常用命令包括：

agent-skills list                              # 列出全部技能
agent-skills install -s tlc-spec-driven        # 安装单个技能

需要特别注意的是，issue #42 报告 CLI 在某些发布渠道中 --skill/-s 标志无法被识别——这是发布配置层面的故障模式，使用前应优先确认 CLI 版本与文档中命令一致。资料来源：README.md

五、内容安全与社区协作

在内容安全方面，README.md 指出：相比开放市场，本目录采用"managed, hardened library"策略，包括 100% 源码开放（无二进制）、CI/CD 静态分析、不可变 lockfile、内容哈希与 Snyk Agent Scan 等纵深防御措施。issue #57 还记录了 MCP Go SDK 中的 serialize-javascript CVE-2026-27896 漏洞，社区已通过 CI 扫描发现并跟进。

在协作流程上，社区曾报告 CONTRIBUTING.md 描述的"fork → PR"流程与仓库"禁止非协作者推送"的设置相冲突（issue #135），实际贡献者需要通过外部 fork 或议题讨论方式接入；新增分类请求（例如 issue #38 中提出的 (marketing) 分类）一般以 RFC 形式提交，等待维护者评估。issue #134 则反映了技能文档需要明确的相对链接，以避免代理把内部组件误认为外部包。资料来源：README.md、packages/skills-catalog/skills/(development)/tlc-spec-driven/README.md

六、版本与发布节奏

技能目录通过独立的 release 流水线发布。当前最新版本 skills-catalog-v0.14.3（2026-04-28）新增了 tactical-ddd 技能，并优化了其描述文案：

## 0.14.3 (2026-04-28)
### 🚀 Features
- skills-catalog: add tactical-ddd skill (c2ba7b8f8)
### 📖 Documentation
- skills-catalog: tighten tactical-ddd description (ce94eea28)

这一节奏意味着生产环境下的消费者（CLI、MCP）应锁定具体版本，以避免目录结构或 frontmatter 字段的隐性变化破坏代理的解析。资料来源：README.md、packages/mcp/package.json

七、See Also

• Skills CLI 与本地安装流程
• Skills frontmatter 与 Markdown 解析器
• 贡献与发布流程（CONTRIBUTING & Conventional Commits）
• MCP 工具注册与 fastmcp 集成

Pitfall Log / 踩坑日志

项目：tech-leads-club/agent-skills

摘要：发现 14 个潜在踩坑项，其中 2 个为 high/blocking；最高优先级：安全/权限坑 - 来源证据：[Security] Risco de Supply Chain e Indirect Prompt Injection no carregamento de skills (@latest)。

1. 安全/权限坑 · 来源证据：[Security] Risco de Supply Chain e Indirect Prompt Injection no carregamento de skills (@latest)

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[Security] Risco de Supply Chain e Indirect Prompt Injection no carregamento de skills (@latest)
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/tech-leads-club/agent-skills/issues/114 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

2. 安全/权限坑 · 来源证据：docs(tlc-spec-driven): "Skill Integrations" table lacks links, steering agents to install third-party forks

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：docs(tlc-spec-driven): "Skill Integrations" table lacks links, steering agents to install third-party forks
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/tech-leads-club/agent-skills/issues/120 | 来源类型 github_issue 暴露的待验证使用条件。

3. 安装坑 · 来源证据：Add TweetClaw skill for OpenClaw X/Twitter workflows

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Add TweetClaw skill for OpenClaw X/Twitter workflows
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/tech-leads-club/agent-skills/issues/131 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。

4. 配置坑 · 可能修改宿主 AI 配置

• 严重度：medium
• 证据强度：source_linked
• 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。
• 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。
• 证据：capability.host_targets | https://github.com/tech-leads-club/agent-skills | host_targets=claude_code, claude, cursor, mcp_host, chatgpt

5. 能力坑 · 能力判断依赖假设

• 严重度：medium
• 证据强度：source_linked
• 发现：README/documentation is current enough for a first validation pass.
• 对用户的影响：假设不成立时，用户拿不到承诺的能力。
• 证据：capability.assumptions | https://github.com/tech-leads-club/agent-skills | README/documentation is current enough for a first validation pass.

6. 维护坑 · 维护活跃度未知

• 严重度：medium
• 证据强度：source_linked
• 发现：未记录 last_activity_observed。
• 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
• 证据：evidence.maintainer_signals | https://github.com/tech-leads-club/agent-skills | last_activity_observed missing

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 证据：downstream_validation.risk_items | https://github.com/tech-leads-club/agent-skills | no_demo; severity=medium

8. 安全/权限坑 · 存在评分风险

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：风险会影响是否适合普通用户安装。
• 证据：risks.scoring_risks | https://github.com/tech-leads-club/agent-skills | no_demo; severity=medium

9. 安全/权限坑 · 来源证据：The organisation has archived and discontinued OpenCode and recommended the migration to Crush

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：The organisation has archived and discontinued OpenCode and recommended the migration to Crush
• 对用户的影响：可能影响升级、迁移或版本选择。
• 证据：community_evidence:github | https://github.com/tech-leads-club/agent-skills/issues/123 | 来源类型 github_issue 暴露的待验证使用条件。

10. 安全/权限坑 · 来源证据：docs: CONTRIBUTING.md says to open a PR but repo blocks non-collaborators

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：docs: CONTRIBUTING.md says to open a PR but repo blocks non-collaborators
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 证据：community_evidence:github | https://github.com/tech-leads-club/agent-skills/issues/135 | 来源类型 github_issue 暴露的待验证使用条件。

11. 安全/权限坑 · 来源证据：🔐 Community Tool: SkilLock — capability-drift PR review for Claude/Codex Skills

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：🔐 Community Tool: SkilLock — capability-drift PR review for Claude/Codex Skills
• 对用户的影响：可能阻塞安装或首次运行。
• 证据：community_evidence:github | https://github.com/tech-leads-club/agent-skills/issues/126 | 来源类型 github_issue 暴露的待验证使用条件。

12. 安全/权限坑 · 来源证据：🔒 Security Scan: Issues Found in Skills

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：🔒 Security Scan: Issues Found in Skills
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 证据：community_evidence:github | https://github.com/tech-leads-club/agent-skills/issues/129 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。

13. 维护坑 · issue/PR 响应质量未知

• 严重度：low
• 证据强度：source_linked
• 发现：issue_or_pr_quality=unknown。
• 对用户的影响：用户无法判断遇到问题后是否有人维护。
• 证据：evidence.maintainer_signals | https://github.com/tech-leads-club/agent-skills | issue_or_pr_quality=unknown

14. 维护坑 · 发布节奏不明确

• 严重度：low
• 证据强度：source_linked
• 发现：release_recency=unknown。
• 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
• 证据：evidence.maintainer_signals | https://github.com/tech-leads-club/agent-skills | release_recency=unknown