README.md

ai-coding-kit

本仓库聚合两套互相关联的本地工程化能力：Agent Skill 的维护与多端同步，以及 MCP / Codex 配置的单源多端同步。二者可独立使用；一起使用时，可在 Codex、Claude Code、Cursor 与 Xcode 相关路径上保持技能与 MCP 配置同源、少漂移。

目录	说明
skills-engineering	维护、同步与演进工程化 Skill（当前主技能 ios-engineer）；含 SKILL.md、references、演进提案与校验、同步到各 Agent skills 目录与 preamble。详见该目录 README。
mcp	MCP server 清单（servers.json）——本地密钥文件、gitignored；以 servers.json.example 为模板。
env	统一配置源目录：env/codex/shared.toml（Codex 通用配置——model / model_provider / features / projects 等 CLI 与 Xcode Coding Assistant 共享字段）、env/claude/settings.shared.json（Claude Code 环境变量）。
sync	把 mcp/servers.json、env/codex/shared.toml、env/claude/settings.shared.json 同步到 Cursor、Codex、Claude Code 与 Xcode Coding Assistant 等路径。详见该目录 README。

认知拓展

独立 skill cognitive-expansion，与 ios-engineer 同级：单源 SKILL.md + references/cognitive_expansion.md，经 sync-skills.sh 同步 全文 到 Codex / Claude / Cursor / Xcode 的 ~/.*/skills/cognitive-expansion/；Cursor 项目内另生成 .cursor/rules/cognitive-expansion.mdc（由详规自动生成，勿手改）。

入口	路径
Skill 源（唯一维护处）	skills-engineering/cognitive-expansion/
详规正文	skills-engineering/cognitive-expansion/references/cognitive_expansion.md
认知对手（Tier 2）	skills-engineering/ios-engineer/references/cognitive_adversary_mode.md

同步：cd skills-engineering && ./scripts/sync-skill-full.sh（先 sync-skills.sh 全文，再 sync-agent-preamble.sh 写入 preamble 加载指令与 Cursor .mdc）。新增 skill 时在 agent-preamble.md.tmpl 的 sync-manifest 加 skill:<name>。详见 skills-engineering/README.md。

触发语：默认 Tier 0 尾注；【深潜】 / 【拓展】；【认知对手模式】 等走 ios-engineer 认知对手全文。

快速开始

• 技能与 preamble：在 skills-engineering 下按 skills-engineering/README.md 的「快速开始」执行 ./scripts/sync-skills.sh 等。
• MCP / Codex / Claude 共享：编辑 mcp/servers.json（从 mcp/servers.json.example 复制）、env/codex/shared.toml 或 env/claude/settings.shared.json，然后执行 bash sync/sync_all.sh。详见 sync/README.md。

忽略规则：敏感文件与本机配置由仓库根目录 .gitignore 统一管理（例如 mcp/servers.json、skills-engineering/scripts/config.local.sh）。

Git 钩子

仓库根级统一管理 pre-commit 与 pre-push，安装一次同时启用两个 subtree 的守卫：

bash install-hooks.sh

会把 core.hooksPath 指向 .githooks/：

• .githooks/pre-commit：拦截 skills-engineering/ios-engineer/SKILL.md 与 references/*.md 的未治理变更（必须同 commit 绑定 evolution proposal + approval）。
• .githooks/pre-push：推送前依次跑 skills-engineering 同步链（sync-skills.sh → sync-agent-preamble.sh → verify-sync.sh），再跑 sync/sync_all.sh；默认任一失败中止 push（例外：mcp/servers.json 缺失时，sync_all.sh 会跳过并退出 0，不阻断 push）。

紧急绕过：

SKILL_BYPASS=1 git commit ...        # 跳过 skill 治理 + skill-sync 链（仍跑 sync/sync_all.sh）
git push --no-verify                 # 跳过整个 pre-push

详细行为见各 subtree README 的「Git 钩子」章节。

平台说明

技能同步与脚本当前以 macOS 下的 Codex、Claude Code、Cursor 为主；MCP 同步支持 macOS 与 Linux。细节以各子目录 README 为准。