refactor: 移除 skills/shared 层级，skills/ 直接作为源目录

- 将 skills/shared/ 目录下所有内容上移到 skills/
- 修复 bootstrap-sync.py 增加 Skill() 调用替换和 skills/{name}/SKILL.md 路径替换
- 更新 bootstrap-sync.yml 和 install.sh 的路径引用
- 更新 CLAUDE.md 添加 ADF 命名空间说明
- 修复 skills/ 下的 Skill 调用和路径引用（去掉 adf- 前缀）

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: alpha-86

.github/workflows/bootstrap-sync.py

@@ -2,14 +2,14 @@
 """
 Bootstrap Sync Script for AgentDevFlow (adf-prefix version)
 
-Reads all .md files from skills/shared/ and generates corresponding skill files
+Reads all .md files from skills/ and generates corresponding skill files
 in .claude/skills/ with adf- prefix.
 
 Each skill gets its own subdirectory: .claude/skills/adf-{name}/
 SKILL.md is generated for top-level entries; subdirectory contents are copied.
 
 Step 0: Clear .claude/skills/
-Step 1: Dynamically scan skills/shared/ and generate adf- prefix mapping
+Step 1: Dynamically scan skills/ and generate adf- prefix mapping
 Step 2: Generate SKILL.md files to .claude/skills/adf-*/
 Step 3: Batch replace internal references
 Step 4: git add -> commit -> push to main
@@ -23,7 +23,7 @@
 from pathlib import Path
 from typing import Optional
 
-SKILLS_SHARED_DIR = Path("skills/shared")
+SKILLS_SHARED_DIR = Path("skills")
 TARGET_DIR = Path(".claude/skills")
 
 # Files that should NOT be synced (internal/shared use only)
@@ -78,7 +78,7 @@ def extract_name_and_description(content: str) -> tuple[str, str]:
 
 
 def build_name_mapping() -> dict[str, str]:
-    """Dynamically scan skills/shared/ and build {original_name: adf_name} mapping."""
+    """Dynamically scan skills/ and build {original_name: adf_name} mapping."""
     mapping = {}
 
     # Top-level .md files → top-level skills
@@ -102,9 +102,10 @@ def replace_internal_references(content: str, mapping: dict[str, str]) -> str:
     """Replace all internal skill references in content.
 
     Patterns replaced:
-    - /{orig} → /adf-{adf}  (skill invocation paths, only when / is followed by word char)
-    - skills/shared/{orig}/ → .claude/skills/adf-{adf}/  (subdirectory references)
-    - skills/shared/{orig}.md → .claude/skills/adf-{adf}/SKILL.md  (direct file references)
+    - /{orig} → /adf-{adf}  (skill invocation paths)
+    - Skill("{orig}") → Skill("{adf}")  (skill invocation calls)
+    - {orig}/SKILL.md → .claude/skills/{adf}/SKILL.md  (skill file references)
+    - skills/{orig}/SKILL.md → .claude/skills/{adf}/SKILL.md  (skills prefix references)
     """
 
     # Only apply replacements for non-skipped items
@@ -117,20 +118,18 @@ def replace_internal_references(content: str, mapping: dict[str, str]) -> str:
             continue
 
         # Skill invocation paths: /agent-bootstrap → /adf-agent-bootstrap
-        # Use word-boundary aware replacement (only at / + word start)
-        # This avoids replacing things like "/start-agent-team" inside "/adf-start-agent-team"
         replacements.append((f"/{orig}", f"/{adf}"))
 
-        # Subdirectory references: skills/shared/agents/ → .claude/skills/adf-agents/
-        replacements.append((f"skills/shared/{orig}/", f".claude/skills/{adf}/"))
+        # Skill invocation calls: Skill("product-manager") → Skill("adf-product-manager")
+        replacements.append((f'Skill("{orig}")', f'Skill("{adf}")'))
 
-        # Direct file references: skills/shared/agent-bootstrap.md → .claude/skills/adf-agent-bootstrap/SKILL.md
-        replacements.append(
-            (f"skills/shared/{orig}.md", f".claude/skills/{adf}/SKILL.md")
-        )
+        # Subdirectory references: product-manager/SKILL.md → .claude/skills/adf-product-manager/SKILL.md
+        replacements.append((f"{orig}/SKILL.md", f".claude/skills/{adf}/SKILL.md"))
+
+        # Also handle skills/ prefix: skills/architect/SKILL.md → .claude/skills/adf-architect/SKILL.md
+        replacements.append((f"skills/{orig}/SKILL.md", f".claude/skills/{adf}/SKILL.md"))
 
     # Sort by length descending to avoid partial replacement issues
-    # (e.g., replace "skills/shared/agents/" before "skills/shared/agent-...")
     replacements.sort(key=lambda x: -len(x[0]))
 
     for old, new in replacements:

.github/workflows/bootstrap-sync.yml

@@ -1,16 +1,16 @@
 name: Bootstrap Sync
 
-# 持续部署：将 skills/shared/ 中的源文件同步到 .claude/skills/
+# 持续部署：将 skills/ 中的源文件同步到 .claude/skills/
 # 作为 AgentDevFlow 的 adf-prefix 自举技能包。
 #
 # 工作原理：
-# 1. 当 skills/shared/ 中的共享技能发生变更并合并到 main 分支时触发
-# 2. 读取 skills/shared/ 中每个 .md 文件
+# 1. 当 skills/ 中的共享技能发生变更并合并到 main 分支时触发
+# 2. 读取 skills/ 中每个 .md 文件
 # 3. 为每个共享技能在 .claude/skills/ 下创建或更新对应的 SKILL.md
 # 4. 直接提交到 main 分支（自举部署，无 PR）
 #
 # 禁止：
-# - 禁止修改 skills/shared/ 源文件（只读取）
+# - 禁止修改 skills/ 源文件（只读取）
 # - 禁止修改非生成文件
 # - 禁止在没有变更时提交空提交
 
@@ -19,7 +19,7 @@ on:
     branches:
       - main
     paths:
-      - 'skills/shared/**/*.md'
+      - 'skills/**/*.md'
       - '.github/workflows/bootstrap-sync.yml'
   workflow_dispatch:
     inputs:
@@ -30,7 +30,7 @@ on:
         type: boolean
 
 env:
-  SKILLS_SHARED_DIR: skills/shared
+  SKILLS_SHARED_DIR: skills
   SKILLS_TARGET_DIR: .claude/skills
 
 jobs:

CLAUDE.md

@@ -1,22 +1,59 @@
 # AgentDevFlow CLAUDE.md
 
+## ADF 命名空间的核心认知（本项目最关键的架构设计）
+
+### adf- 前缀的真正含义
+
+`adf-` 是 AgentDevFlow 的**开发版命名空间**，用于区分本项目自举用的开发版和外部用户安装的稳定版。
+
+| 环境 | 路径 | 命名空间 | Skill 调用 |
+|------|------|---------|-----------|
+| 本项目 (`~/code/AgentDevFlow`) | `.claude/skills/adf-*/` | adf- 开发版 | `Skill("adf-product-manager")` |
+| 外部用户 (`~/.claude/skills/`) | `skills/product-manager/` | 稳定版（无前缀） | `Skill("product-manager")` |
+
+### 核心规则
+
+1. **`skills/` 是唯一源文件**，所有 Skill 调用在源文件中**不带 adf- 前缀**
+2. **bootstrap-sync** 在生成 `.claude/skills/adf-*/` 时，自动把 Skill 调用加上 adf- 前缀
+3. **禁止在 `skills/` 源文件中写 adf- 前缀**（会导致双重前缀或外部用户无法使用）
+
+### bootstrap-sync 替换规则
+
+当 `skills/start-agent-team/SKILL.md` 包含 `Skill("product-manager")` 时：
+- bootstrap-sync 生成 `.claude/skills/adf-start-agent-team/SKILL.md` 时自动替换为 `Skill("adf-product-manager")`
+
+### 错误示例（我曾经犯过的错）
+
+❌ **错误**：`skills/start-agent-team/SKILL.md` 里写 `Skill("adf-product-manager")`
+- 原因：外部用户安装后没有 `adf-product-manager` 这个 skill，会导致调用失败
+
+✅ **正确**：`skills/start-agent-team/SKILL.md` 里写 `Skill("product-manager")`
+- bootstrap-sync 会自动在生成的目标文件中替换为 `Skill("adf-product-manager")`
+
+### 判断依据
+
+- `prompts/by-me/005_V1_如何在本项目中使用.md` — 明确说明 adf- 是命名空间隔离机制
+- `prompts/discuss/024_2026-04-10_adf-prefix自举部署方案.md` — 说明 bootstrap-sync 的替换逻辑
+
+---
+
 ## ADF Bootstrap Skill 架构：真实源 vs 重命名产物
 
 ### 核心概念：禁止直接修改 bootstrap 产物
 
 `.claude/skills/adf-*/SKILL.md` 文件是 `bootstrap-sync` 脚本的**自动生成产物**，不是源文件。
 
-- **真实源文件**在 `skills/shared/` 下
-- **bootstrap-sync** 做的是：路径替换（`skills/shared/` → `.claude/skills/adf-*`）+ frontmatter 注入
+- **真实源文件**在 `skills/` 下
+- **bootstrap-sync** 做的是：路径替换（`skills/` → `.claude/skills/adf-*`）+ frontmatter 注入
 - **禁止直接修改** `.claude/skills/adf-*/SKILL.md`，这些文件会被 bootstrap-sync 覆盖
 
 ### bootstrap-sync 自动同步机制
 
-bootstrap-sync.yml 在 `skills/shared/**/*.md` 变更时自动触发（push to main）。
+bootstrap-sync.yml 在 `skills/**/*.md` 变更时自动触发（push to main）。
 
 **注意**：commit message 中多行 shell 字符串引号可能导致 YAML 解析失败（`[skip ci]"` 结尾问题），需保持 commit message 简洁。
 
-| 真实源 (`skills/shared/`) | bootstrap 产物 (`.claude/skills/`) |
+| 真实源 (`skills/`) | bootstrap 产物 (`.claude/skills/`) |
 |---------------------------|-------------------------------------|
 | `start-agent-team.md` | `adf-start-agent-team/SKILL.md` |
 | `team-setup.md` | `adf-team-setup/SKILL.md` |
@@ -34,7 +71,7 @@ bootstrap-sync 修复后，产物与源文件的差异仅为 frontmatter 注入
 
 ### 工作流原则
 
-1. **只修改源 skill**：`skills/shared/*.md` 是唯一的真实来源，禁止直接修改 `.claude/skills/adf-*/SKILL.md`
+1. **只修改源 skill**：`skills/*.md` 是唯一的真实来源，禁止直接修改 `.claude/skills/adf-*/SKILL.md`
 2. **验证后才发布**：PR 合并前 diff 对照表中的对应文件对，确保产物与源一致
 
 ### GitHub Issue 操作规范
@@ -78,7 +115,7 @@ python scripts/github_issue_sync.py
 ### 相关文件位置
 
 - bootstrap-sync 脚本：`.github/workflows/bootstrap-sync.py`
-- 源 skill：`skills/shared/`
+- 源 skill：`skills/`
 - bootstrap 产物：`.claude/skills/adf-*/SKILL.md`
 - issue-poll workflow：`.github/workflows/issue-poll.yml`
 - task_router 脚本：`scripts/task_router.py`

scripts/install.sh

@@ -12,7 +12,7 @@
 #   ./scripts/install.sh --dry-run              # 预览模式
 #
 # 安装内容:
-#   - skills/shared/ -> {target}/skills/shared/
+#   - skills/ -> {target}/skills/
 #   - adapters/claude/.claude/ -> {target}/skills/
 #
 # 注意:
@@ -113,8 +113,8 @@ check_prerequisites() {
         exit 1
     fi
 
-    if [[ ! -d "$REPO_ROOT/skills/shared" ]]; then
-        error "skills/shared/ 目录不存在"
+    if [[ ! -d "$REPO_ROOT/skills" ]]; then
+        error "skills/ 目录不存在"
         exit 1
     fi
 
@@ -162,9 +162,9 @@ install_dev() {
     fi
     echo ""
 
-    # 安装共享技能（skills/shared/）
-    local shared_source="${REPO_ROOT}/skills/shared"
-    local shared_target="${TARGET_DIR}/skills/shared"
+    # 安装共享技能（skills/）
+    local shared_source="${REPO_ROOT}/skills"
+    local shared_target="${TARGET_DIR}/skills"
 
     info "安装共享技能到 ${shared_target}..."
     if $DRY_RUN; then
@@ -258,8 +258,8 @@ post_install_check() {
     local skill_count=0
     local adapter_count=0
 
-    if [[ -d "${TARGET_DIR}/skills/shared" ]]; then
-        skill_count=$(find "${TARGET_DIR}/skills/shared" -name "*.md" 2>/dev/null | wc -l)
+    if [[ -d "${TARGET_DIR}/skills" ]]; then
+        skill_count=$(find "${TARGET_DIR}/skills" -name "*.md" 2>/dev/null | wc -l)
     fi
 
     if [[ -d "${TARGET_DIR}/skills" ]]; then
@@ -300,7 +300,7 @@ show_next_steps() {
     echo ""
     info "更多信息请查看:"
     echo "  - ${REPO_ROOT}/README.md"
-    echo "  - ${REPO_ROOT}/skills/shared/README.md"
+    echo "  - ${REPO_ROOT}/skills/README.md"
     echo ""
 }
 

skills/shared/README.md skills/README.mdskills/shared/README.md renamed to skills/README.md

@@ -1,6 +1,6 @@
 # 共享技能目录
 
-`skills/shared/` 是 AgentDevFlow 的平台无关执行资产层。
+`skills/` 是 AgentDevFlow 的平台无关执行资产层。
 
 ## 结构
 
@@ -62,7 +62,7 @@
 
 ## 当前判定
 
-`skills/shared/` 现在已经基本构成插件核心资产层，原因是它已经具备：
+`skills/` 现在已经基本构成插件核心资产层，原因是它已经具备：
 
 - 共享启动入口：`team-setup.md`、`start-agent-team.md`、`create-agent.md`
 - 共享协议：`skill-protocol.md`
@@ -74,4 +74,4 @@
 
 - `github-issue/SKILL.md` 对应的共享入口还不够明确
 - `review-org/SKILL.md` 对应的共享入口还不够明确
-- evaluation checker 还没有沉到 `skills/shared/` 形成更独立的检查子能力
+- evaluation checker 还没有沉到 `skills/` 形成更独立的检查子能力

skills/shared/agent-bootstrap/SKILL.md skills/agent-bootstrap/SKILL.mdskills/shared/agent-bootstrap/SKILL.md renamed to skills/agent-bootstrap/SKILL.md

@@ -11,14 +11,14 @@
 | 适用场景 | 任意目标项目启动 AgentDevFlow | AgentDevFlow 自身初始化 |
 | 起点 | 目标项目已有骨架 | 项目骨架待建立或待复核 |
 | 重点 | 建立交付目录、Issue、团队 | 建立 AgentDevFlow 自身治理 + 交付机制 |
-| 角色来源 | `skills/shared/{role}.md` | `skills/shared/{role}.md` (自身) |
+| 角色来源 | `skills/{role}.md` | `skills/{role}.md` (自身) |
 
 ## 执行前必读
 
-1. `skills/shared/start-agent-team.md`
-2. `skills/shared/create-agent.md`
-3. `skills/shared/skill-protocol.md`
-4. `skills/shared/event-bus.md`
+1. `skills/start-agent-team.md`
+2. `skills/create-agent.md`
+3. `skills/skill-protocol.md`
+4. `skills/event-bus.md`
 5. `prompts/001_team_topology.md`
 6. `prompts/010_team_setup_and_bootstrap.md`
 7. `docs/governance/core-principles.md`
@@ -43,7 +43,7 @@
 - `docs/release/` - 发布记录
 - `docs/memo/` - 纪要
 - `docs/todo/` - 待办注册
-- `skills/shared/` - 共享资产层
+- `skills/` - 共享资产层
 - `prompts/` - 规则层
 - `adapters/` - 平台适配
 

skills/shared/architect/SKILL.md skills/architect/SKILL.mdskills/shared/architect/SKILL.md renamed to skills/architect/SKILL.md

@@ -51,11 +51,11 @@
 6. `prompts/017_human_review_and_signoff.md`
 7. `prompts/019_dual_stage_pr_and_three_layer_safeguard.md`
 8. `prompts/021_platform_checks_and_gate_automation.md`
-9. `skills/shared/workflows/tech-review.md`
-10. `skills/shared/workflows/human-review.md`
-11. `skills/shared/workflows/implementation.md`
-12. `skills/shared/templates/tech-spec-template.md`
-13. `skills/shared/templates/review-comment-template.md`
+9. `skills/workflows/tech-review.md`
+10. `skills/workflows/human-review.md`
+11. `skills/workflows/implementation.md`
+12. `skills/templates/tech-spec-template.md`
+13. `skills/templates/review-comment-template.md`
 
 ## 初始化后必做
 
@@ -79,7 +79,7 @@
 
 ## 评审前准备
 
-1. 读取 `skills/shared/workflows/tech-review.md`。
+1. 读取 `skills/workflows/tech-review.md`。
 2. 检查 PRD 中的关键需求、非目标和验收标准。
 3. 检查 Tech Spec 是否覆盖接口、数据流、依赖、验证、发布推进、回滚。
 4. 检查 Issue 评论 中是否已有上游结论。

skills/shared/create-agent/SKILL.md skills/create-agent/SKILL.mdskills/shared/create-agent/SKILL.md renamed to skills/create-agent/SKILL.md

@@ -18,13 +18,13 @@
 
 | 序号 | Agent 名称 | 角色类型 | 角色 Skill | 状态 |
 |------|-----------|---------|------------|------|
-| 1 | Team Lead | team-lead | `adf-team-lead` | **不创建**（Human 本身）|
-| 2 | Product Manager | product-manager | `adf-product-manager` | 立即创建 |
-| 3 | 架构师 | architect | `adf-architect` | 立即创建 |
-| 4 | 质量工程师 | qa-engineer | `adf-qa-engineer` | 立即创建 |
-| 5 | 工程师 | engineer | `adf-engineer` | 立即创建 |
-| 6 | 平台与发布负责人 | platform-sre | `adf-platform-sre` | 立即创建 |
-| 7 | PMO | pmo | `adf-pmo` | 按需创建 |
+| 1 | Team Lead | team-lead | `team-lead` | **不创建**（Human 本身）|
+| 2 | Product Manager | product-manager | `product-manager` | 立即创建 |
+| 3 | 架构师 | architect | `architect` | 立即创建 |
+| 4 | 质量工程师 | qa-engineer | `qa-engineer` | 立即创建 |
+| 5 | 工程师 | engineer | `engineer` | 立即创建 |
+| 6 | 平台与发布负责人 | platform-sre | `platform-sre` | 立即创建 |
+| 7 | PMO | pmo | `pmo` | 按需创建 |
 
 **状态说明**：
 - **不创建**：Team Lead 是 Human 本身，不需要创建 Agent 实例
@@ -36,8 +36,8 @@
 ## 执行前必读
 
 1. `prompts/006_agent_creation_contract.md`
-2. `skills/shared/skill-protocol.md`
-3. `skills/shared/event-bus.md`
+2. `skills/skill-protocol.md`
+3. `skills/event-bus.md`
 4. 对应角色 Skill（见上方速查表）
 
 ## 创建步骤
@@ -55,12 +55,12 @@
 
 | 角色类型 | Skill 路径 |
 |---------|-----------|
-| `product-manager` | `.claude/skills/adf-product-manager/SKILL.md` |
-| `architect` | `.claude/skills/adf-architect/SKILL.md` |
-| `qa-engineer` | `.claude/skills/adf-qa-engineer/SKILL.md` |
-| `engineer` | `.claude/skills/adf-engineer/SKILL.md` |
-| `platform-sre` | `.claude/skills/adf-platform-sre/SKILL.md` |
-| `pmo` | `.claude/skills/adf-pmo/SKILL.md` |
+| `product-manager` | `product-manager/SKILL.md` |
+| `architect` | `architect/SKILL.md` |
+| `qa-engineer` | `qa-engineer/SKILL.md` |
+| `engineer` | `engineer/SKILL.md` |
+| `platform-sre` | `platform-sre/SKILL.md` |
+| `pmo` | `pmo/SKILL.md` |
 
 ### 步骤 1.5. team-lead 类型特殊处理
 

skills/shared/engineer/SKILL.md skills/engineer/SKILL.mdskills/shared/engineer/SKILL.md renamed to skills/engineer/SKILL.md

@@ -58,9 +58,9 @@
 5. `prompts/013_github_issue_and_review_comments.md`
 6. `prompts/016_dual_track_delivery_mechanism.md`
 7. `prompts/019_dual_stage_pr_and_three_layer_safeguard.md`
-8. `skills/shared/workflows/implementation.md`
-9. `skills/shared/workflows/qa-validation.md`
-10. `skills/shared/templates/review-comment-template.md`
+8. `skills/workflows/implementation.md`
+9. `skills/workflows/qa-validation.md`
+10. `skills/templates/review-comment-template.md`
 
 ## 何时启用