.agents 目录承载了所有 skills，会导致本地开发的 token 消耗过大，需要考虑区分开发使用和 workflow 使用场景

[Terry-Mao]

.agents/skills 中有本地开发和 github workflow 全量 SKILL，需要优化下，如何隔离，避免本地开发时候token消耗过大。

[github-actions]

分诊结论

该 issue 是一个 enhancement，主要影响 area:skills 和 area:workflow。

当前仓库中 .codex/skills 与 .claude/skills 都指向共享的 .agents/skills，而该目录包含本地开发 helper 与 GitHub workflow 专用 skill 的全量集合。README、docs/local-development-flow.md、docs/github-collaboration-flow.md 和 product wiki 的 agent directory layout 也都按共享 skill 入口描述当前设计，暂未看到本地开发与 workflow 使用场景的隔离机制。

复现度评估为 high：从仓库目录结构和文档即可确认本地入口会暴露全量 .agents/skills。建议后续规格设计重点明确：

• 本地开发默认应暴露哪些 skill。
• GitHub workflow 专用 skill 是否应保留在 workflow-only 入口或运行时上下文中。
• 安装脚本和工具入口目录是否需要生成不同的 skill surface。
• 现有 GitHub Actions 中显式读取 skill 路径的流程如何保持兼容。

重复检查：候选列表中 #243 与本问题有较宽泛的体系优化交集，但不是同一具体请求；其余候选不满足相同标题意图和描述细节。未达到两个以上 likely duplicate 的阈值，因此不标记 duplicate。

[Terry-Mao]

拆分本地 Skills 与 GitHub Workflow Skills

Summary

将 skill 按运行场景拆分：

• .agents/skills/：本地开发可发现 skills，以及本地和 workflow 共用的 shared skills。
• .github/skills/：只由 GitHub Actions workflow 显式读取的 workflow-only skills。
• .agents/contracts/：继续存放共享合同和 schema。

目标是让 .codex/skills -> ../.agents/skills、.claude/skills -> ../.agents/skills 仍然可用，但本地默认只暴露本地/共享 skill，避免 workflow-only skill 增加本地 token 面。

Key Changes

• 保留在 .agents/skills/：

  • 本地入口：create-issue、create-pr、diagnose-ci-failures、git-*、resolve-merge-conflicts、review-pr-local、review-spec-local、bootstrap-issue-config
  • shared spec 能力：spec-driven-implementation、write-product-spec、write-tech-spec

• 迁移到 .github/skills/：

  • workflow core：triage-issue、dedupe-issue、create-product-spec、create-tech-spec、implement-issue、implement-specs
  • review：review-pr、review-spec、check-impl-against-spec、security-review-pr、security-review-spec
  • product/update：product-change-report、product-docs-sync、product-wiki、update-pr-review、update-dedupe、update-triage
  • repo companions：review-pr-repo、review-spec-repo、triage-issue-repo、dedupe-issue-repo

• 更新所有 workflow prompt、helper scripts、skill 内部引用和 validators：

  • workflow-only skill 路径改为 .github/skills//SKILL.md
  • shared skill 路径继续使用 .agents/skills//SKILL.md
  • review contract 中 validator 路径随 review-pr 迁移改为 .github/skills/review-pr/scripts/validate_review_json.py
  • self-evolution 写入范围改为 .github/skills/*-repo/

• 更新安装逻辑：

  • install.sh 同步 .agents/skills/、.agents/contracts/、.github/skills/、.github/agents/、.github/scripts/、managed workflows
  • repo-local companion skills 在 .github/skills/*-repo/ 下仍不由安装脚本覆盖；目标仓库已有 companion 保留
  • .agents/skills/*-repo/ 旧规则不再作为主要路径，但测试可覆盖不会误装旧 companion

• 更新文档：

  • README、AGENTS、docs/agent-directories.md、docs/local-development-flow.md、docs/github-collaboration-flow.md
  • product raw/wiki 中涉及 skill 路径、agent directory layout、review/triage/dedupe/update workflow 的页面
  • 说明 .agents/skills 是本地/共享入口，.github/skills 是 workflow automation 入口

Test Plan

• 路径和安装测试：

  • 更新 .github/tests/test_install_script.py，断言 local/shared skills 安装到 .agents/skills，workflow skills 安装到 .github/skills，repo companions 不覆盖目标仓库已有文件
  • 更新所有 .github/aicodingflow-tests/ 中硬编码 .agents/skills/... 的断言

• Workflow 合同测试：

  • 跑全量：PYTHONDONTWRITEBYTECODE=1 python3 -m unittest discover -s .github/aicodingflow-tests
  • 跑安装测试：PYTHONDONTWRITEBYTECODE=1 python3 -m unittest discover -s .github/tests -p 'test_install_script.py'
  • 编译迁移后仍含 Python 脚本的 skill helper：
    PYTHONPYCACHEPREFIX=/tmp/aicodingflow-pycache python3 -m py_compile <changed .py paths>

• 静态检查：

  • rg -n ".agents/skills/(triage|dedupe|review-pr|review-spec|implement|product-|update-|security|check-impl|create-product|create-tech)" 确认 workflow-only 旧路径已清理
  • git diff --check

Assumptions

• 第一版不新增 install.sh --profile，只做目录职责拆分；安装 profile 后续单独做。
• write-product-spec、write-tech-spec、spec-driven-implementation 保留在 .agents/skills/，作为 local/shared skills，被 workflow 显式引用时不迁移。
• .codex/skills 和 .claude/skills 继续指向 .agents/skills，通过减少 .agents/skills 内容来降低本地默认 skill 发现面。
• 旧 .agents/skills/-repo companion 不做兼容读取；迁移后权威路径是 .github/skills/-repo。