@pigcloud/skills 1.0.3 → 1.0.5

package/CHANGELOG.md

@@ -8,9 +8,9 @@
 
 ### Changed
 - Made postinstall client-aware so it can auto-install into the detected client(s) from `INIT_CWD`.
-- Kept Codex as the only client with a real command pack so `/prd`, `/analyze`, and friends remain executable entries instead of fake aliases.
+- Kept Codex as the only client with a real command pack so `/spec` remains the executable entry instead of a fake alias.
 - Extended `pig-skills auto` to install the matching client folders for Codex, Claude Code, Trae, Cursor, Copilot, and Windsurf.
-- Clarified in the README and usage docs that only Codex gets `/prd`-style command files, while other clients receive skills and rules.
+- Clarified in the README and usage docs that only Codex gets `/spec`-style command files, while other clients receive skills and rules.
 - Unified the usage guides around the same client-detection and knowledge-capture model.
 
 ## [1.1.0] - 2026-06-18
@@ -19,7 +19,7 @@
 - 重构 skill 体系说明，按当前 13 个 skill 重新梳理 README 和使用方式
 - 补充统一校验入口 `validate-skills.js`，并增加 Windows / macOS / Linux 壳
 - 将便携 Python 纳入仓库内，避免依赖系统环境
-- 统一 `spec-refinement`、`knowledge-capture`、`workflow-router` 等高频 skill 的识别与门禁表达
+- 统一 `spec`、`knowledge-capture`、`workflow-router` 等高频 skill 的识别与门禁表达
 - 收缩 skill frontmatter，按官方 validator 规范保留最小字段
 - 将 `handover` 合并进 `knowledge-capture`，删除独立交接 skill
 
@@ -41,7 +41,7 @@
 
 ### Skills
 - **Core**: workflow-router, technical-design, feature-build, code-review
-- **Analysis**: spec-refinement, domain-modeling
+- **Analysis**: spec, domain-modeling
 - **Integration**: api-docs, test-design
 - **Collaboration**: knowledge-capture
 - **Infrastructure**: project-bootstrap, environment-deploy

package/README.en.md

@@ -1,83 +1,74 @@
-# @pigcloud/skills
-
-> An AI skills pack for product, engineering, and QA collaboration. `@pigcloud/skills` is the npm package name; `skills/` carries reusable capabilities, `rules/` carries constraints and validation, `workflow-router` handles stage routing, and `CI / Test / Evidence` completes the delivery loop.
-
-## What this system does
-
-- Route first, then execute
-- Constrain first, then generate
-- Reuse first, then rewrite
-- Verify first, then conclude
-
-## Core Layers
-
-1. `workflow-router`: identifies the task type and chooses the next stage
-2. `skills/`: reusable capability modules
-3. `rules/`: project constraints, boundaries, and hard checks
-4. `CI / Test / Evidence`: verifiable delivery gates
-
-## Common Entry Points
-
-- Product intake: `product-intake`
-- Requirement refinement: `spec-refinement`
-- Stage routing: `workflow-router`
-- Design and implementation: `technical-design` / `feature-build`
-- Review and validation: `code-review` / `security-review` / `performance-check`
-- Knowledge capture: `knowledge-capture`
-
-## Install
-
-```bash
-npm install -g @pigcloud/skills
-```
-
-## Migration Note
-
-- `@pig-cloud/skills` is the historical package name
-- `@pig/skills` was the intermediate migration name
-- New installs should use `@pigcloud/skills`
-- `Pig Cloud` is only the repository-specific rules/scaffold context, not the npm package name
-
-## Client Setup
-
-- Codex: see [docs/CODEX-APP-GUIDE.md](docs/CODEX-APP-GUIDE.md)
-- Trae: see [docs/TRAE-GUIDE.md](docs/TRAE-GUIDE.md)
-- Cloud Code / Claude Code: see [docs/CLAUDE-CODE-GUIDE.md](docs/CLAUDE-CODE-GUIDE.md)
-- Unified installation guide: see [docs/client-installation-guide.md](docs/client-installation-guide.md)
-
-## Governance Overview
-
-- System overview: [docs/agent-governance-overview.md](docs/agent-governance-overview.md)
-- Skills extension guide: [docs/skills-extension-guide.md](docs/skills-extension-guide.md)
-- Package migration note: [docs/package-name-migration.md](docs/package-name-migration.md)
-
-## Validation
-
-```bash
-node validate-skills.js
-node scripts/validate-skill-shapes.js
-node scripts/validate-rules.js
-node scripts/validate-skill-stop-rules.js
-node scripts/validate-skill-replay-signals.js
-node self-test-skills.js
-```
-
-## Directory Map
-
-- `skills/`: skill bodies
-- `skills/references/`: authoring standard, reference matrix, loading map
-- `rules/`: rule entry point and bundles
-- `docs/`: install, governance, migration, and workflow notes
-- `bin/`: CLI, auto-install, postinstall
-
-## Entry Docs
-
-- [AGENTS.md](AGENTS.md)
-- [docs/README.md](docs/README.md)
-- [docs/client-installation-guide.md](docs/client-installation-guide.md)
-- [docs/agent-governance-overview.md](docs/agent-governance-overview.md)
-- [docs/skills-extension-guide.md](docs/skills-extension-guide.md)
-- [docs/package-name-migration.md](docs/package-name-migration.md)
-- [skills/references/skill-authoring-standard.md](skills/references/skill-authoring-standard.md)
-- [skills/references/skill-reference-matrix.md](skills/references/skill-reference-matrix.md)
-- [skills/references/rule-loading-map.md](skills/references/rule-loading-map.md)
+# @pigcloud/skills
+
+> An AI skills pack for product, engineering, and QA collaboration. `skills/` carries reusable capabilities, `rules/` carries constraints and validation, `workflow-router` handles stage routing, and `CI / Test / Evidence` completes the delivery loop.
+
+## What this system does
+
+- Route first, then execute
+- Constrain first, then generate
+- Reuse first, then rewrite
+- Verify first, then conclude
+
+## Core Layers
+
+1. `workflow-router`: identifies the task type and chooses the next stage
+2. `skills/`: reusable capability modules
+3. `rules/`: project constraints, boundaries, and hard checks
+4. `CI / Test / Evidence`: verifiable delivery gates
+
+## Common Entry Points
+
+- Spec: `spec`
+- Stage routing: `workflow-router`
+- Design and implementation: `technical-design` / `feature-build`
+- Review and validation: `code-review` / `security-review` / `performance-check`
+- Fact extraction: `extract-business-facts`
+- Knowledge capture: `knowledge-capture`
+
+## Install
+
+```bash
+npm install -g @pigcloud/skills
+```
+
+## Client Setup
+
+- Codex: see [docs/CODEX-APP-GUIDE.md](docs/CODEX-APP-GUIDE.md)
+- Trae: see [docs/TRAE-GUIDE.md](docs/TRAE-GUIDE.md)
+- Claude Code: see [docs/CLAUDE-CODE-GUIDE.md](docs/CLAUDE-CODE-GUIDE.md)
+- Unified installation guide: see [docs/client-installation-guide.md](docs/client-installation-guide.md)
+
+## Governance Overview
+
+- System overview: [docs/agent-governance-overview.md](docs/agent-governance-overview.md)
+- Skills extension guide: [docs/skills-extension-guide.md](docs/skills-extension-guide.md)
+
+## Validation
+
+```bash
+node validate-skills.js
+node scripts/validate-skill-shapes.js
+node scripts/validate-rules.js
+node scripts/validate-skill-stop-rules.js
+node scripts/validate-skill-replay-signals.js
+node self-test-skills.js
+```
+
+## Directory Map
+
+- `skills/`: skill bodies
+- `skills/references/`: authoring standard, reference matrix, loading map
+- `rules/`: rule entry point and bundles
+- `docs/`: install, governance, and workflow notes
+- `bin/`: CLI, auto-install, postinstall
+
+## Entry Docs
+
+- [AGENTS.md](AGENTS.md)
+- [docs/README.md](docs/README.md)
+- [docs/client-installation-guide.md](docs/client-installation-guide.md)
+- [docs/agent-governance-overview.md](docs/agent-governance-overview.md)
+- [docs/skills-extension-guide.md](docs/skills-extension-guide.md)
+- [skills/references/skill-authoring-standard.md](skills/references/skill-authoring-standard.md)
+- [skills/references/skill-reference-matrix.md](skills/references/skill-reference-matrix.md)
+- [skills/references/rule-loading-map.md](skills/references/rule-loading-map.md)

package/README.md

@@ -1,85 +1,74 @@
-# @pigcloud/skills
-
-> 一个面向产品、研发、测试协作的 AI skills pack。`@pigcloud/skills` 是 npm 包名；`skills/` 负责能力执行，`rules/` 负责约束与校验，`workflow-router` 负责阶段编排，`CI / Test / Evidence` 负责交付闭环。
-
-## 这套体系做什么
-
-- 先路由，再执行
-- 先约束，再生成
-- 先复用，再重写
-- 先验证，再结论
-
-## 核心分层
-
-1. `workflow-router`：识别任务类型并决定下一阶段
-2. `skills/`：承载可复用能力模块
-3. `rules/`：承载项目规范、边界和强约束
-4. `CI / Test / Evidence`：承载可验证交付
-
-## 常见入口
-
-- 产品收口：`product-intake`
-- 需求细化：`spec-refinement`
-- 阶段路由：`workflow-router`
-- 设计与实现：`technical-design` / `feature-build`
-- 审核与验证：`code-review` / `security-review` / `performance-check`
-- 知识沉淀：`knowledge-capture`
-
-## 安装
-
-### 全局安装
-
-```bash
-npm install -g @pigcloud/skills
-```
-
-### 迁移说明
-
-- `@pig-cloud/skills` 是历史包名
-- `@pig/skills` 是迁移中间名
-- 现在请使用 `@pigcloud/skills`
-- `Pig Cloud` 仅表示仓库里的专属规则/脚手架语境，不再表示 npm 包名
-
-## 客户端接入
-
-- Codex：见 [docs/CODEX-APP-GUIDE.md](docs/CODEX-APP-GUIDE.md)
-- Trae：见 [docs/TRAE-GUIDE.md](docs/TRAE-GUIDE.md)
-- Cloud Code / Claude Code：见 [docs/CLAUDE-CODE-GUIDE.md](docs/CLAUDE-CODE-GUIDE.md)
-- 统一安装说明：见 [docs/client-installation-guide.md](docs/client-installation-guide.md)
-
-## 治理总览
-
-- 体系总览：见 [docs/agent-governance-overview.md](docs/agent-governance-overview.md)
-- 技能扩展：见 [docs/skills-extension-guide.md](docs/skills-extension-guide.md)
-- 包名迁移：见 [docs/package-name-migration.md](docs/package-name-migration.md)
-
-## 验证
-
-```bash
-node validate-skills.js
-node scripts/validate-skill-shapes.js
-node scripts/validate-rules.js
-node scripts/validate-skill-stop-rules.js
-node scripts/validate-skill-replay-signals.js
-node self-test-skills.js
-```
-
-## 目录
-
-- `skills/`：技能主体
-- `skills/references/`：作者规范、参考矩阵、规则加载地图
-- `rules/`：规则入口和 bundle
-- `docs/`：安装、治理、迁移、工作流说明
-- `bin/`：CLI、自动安装、postinstall
-
-## 入口文档
-
-- [AGENTS.md](AGENTS.md)
-- [docs/README.md](docs/README.md)
-- [docs/client-installation-guide.md](docs/client-installation-guide.md)
-- [docs/agent-governance-overview.md](docs/agent-governance-overview.md)
-- [docs/skills-extension-guide.md](docs/skills-extension-guide.md)
-- [docs/package-name-migration.md](docs/package-name-migration.md)
-- [skills/references/skill-authoring-standard.md](skills/references/skill-authoring-standard.md)
-- [skills/references/skill-reference-matrix.md](skills/references/skill-reference-matrix.md)
-- [skills/references/rule-loading-map.md](skills/references/rule-loading-map.md)
+# @pigcloud/skills
+
+> 一个面向产品、研发、测试协作的 AI 技能包。`skills/` 负责任务边界与交接，`rules/` 负责规则约束与校验，`workflow-router` 负责阶段路由，`CI / Test / Evidence` 负责交付闭环。
+
+## 这套系统做什么
+
+- 先路由，再执行
+- 先约束，再生成
+- 先复用，再改写
+- 先验证，再结论
+
+## 核心层
+
+1. `workflow-router`：识别任务类型并选择下一阶段
+2. `skills/`：可复用的能力模块
+3. `rules/`：项目约束、边界和硬校验
+4. `CI / Test / Evidence`：可验证的交付门禁
+
+## 常用入口
+
+- 规格澄清：`spec`
+- 阶段路由：`workflow-router`
+- 设计与实现：`technical-design` / `feature-build`
+- 审查与验证：`code-review` / `security-review` / `performance-check`
+- 事实抽取：`extract-business-facts`
+- 知识沉淀：`knowledge-capture`
+
+## 安装
+
+```bash
+npm install -g @pigcloud/skills
+```
+
+## 客户端接入
+
+- Codex：见 [docs/CODEX-APP-GUIDE.md](docs/CODEX-APP-GUIDE.md)
+- Trae：见 [docs/TRAE-GUIDE.md](docs/TRAE-GUIDE.md)
+- Claude Code：见 [docs/CLAUDE-CODE-GUIDE.md](docs/CLAUDE-CODE-GUIDE.md)
+- 统一安装指南：见 [docs/client-installation-guide.md](docs/client-installation-guide.md)
+
+## 治理概览
+
+- 系统总览：见 [docs/agent-governance-overview.md](docs/agent-governance-overview.md)
+- 技能扩展指南：见 [docs/skills-extension-guide.md](docs/skills-extension-guide.md)
+
+## 校验
+
+```bash
+node validate-skills.js
+node scripts/validate-skill-shapes.js
+node scripts/validate-rules.js
+node scripts/validate-skill-stop-rules.js
+node scripts/validate-skill-replay-signals.js
+node self-test-skills.js
+```
+
+## 目录说明
+
+- `skills/`：技能正文
+- `skills/references/`：编写标准、参考矩阵、加载映射
+- `rules/`：规则入口与规则包
+- `docs/`：安装、治理和工作流说明
+- `bin/`：CLI、自动安装、postinstall
+
+## 入口文档
+
+- [AGENTS.md](AGENTS.md)
+- [docs/README.md](docs/README.md)
+- [docs/client-installation-guide.md](docs/client-installation-guide.md)
+- [docs/agent-governance-overview.md](docs/agent-governance-overview.md)
+- [docs/skills-extension-guide.md](docs/skills-extension-guide.md)
+- [skills/references/skill-authoring-standard.md](skills/references/skill-authoring-standard.md)
+- [skills/references/skill-reference-matrix.md](skills/references/skill-reference-matrix.md)
+- [skills/references/rule-loading-map.md](skills/references/rule-loading-map.md)

package/bin/cli.js

@@ -7,16 +7,17 @@ const os = require('os');
 const { detectRulesBundle } = require('./rules-loader');
 const { ensureNpmRuntime } = require('./runtime-bootstrap');
 
-const PACKAGE_ROOT = path.join(__dirname, '..');
-const SKILLS_DIR = path.join(PACKAGE_ROOT, 'skills');
-const VERSION = require('../package.json').version;
-const CODEX_HOME = process.env.CODEX_HOME || path.join(os.homedir(), '.codex');
-const AGENTS_HOME = path.join(os.homedir(), '.agents');
-const COMMAND_PACK_NAME = 'pig-cloud-skills-commands';
-const COMMAND_PACK_SOURCE = path.join(PACKAGE_ROOT, COMMAND_PACK_NAME);
-const CODEX_HOME_SKILLS_DIR = path.join(CODEX_HOME, 'skills');
-const AGENTS_PLUGINS_DIR = path.join(AGENTS_HOME, 'plugins');
-const AGENTS_MARKETPLACE_FILE = path.join(AGENTS_PLUGINS_DIR, 'marketplace.json');
+const PACKAGE_ROOT = path.join(__dirname, '..');
+const SKILLS_DIR = path.join(PACKAGE_ROOT, 'skills');
+const VERSION = require('../package.json').version;
+const CODEX_HOME = process.env.CODEX_HOME || path.join(os.homedir(), '.codex');
+const COMMAND_PACK_NAME = 'codex-commands';
+const COMMAND_PACK_SOURCE = path.join(PACKAGE_ROOT, COMMAND_PACK_NAME);
+const CODEX_HOME_SKILLS_DIR = path.join(CODEX_HOME, 'skills');
+const CODEX_HOME_SKILLS_NAMESPACE = 'pigcloud';
+const CODEX_HOME_SKILLS_NAMESPACE_DIR = path.join(CODEX_HOME_SKILLS_DIR, CODEX_HOME_SKILLS_NAMESPACE);
+const CODEX_PLUGINS_DIR = path.join(CODEX_HOME, 'plugins');
+const CODEX_MARKETPLACE_FILE = path.join(CODEX_PLUGINS_DIR, 'marketplace.json');
 const INSTALL_ROOT = path.resolve(process.env.INIT_CWD || process.cwd());
 const SUPPORTED_TOOLS = ['codex', 'claude', 'trae', 'cursor', 'copilot', 'windsurf'];
 const TOOL_ALIASES = {
@@ -43,12 +44,12 @@ const chalk = {
 
 const SKILLS = [
   { name: 'workflow-router', category: 'core', description: 'route workflow stages' },
+  { name: 'spec', category: 'analysis', description: 'turn product input into an executable spec' },
   { name: 'technical-design', category: 'core', description: 'shape implementation design' },
   { name: 'feature-build', category: 'core', description: 'implement features safely' },
   { name: 'code-review', category: 'core', description: 'review code changes' },
-  { name: 'product-intake', category: 'analysis', description: 'capture product intent' },
-  { name: 'spec-refinement', category: 'analysis', description: 'turn demand into specs' },
   { name: 'domain-modeling', category: 'analysis', description: 'extract domain knowledge' },
+  { name: 'extract-business-facts', category: 'analysis', description: 'extract business facts from code' },
   { name: 'api-docs', category: 'integration', description: 'document API contracts' },
   { name: 'test-design', category: 'integration', description: 'design test coverage' },
   { name: 'security-review', category: 'review', description: 'review security risks' },
@@ -58,11 +59,11 @@ const SKILLS = [
   { name: 'environment-deploy', category: 'infrastructure', description: 'deploy supporting environments' }
 ];
 
-const TOOL_CONFIGS = {
-  codex: { dir: '.agents/skills', rootFile: '.agents/AGENTS.md', markers: ['.agents/AGENTS.md', '.agents'] },
-  opencode: { dir: '.agents/skills', rootFile: '.agents/AGENTS.md', markers: ['.agents/AGENTS.md', '.agents'] },
-  claude: { dir: '.claude/skills', rootFile: '.claude/CLAUDE.md', markers: ['.claude/CLAUDE.md', '.claude'] },
-  claude_code: { dir: '.claude/skills', rootFile: '.claude/CLAUDE.md', markers: ['.claude/CLAUDE.md', '.claude'] },
+const TOOL_CONFIGS = {
+  codex: { dir: '.codex/skills/pigcloud', rootFile: '.codex/AGENTS.md', markers: ['.codex/AGENTS.md', '.codex'] },
+  opencode: { dir: '.codex/skills/pigcloud', rootFile: '.codex/AGENTS.md', markers: ['.codex/AGENTS.md', '.codex'] },
+  claude: { dir: '.claude/skills', rootFile: '.claude/CLAUDE.md', markers: ['.claude/CLAUDE.md', '.claude'] },
+  claude_code: { dir: '.claude/skills', rootFile: '.claude/CLAUDE.md', markers: ['.claude/CLAUDE.md', '.claude'] },
   trae: { dir: '.trae/skills', rootFile: '.trae/AGENTS.md', markers: ['.trae/AGENTS.md', '.trae'] },
   cursor: { dir: '.cursor/rules', rootFile: '.cursor/rules/project-rules.mdc', markers: ['.cursor/rules/project-rules.mdc', '.cursor/rules'] },
   copilot: { dir: '.github', rootFile: '.github/copilot-instructions.md', markers: ['.github/copilot-instructions.md'] },
@@ -253,17 +254,29 @@ async function writeRootFile(tool, cwd = process.cwd()) {
   }
 }
 
-async function copySkillToCodexHome(skillName) {
-  const skill = normalizeSkillName(skillName);
-  if (!getSkillInfo(skill)) {
-    throw new Error(`Unknown skill: ${skillName}`);
-  }
-
-  const sourceDir = path.join(SKILLS_DIR, skill);
-  const destDir = path.join(CODEX_HOME_SKILLS_DIR, skill);
-  await ensureDir(CODEX_HOME_SKILLS_DIR);
-  await copyDirectory(sourceDir, destDir);
-}
+async function copySkillToCodexHome(skillName) {
+  const skill = normalizeSkillName(skillName);
+  if (!getSkillInfo(skill)) {
+    throw new Error(`Unknown skill: ${skillName}`);
+  }
+
+  const sourceDir = path.join(SKILLS_DIR, skill);
+  const destDir = path.join(CODEX_HOME_SKILLS_NAMESPACE_DIR, skill);
+  await removePath(path.join(CODEX_HOME_SKILLS_DIR, skill));
+  await removePath(destDir);
+  await ensureDir(CODEX_HOME_SKILLS_NAMESPACE_DIR);
+  await copyDirectory(sourceDir, destDir);
+}
+
+async function clearCodexPersonalSkillsNamespace() {
+  await removePath(CODEX_HOME_SKILLS_NAMESPACE_DIR);
+}
+
+async function clearCodexLegacyFlatSkills(skillNames) {
+  for (const skillName of skillNames) {
+    await removePath(path.join(CODEX_HOME_SKILLS_DIR, normalizeSkillName(skillName)));
+  }
+}
 
 function buildMarketplaceEntry(pluginName) {
   return {
@@ -280,11 +293,11 @@ function buildMarketplaceEntry(pluginName) {
   };
 }
 
-async function writeCodexMarketplaceEntry(pluginName) {
-  await ensureDir(AGENTS_PLUGINS_DIR);
-  const existing = (await pathExists(AGENTS_MARKETPLACE_FILE))
-    ? await readJson(AGENTS_MARKETPLACE_FILE)
-    : { name: 'personal', interface: { displayName: 'Personal' }, plugins: [] };
+async function writeCodexMarketplaceEntry(pluginName) {
+  await ensureDir(CODEX_PLUGINS_DIR);
+  const existing = (await pathExists(CODEX_MARKETPLACE_FILE))
+    ? await readJson(CODEX_MARKETPLACE_FILE)
+    : { name: 'personal', interface: { displayName: 'Personal' }, plugins: [] };
 
   if (!existing.name) existing.name = 'personal';
   if (!existing.interface) existing.interface = { displayName: 'Personal' };
@@ -298,19 +311,19 @@ async function writeCodexMarketplaceEntry(pluginName) {
     existing.plugins.push(entry);
   }
 
-  await writeJson(AGENTS_MARKETPLACE_FILE, existing);
-}
-
-async function installCodexCommandPack() {
-  if (!(await pathExists(COMMAND_PACK_SOURCE))) {
-    throw new Error(`Codex command pack not found: ${COMMAND_PACK_SOURCE}`);
-  }
-
-  const destDir = path.join(AGENTS_PLUGINS_DIR, COMMAND_PACK_NAME);
-  await ensureDir(AGENTS_PLUGINS_DIR);
-  await copyDirectory(COMMAND_PACK_SOURCE, destDir);
-  await writeCodexMarketplaceEntry(COMMAND_PACK_NAME);
-}
+  await writeJson(CODEX_MARKETPLACE_FILE, existing);
+}
+
+async function installCodexCommandPack() {
+  if (!(await pathExists(COMMAND_PACK_SOURCE))) {
+    throw new Error(`Codex command pack not found: ${COMMAND_PACK_SOURCE}`);
+  }
+
+  const destDir = path.join(CODEX_PLUGINS_DIR, COMMAND_PACK_NAME);
+  await ensureDir(CODEX_PLUGINS_DIR);
+  await copyDirectory(COMMAND_PACK_SOURCE, destDir);
+  await writeCodexMarketplaceEntry(COMMAND_PACK_NAME);
+}
 
 async function installSharedWorkspaceAssets(cwd = getInstallRoot()) {
   const sharedAssets = [
@@ -325,13 +338,18 @@ async function installSharedWorkspaceAssets(cwd = getInstallRoot()) {
   }
 }
 
-async function installSkills(skills, tool, cwd = getInstallRoot()) {
-  await installSharedWorkspaceAssets(cwd);
-  for (const skill of skills) {
-    await copySkill(skill, tool, cwd);
-  }
-  await writeRootFile(tool, cwd);
-  if (tool === 'codex') {
+async function installSkills(skills, tool, cwd = getInstallRoot(), options = {}) {
+  const { resetCodexNamespace = false } = options;
+  await installSharedWorkspaceAssets(cwd);
+  if (tool === 'codex' && resetCodexNamespace) {
+    await clearCodexPersonalSkillsNamespace();
+    await clearCodexLegacyFlatSkills(skills);
+  }
+  for (const skill of skills) {
+    await copySkill(skill, tool, cwd);
+  }
+  await writeRootFile(tool, cwd);
+  if (tool === 'codex') {
     for (const skill of skills) {
       await copySkillToCodexHome(skill);
     }
@@ -339,16 +357,16 @@ async function installSkills(skills, tool, cwd = getInstallRoot()) {
   }
 }
 
-async function installSkillsForTools(skills, tools, cwd = getInstallRoot()) {
-  const uniqueTools = [...new Set(tools.filter(Boolean))];
-  if (uniqueTools.length === 0) {
-    throw new Error('Unable to resolve any install targets.');
-  }
-
-  for (const tool of uniqueTools) {
-    await installSkills(skills, tool, cwd);
-  }
-}
+async function installSkillsForTools(skills, tools, cwd = getInstallRoot(), options = {}) {
+  const uniqueTools = [...new Set(tools.filter(Boolean))];
+  if (uniqueTools.length === 0) {
+    throw new Error('Unable to resolve any install targets.');
+  }
+
+  for (const tool of uniqueTools) {
+    await installSkills(skills, tool, cwd, options);
+  }
+}
 
 function parseArgs(argv) {
   const positionals = [];
@@ -465,10 +483,10 @@ async function run() {
   if (command === 'init') {
     const skills = getSelectedSkills(options.skills, options.all || !options.skills);
     try {
-      await ensureRuntimeForInstall();
-      const tools = resolveRequestedTools(options.tool);
-      await installSkillsForTools(skills, tools);
-      console.log(chalk.green(`Installed ${skills.length} skills for ${tools.join(', ')}`));
+      await ensureRuntimeForInstall();
+      const tools = resolveRequestedTools(options.tool);
+      await installSkillsForTools(skills, tools, getInstallRoot(), { resetCodexNamespace: true });
+      console.log(chalk.green(`Installed ${skills.length} skills for ${tools.join(', ')}`));
     } catch (error) {
       console.error(chalk.red(error.message));
       process.exitCode = 1;
@@ -479,10 +497,10 @@ async function run() {
   if (command === 'auto') {
     const skills = getSelectedSkills(options.skills, options.all || !options.skills);
     try {
-      await ensureRuntimeForInstall();
-      const tools = resolveRequestedTools('auto');
-      await installSkillsForTools(skills, tools);
-      console.log(chalk.green(`Auto-installed ${skills.length} skills for ${tools.join(', ')}`));
+      await ensureRuntimeForInstall();
+      const tools = resolveRequestedTools('auto');
+      await installSkillsForTools(skills, tools, getInstallRoot(), { resetCodexNamespace: true });
+      console.log(chalk.green(`Auto-installed ${skills.length} skills for ${tools.join(', ')}`));
     } catch (error) {
       console.error(chalk.red(error.message));
       process.exitCode = 1;
@@ -493,9 +511,9 @@ async function run() {
   if (command === 'codex') {
     const skills = getSelectedSkills(options.skills, options.all || !options.skills);
     try {
-      await ensureRuntimeForInstall();
-      await installSkills(skills, 'codex');
-      console.log(chalk.green(`Synced ${skills.length} skills into Codex`));
+      await ensureRuntimeForInstall();
+      await installSkills(skills, 'codex', getInstallRoot(), { resetCodexNamespace: true });
+      console.log(chalk.green(`Synced ${skills.length} skills into Codex`));
       console.log(chalk.green(`Installed Codex command pack: ${COMMAND_PACK_NAME}`));
     } catch (error) {
       console.error(chalk.red(error.message));
@@ -570,11 +588,11 @@ async function run() {
       await installSharedWorkspaceAssets();
       for (const tool of tools) {
         await copySkill(skillName, tool);
-        await writeRootFile(tool);
-        if (tool === 'codex') {
-          await copySkillToCodexHome(skillName);
-          await installCodexCommandPack();
-        }
+        await writeRootFile(tool);
+        if (tool === 'codex') {
+          await copySkillToCodexHome(skillName);
+          await installCodexCommandPack();
+        }
       }
       console.log(chalk.green(`Installed: ${normalizeSkillName(skillName)} -> ${tools.join(', ')}`));
     } catch (error) {
@@ -599,12 +617,19 @@ async function run() {
       for (const tool of tools) {
         const targetSkillDir = getTargetSkillDir(tool);
         if (!targetSkillDir) continue;
-        const skillDir = path.join(targetSkillDir, normalizedSkill);
-        if (await pathExists(skillDir)) {
-          await removePath(skillDir);
-          removedAny = true;
-        }
-      }
+        const skillDir = path.join(targetSkillDir, normalizedSkill);
+        if (await pathExists(skillDir)) {
+          await removePath(skillDir);
+          removedAny = true;
+        }
+        if (tool === 'codex') {
+          const legacySkillDir = path.join(CODEX_HOME_SKILLS_DIR, normalizedSkill);
+          if (await pathExists(legacySkillDir)) {
+            await removePath(legacySkillDir);
+            removedAny = true;
+          }
+        }
+      }
       console.log(removedAny
         ? chalk.green(`Removed: ${normalizedSkill}`)
         : chalk.yellow(`Skill not found: ${normalizedSkill}`));
@@ -640,10 +665,10 @@ async function run() {
 
   if (command === 'update') {
     try {
-      await ensureRuntimeForInstall();
-      const tools = resolveRequestedTools(options.tool);
-      await installSkillsForTools(SKILLS.map(skill => skill.name), tools);
-      console.log(chalk.green(`Updated ${SKILLS.length} skills for ${tools.join(', ')}`));
+      await ensureRuntimeForInstall();
+      const tools = resolveRequestedTools(options.tool);
+      await installSkillsForTools(SKILLS.map(skill => skill.name), tools, getInstallRoot(), { resetCodexNamespace: true });
+      console.log(chalk.green(`Updated ${SKILLS.length} skills for ${tools.join(', ')}`));
     } catch (error) {
       console.error(chalk.red(error.message));
       process.exitCode = 1;