stack-analyzer

name	stack-analyzer
description	分析项目技术栈并推荐技能。自动检测框架，激活通用 ai-dev-kit 技能，并可选择在目标仓库中脚手架生成项目特定技能。

技术栈分析器技能

一个元技能，用于分析项目的技术栈并推荐或脚手架生成合适的 AI 辅助开发技能。此技能在 /ai-dev-kit:setup 期间自动运行，也可手动调用。

设计原则

插件隔离

不留痕迹：ai-dev-kit 插件必须能完全移除而不留下残留物。此技能强制执行：

组件	位置	卸载时
通用技能	plugins/ai-dev-kit/skills/	随插件一起移除
项目特定技能	目标仓库 .claude/skills/	用户自行决定
生成的清单	.claude/skills/_generated.json	用户自行决定

通用性

所有 ai-dev-kit 技能都是框架通用的，不针对任何特定代码库：

模式	正确	错误
BAML 技能	通用 BAML 模式	CodeGraph-DE 特定的 DTO
Supabase 技能	通用最佳实践	Book-Vetting 特定的查询
Schema 对齐	适用于任何 ORM	假设特定模型

变量

变量	默认值	描述
AUTO_ACTIVATE	false	自动激活推荐的通用技能
SCAFFOLD_SKILLS	false	在目标仓库中脚手架生成项目特定技能
OUTPUT_REPORT	true	生成推荐报告
MANIFEST_PATH	.claude/skills/_generated.json	生成清单的路径

使用说明

必须 - 按顺序执行以下工作流步骤。

1. 运行 library-detection 技能获取项目技术栈
2. 将检测到的技术栈与技能推荐进行匹配
3. 报告推荐的通用技能
4. 可选：脚手架生成项目特定技能
5. 如果创建了技能，更新生成的清单

危险信号 - 停下来重新考虑

如果你即将：

• 创建针对特定代码库的技能（而非通用模式）
• 将项目特定技能放在插件目录中
• 跳过生成清单的更新
• 为未检测到的技术推荐技能

停下来 -> 验证检测结果 -> 使用通用模式 -> 然后继续

工作流

1. 检测项目技术栈

首先调用 library-detection 技能：

读取并执行 plugins/ai-dev-kit/skills/library-detection/SKILL.md

返回内容：
- languages（typescript、python 等）
- frameworks（react、fastapi 等）
- test_frameworks（vitest、pytest 等）
- databases（postgresql、sqlite 等）
- build_tools（vite、uv 等）

2. 与技能推荐匹配

从 ./config/recommendations.yaml 加载推荐并匹配：

对于每个检测到的技术：
  如果匹配技能激活规则：
    添加到 recommended_skills 列表
  如果匹配脚手架模板规则：
    添加到 scaffold_candidates 列表

3. 生成报告

创建推荐报告：

# 技术栈分析报告

## 检测到的技术栈
- **语言**：TypeScript、Python
- **框架**：Next.js、FastAPI
- **数据库**：PostgreSQL（通过 Supabase）
- **测试**：Vitest、Pytest
- **AI/ML**：BAML

## 推荐的通用技能（在插件中）

| 技能 | 原因 | 状态 |
|------|------|------|
| baml-integration | 在 baml_src/ 中检测到 BAML | 已激活 |
| supabase-patterns | 发现 Supabase 依赖 | 已激活 |
| schema-alignment | 检测到 SQLAlchemy | 已激活 |

## 项目特定技能（可脚手架生成）

| 模板 | 触发条件 | 输出 |
|------|----------|------|
| project-research | 发现 3 个研究子代理 | .claude/skills/{project}-research/ |
| project-domain | src/models/ 中有模型 | .claude/skills/{project}-domain/ |

4. 脚手架生成项目特定技能（如已启用）

对每个脚手架候选：

# 1. 复制模板到目标仓库
cp -r ./templates/{template}/ ${TARGET_REPO}/.claude/skills/{project}-{template}/

# 2. 添加生成头信息到 SKILL.md
echo "<!-- Generated by ai-dev-kit:recommend-skills on $(date) -->" | \
  cat - ./templates/{template}/SKILL.md > temp && mv temp SKILL.md

# 3. 用项目名称自定义
sed -i "s/{project}/${PROJECT_NAME}/g" SKILL.md

5. 更新生成清单

创建或更新 .claude/skills/_generated.json。

技能推荐规则

通用技能（激活）

技能	检测条件
baml-integration	baml_src/**/*.baml 存在或有 baml-py/baml 依赖
supabase-patterns	有 supabase 依赖或 supabase/migrations/ 存在
schema-alignment	检测到 sqlalchemy/prisma/django/alembic
treesitter-patterns	有 tree-sitter/tree_sitter 依赖
security-audit	生产代码库始终推荐

项目特定技能（脚手架）

模板	检测条件
project-research	.claude/commands/**/research/** 或 subagent.*research 模式
project-domain	src/models/** 或 services/domain/** 存在
project-testing	超出标准框架的自定义测试模式

模板

project-research

用于有研究导向子代理的项目：

templates/project-research/
├── SKILL.md          # 自定义研究模式
├── cookbook/
│   └── research-workflow.md
└── reference/
    └── source-types.md

project-domain

用于有丰富领域模型的项目：

templates/project-domain/
├── SKILL.md          # 领域词汇和模式
├── cookbook/
│   └── entity-relationships.md
└── reference/
    └── domain-glossary.md

project-testing

用于有自定义测试需求的项目：

templates/project-testing/
├── SKILL.md          # 自定义测试模式
├── cookbook/
│   └── test-fixtures.md
└── reference/
    └── coverage-requirements.md

集成

与 /ai-dev-kit:setup 集成

在现有项目设置期间自动运行：

1. 用户运行：/ai-dev-kit:setup
2. Setup 调用：stack-analyzer 技能
3. 技术栈分析器：
   - 检测技术栈
   - 显示推荐
   - 提示："激活推荐的技能？[y/N]"
   - 如果是：标记技能为已激活
   - 提示："脚手架生成项目特定技能？[y/N]"
   - 如果是：在目标仓库中创建技能
4. Setup 继续剩余步骤

与 /ai-dev-kit:recommend-skills 集成

直接调用：

# 仅报告（无变更）
/ai-dev-kit:recommend-skills

# 自动激活通用技能
/ai-dev-kit:recommend-skills --auto-activate

# 脚手架生成项目特定技能
/ai-dev-kit:recommend-skills --scaffold

# 所有选项
/ai-dev-kit:recommend-skills --auto-activate --scaffold --output=report.md

卸载时清理

移除 ai-dev-kit 插件时，通知用户：

## ai-dev-kit 卸载通知

以下文件由 ai-dev-kit 生成，卸载后仍保留：

**项目特定技能：**
- .claude/skills/book-vetting-research/
- .claude/skills/book-vetting-domain/

**文档：**
- ai-docs/libraries/baml/
- ai-docs/libraries/supabase/

完整列表见 .claude/skills/_generated.json。

这些文件如不再需要可安全删除。