@xenonbyte/xsk 0.1.0 → 0.1.1

package/README.md

@@ -1,32 +1,46 @@
 # xsk
 
-Agent skill aggregator. `xsk` curates a small set of agent skills and installs them across Claude Code, Codex, opencode, and Gemini with manifest-backed safety.
+> Curate a small set of agent skills and install them across Claude Code, Codex, opencode, and Gemini, with manifest-backed safety.
 
-Package: `@xenonbyte/xsk` · Binary: `xsk` · Runtime: Node >= 20, CommonJS, zero third-party runtime dependencies.
+[![Node](https://img.shields.io/badge/node-%3E%3D20-3c873a)](https://nodejs.org/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
+[![Runtime deps](https://img.shields.io/badge/runtime%20deps-0-brightgreen)](package.json)
+
+`xsk` (`@xenonbyte/xsk`) is a zero-dependency CLI that installs a curated set of agent skills into every supported AI coding agent, then tracks exactly what it created so uninstall removes only those files.
 
 ## Overview
 
-Two recurring frictions when working across AI coding agents: third-party skill packs are all-or-nothing, and self-authored skills are scattered with no shared install/manifest/safety story. `xsk` solves both. It ships six curated skills (two distilled from third parties, four original) and a CLI that installs each skill into every supported platform's skill directory, then tracks exactly what it created so uninstall removes only those files.
+Working across AI coding agents has two recurring frictions: third-party skill packs are all-or-nothing, and self-authored skills are scattered with no shared install/manifest/safety story. `xsk` solves both. It ships eight curated skills (two distilled from third parties, six original) and a CLI that installs each skill into every supported platform's skill directory, then records exactly what it created so uninstall removes only those files.
 
 `xsk` is itself an agent-skill project and conforms to the same standard its scaffold skill enforces.
 
+## Features
+
+- **Eight curated skills**, not an all-or-nothing pack: install everything, or pick per platform.
+- **Four platforms, one shape.** Claude Code, Codex, opencode, and Gemini share a `<name>/SKILL.md` layout; opencode additionally gets directly invocable `/xsk-<name>` commands.
+- **Manifest-backed safety.** Owned-only removal, ownership markers, atomic writes, symlink refusal, and content-hash drift detection.
+- **Uninstall-first installs.** A reinstall resets prior owned files (pruning skills no longer installed) before regenerating, so no manual `uninstall` is needed.
+- **User edits are never clobbered.** A modified owned file is refused and rolled back instead of being overwritten.
+- **Zero runtime dependencies.** Pure Node.js (>= 20), CommonJS.
+
 ## Installation
 
 ```sh
 npm install -g @xenonbyte/xsk
 ```
 
-Requires Node >= 20 on macOS or Linux.
+> [!IMPORTANT]
+> Requires Node >= 20 on macOS or Linux.
 
 ## Usage
 
 ```sh
-xsk install                 # install every skill into every platform
+xsk install                       # install every skill into every platform
 xsk install --platform claude,codex
-xsk status                  # read-only: what is installed per platform
+xsk status                        # read-only: what is installed per platform
 xsk status --json
-xsk uninstall               # remove only what xsk created
-xsk doctor                  # probe environment + manifest health
+xsk uninstall                     # remove only what xsk created
+xsk doctor                        # probe environment + manifest health
 xsk version
 xsk help
 ```
@@ -46,18 +60,21 @@ Unknown options fail loud with a non-zero exit.
 
 ## Skills
 
-Six skills, prefixed `xsk-`:
+Eight skills, prefixed `xsk-`:
 
 | Skill | Purpose |
 |---|---|
 | `xsk-think` | Turn a rough idea into a decision-complete plan before any code is written. Distilled from Waza `/think`. |
 | `xsk-bypass-claude` | Set the current project to Claude Code bypass-permissions mode by writing `.claude/settings.local.json`. Claude only. |
 | `xsk-skill-scaffold` | Bring an agent-skill project up to the `xsk` standard, or refuse if it is not one. |
-| `xsk-write-req` | Convert plain-language needs into a compliant requirement doc in `requirements/`, grounded in the current project. |
-| `xsk-archive-req` | Archive the active requirement doc into `requirements/archive/`. |
+| `xsk-write-req` | Convert plain-language needs into a compliant requirement doc in `.xsk/requirements/`, grounded in the current project. |
+| `xsk-archive-req` | Archive the active requirement doc into `.xsk/requirements/archive/`. |
 | `xsk-check` | Review a code change before it ships: scope drift, hard stops, evidence-gated findings, then verify and sign off. Distilled from Waza `/check`. |
+| `xsk-point` | Research one aspect of the current project to a decision-complete landed plan and persist it as a point document in `.xsk/points/`. |
+| `xsk-consume-point` | Fold selected `.xsk/points/` documents into one `.xsk/requirements/` doc via `xsk-write-req`, archiving consumed points write-before-remove. |
 
-`xsk-bypass-claude` targets Claude Code only; `xsk install` skips it on the other three platforms.
+> [!NOTE]
+> `xsk-bypass-claude` targets Claude Code only; `xsk install` skips it on the other three platforms.
 
 ## Platforms
 
@@ -67,10 +84,12 @@ All four platforms are full and use the same `<name>/SKILL.md` skill-directory s
 |---|---|
 | Claude Code | `~/.claude/skills/<name>/SKILL.md` |
 | Codex | `~/.agents/skills/<name>/SKILL.md` |
-| opencode | `~/.config/opencode/skills/<name>/SKILL.md` |
+| opencode | `~/.config/opencode/skills/<name>/SKILL.md` (skill) and `~/.config/opencode/commands/xsk-<name>.md` (command) |
 | Gemini | `~/.gemini/skills/<name>/SKILL.md` |
 
-Platform behavior is verified as of 2026-06-25 against the official docs linked from the source repository's `docs/REQUIREMENTS.md`.
+For opencode, `xsk install` writes both a skill directory entry and a flat `commands/xsk-<name>.md` command file for each installed skill, making each skill directly invocable as an opencode `/xsk-<name>` command. Both the skill and the command file are manifest-tracked, and uninstall removes them together.
+
+Platform behavior was verified as of 2026-06-25 against the official docs linked from the source repository's requirement spec under `docs/`.
 
 ## Discovery aliases and duplicate skills
 
@@ -82,15 +101,16 @@ Because those aliases are cross-platform visible, a skill copied into one readab
 
 ## Safety
 
-Installing into user home config dirs is destructive if careless. `xsk` is manifest-backed:
+> [!WARNING]
+> Installing into user home config dirs is destructive if careless. `xsk` is manifest-backed so every write is owned and reversible.
 
-- Owned-only removal. Uninstall removes only paths the manifest recorded.
-- Ownership markers. A `.xsk-owned` marker inside each installed skill dir gates directory removal.
-- No symlink traversal or removal. `xsk` refuses on encounter.
-- Atomic writes. Each file is written to a temp sibling then renamed into place; a failed write restores the original.
-- User edits preserved. If a generated file was user-modified, uninstall keeps it, reports a partial result, and narrows the retained manifest so a later run can finish.
+- **Owned-only removal.** Uninstall removes only paths the manifest recorded.
+- **Ownership markers.** A `.xsk-owned` marker inside each installed skill dir gates directory removal.
+- **No symlink traversal or removal.** `xsk` refuses on encounter.
+- **Atomic writes.** Each file is written to a temp sibling then renamed into place; a failed write restores the original.
+- **User edits preserved.** If a generated file was user-modified, uninstall keeps it, reports a partial result, and narrows the retained manifest so a later run can finish.
 
-`xsk` writes only under `~/.xsk/` and the four platform skill dirs.
+`xsk` writes only under `~/.xsk/`, the four platform skill dirs, and opencode's `~/.config/opencode/commands/` command dir.
 
 ## Development
 
@@ -100,8 +120,8 @@ npm run syntaxcheck # node --check every bin/, lib/, test/ file
 npm pack --dry-run  # verify package contents
 ```
 
-The full requirement specification lives in the source repository at `docs/REQUIREMENTS.md`.
+The full requirement specification lives in the source repository under `docs/`.
 
-## License
+---
 
-MIT
+MIT licensed. See [LICENSE](LICENSE).

package/README.zh-CN.md

@@ -1,32 +1,46 @@
 # xsk
 
-Agent skill aggregator（智能体技能聚合器）。`xsk` 精选了一小组 agent skill，并以 manifest 记录作为安全保障，将它们安装到 Claude Code、Codex、opencode 与 Gemini 四个平台。
+> 精选一小组 agent skill，以 manifest 记录作为安全保障，安装到 Claude Code、Codex、opencode 与 Gemini。
 
-Package: `@xenonbyte/xsk` · Binary: `xsk` · Runtime: Node >= 20, CommonJS, 零第三方运行时依赖。
+[![Node](https://img.shields.io/badge/node-%3E%3D20-3c873a)](https://nodejs.org/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
+[![Runtime deps](https://img.shields.io/badge/runtime%20deps-0-brightgreen)](package.json)
+
+`xsk`（`@xenonbyte/xsk`）是一个零依赖 CLI，把一组精选的 agent skill 安装到每个受支持的 AI coding agent，并精确记录它创建了哪些文件，使 uninstall 只移除这些文件。
 
 ## Overview
 
-跨多个 AI coding agent 工作时有两类反复出现的摩擦：第三方 skill 包要么全装要么不装（all-or-nothing），自写的 skill 又散落各处、缺少统一的安装 / manifest / 安全方案。`xsk` 同时解决这两点。它内置六个精选 skill（两个从第三方蒸馏而来，四个原创），并提供一个 CLI，把每个 skill 安装到所有受支持平台的 skill 目录，再精确记录它创建了哪些文件，使 uninstall 只移除这些文件。
+跨多个 AI coding agent 工作时有两类反复出现的摩擦：第三方 skill 包要么全装要么不装（all-or-nothing），自写的 skill 又散落各处、缺少统一的安装 / manifest / 安全方案。`xsk` 同时解决这两点。它内置八个精选 skill（两个从第三方蒸馏而来，六个原创），并提供一个 CLI，把每个 skill 安装到所有受支持平台的 skill 目录，再精确记录它创建了哪些文件，使 uninstall 只移除这些文件。
 
 `xsk` 本身就是一个 agent-skill 项目，并符合它自己的 scaffold skill 所执行的同一套标准。
 
+## Features
+
+- **八个精选 skill**，不是全装或不装的整包，可全部安装，也可按平台挑选。
+- **四个平台，同一形态。** Claude Code、Codex、opencode 与 Gemini 共用 `<name>/SKILL.md` 布局；opencode 还额外获得可直接调用的 `/xsk-<name>` 命令。
+- **manifest 为后盾的安全。** owned-only removal、ownership markers、atomic writes、symlink refusal，以及 content-hash 漂移检测。
+- **uninstall-first 安装。** 重装会先重置此前 owned 的文件（清理已不再安装的 skill）再生成，无需手动 `uninstall`。
+- **绝不覆盖用户改动。** 被改过的 owned 文件会被拒绝并回滚，而不会被覆盖。
+- **零运行时依赖。** 纯 Node.js（>= 20），CommonJS。
+
 ## Installation
 
 ```sh
 npm install -g @xenonbyte/xsk
 ```
 
-要求 macOS 或 Linux 上的 Node >= 20。
+> [!IMPORTANT]
+> 要求 macOS 或 Linux 上的 Node >= 20。
 
 ## Usage
 
 ```sh
-xsk install                 # 把所有 skill 安装到所有平台
+xsk install                       # 把所有 skill 安装到所有平台
 xsk install --platform claude,codex
-xsk status                  # 只读：查看每个平台已安装的内容
+xsk status                        # 只读：查看每个平台已安装的内容
 xsk status --json
-xsk uninstall               # 只移除 xsk 创建的内容
-xsk doctor                  # 探测环境与 manifest 健康状况
+xsk uninstall                     # 只移除 xsk 创建的内容
+xsk doctor                        # 探测环境与 manifest 健康状况
 xsk version
 xsk help
 ```
@@ -46,18 +60,21 @@ xsk help
 
 ## Skills
 
-共六个 skill，统一前缀 `xsk-`：
+共八个 skill，统一前缀 `xsk-`：
 
 | Skill | Purpose |
 |---|---|
 | `xsk-think` | 把一个粗略想法在写任何代码之前变成 decision-complete 的 plan。蒸馏自 Waza `/think`。 |
 | `xsk-bypass-claude` | 通过写 `.claude/settings.local.json` 把当前项目设为 Claude Code bypass-permissions 模式。仅 Claude。 |
 | `xsk-skill-scaffold` | 把一个 agent-skill 项目带到 `xsk` 标准；若不是这类项目则拒绝。 |
-| `xsk-write-req` | 把白话需求转成 `requirements/` 下合规的需求文档，并扎根于当前项目。 |
-| `xsk-archive-req` | 把当前 active 需求文档归档到 `requirements/archive/`。 |
+| `xsk-write-req` | 把白话需求转成 `.xsk/requirements/` 下合规的需求文档，并扎根于当前项目。 |
+| `xsk-archive-req` | 把当前 active 需求文档归档到 `.xsk/requirements/archive/`。 |
 | `xsk-check` | 在改动合入前评审：范围漂移、hard stops、证据门控的发现项，再验证后签收。蒸馏自 Waza `/check`。 |
+| `xsk-point` | 把当前项目某一方面研究到 decision-complete 的落地方案，并作为 point 文档持久化到 `.xsk/points/`。 |
+| `xsk-consume-point` | 通过 `xsk-write-req` 把选定的 `.xsk/points/` 文档折叠进一份 `.xsk/requirements/` 文档，以 write-before-remove 方式归档已消费的 point。 |
 
-`xsk-bypass-claude` 仅面向 Claude Code；`xsk install` 会在其余三个平台跳过它。
+> [!NOTE]
+> `xsk-bypass-claude` 仅面向 Claude Code；`xsk install` 会在其余三个平台跳过它。
 
 ## Platforms
 
@@ -67,10 +84,12 @@ xsk help
 |---|---|
 | Claude Code | `~/.claude/skills/<name>/SKILL.md` |
 | Codex | `~/.agents/skills/<name>/SKILL.md` |
-| opencode | `~/.config/opencode/skills/<name>/SKILL.md` |
+| opencode | `~/.config/opencode/skills/<name>/SKILL.md`（skill）和 `~/.config/opencode/commands/xsk-<name>.md`（command） |
 | Gemini | `~/.gemini/skills/<name>/SKILL.md` |
 
-平台行为依据源仓库 `docs/REQUIREMENTS.md` 中链接的官方文档，校验日期为 2026-06-25。
+对于 opencode，`xsk install` 会为每个已安装的 skill 同时写入 skill 目录条目和平坦的 `commands/xsk-<name>.md` 命令文件，使每个 skill 都可作为 opencode `/xsk-<name>` 命令直接调用。skill 与命令文件均由 manifest 跟踪，卸载时一并移除。
+
+平台行为依据源仓库 `docs/` 下需求规格中链接的官方文档，校验日期为 2026-06-25。
 
 ## Discovery aliases and duplicate skills
 
@@ -82,15 +101,16 @@ opencode 除了自己的 `~/.config/opencode/skills/<name>/SKILL.md`，也会读
 
 ## Safety
 
-向用户 home 配置目录写入若不小心具有破坏性。`xsk` 以 manifest 为后盾：
+> [!WARNING]
+> 向用户 home 配置目录写入若不小心具有破坏性。`xsk` 以 manifest 为后盾，使每次写入都是 owned 且可逆的。
 
-- Owned-only removal。uninstall 只移除 manifest 记录的路径。
-- Ownership markers。每个已安装 skill 目录内有 `.xsk-owned` 标记，目录移除需先校验该标记。
-- No symlink traversal or removal。`xsk` 遇到 symlink 会拒绝。
-- Atomic writes。每个文件先写入临时同目录文件，再 rename 就位；写入失败时恢复原文件。
-- User edits preserved。若生成的文件被用户修改，uninstall 会保留它、报告 partial，并收窄保留的 manifest，使后续可继续完成。
+- **Owned-only removal。** uninstall 只移除 manifest 记录的路径。
+- **Ownership markers。** 每个已安装 skill 目录内有 `.xsk-owned` 标记，目录移除需先校验该标记。
+- **No symlink traversal or removal。** `xsk` 遇到 symlink 会拒绝。
+- **Atomic writes。** 每个文件先写入临时同目录文件，再 rename 就位；写入失败时恢复原文件。
+- **User edits preserved。** 若生成的文件被用户修改，uninstall 会保留它、报告 partial，并收窄保留的 manifest，使后续可继续完成。
 
-`xsk` 只在 `~/.xsk/` 与四个平台 skill 目录下写入。
+`xsk` 只在 `~/.xsk/`、四个平台 skill 目录，以及 opencode 的 `~/.config/opencode/commands/` command 目录下写入。
 
 ## Development
 
@@ -100,8 +120,8 @@ npm run syntaxcheck # 对 bin/、lib/、test/ 下每个文件执行 node --check
 npm pack --dry-run  # 校验 package 内容
 ```
 
-完整需求规格见源仓库中的 `docs/REQUIREMENTS.md`。
+完整需求规格见源仓库 `docs/` 目录。
 
-## License
+---
 
-MIT
+基于 MIT 许可证发布。见 [LICENSE](LICENSE)。

package/bin/xsk.js

@@ -2,7 +2,7 @@
 'use strict';
 
 const { parse } = require('../lib/input');
-const { install } = require('../lib/install');
+const { install, isCommandFilePath } = require('../lib/install');
 const { uninstall } = require('../lib/uninstall');
 const { computeStatus, render: renderStatus } = require('../lib/status');
 const { doctor, render: renderDoctor } = require('../lib/capability');
@@ -41,8 +41,12 @@ function formatInstall(summary) {
       continue;
     }
     const skillCount = (r.installed || []).filter((p) => p.endsWith('SKILL.md')).length;
+    const commandCount = (r.installed || []).filter((p) => isCommandFilePath(p)).length;
     const backCount = (r.backups || []).length;
     let line = `${platform}: installed ${skillCount} skill${skillCount === 1 ? '' : 's'}`;
+    if (commandCount > 0) {
+      line += `; installed ${commandCount} command${commandCount === 1 ? '' : 's'}`;
+    }
     if (backCount > 0) {
       line += `; backed up ${backCount} displaced file${backCount === 1 ? '' : 's'}`;
     }
@@ -64,9 +68,13 @@ function formatUninstall(summary) {
       continue;
     }
     const removedCount = (r.removed || []).filter((p) => p.endsWith('SKILL.md')).length;
+    const removedCommandCount = (r.removed || []).filter((p) => isCommandFilePath(p)).length;
     const restoredCount = (r.restored || []).length;
     const retainedCount = (r.retained || []).length;
     let line = `${platform}: removed ${removedCount} skill${removedCount === 1 ? '' : 's'}`;
+    if (removedCommandCount > 0) {
+      line += `; removed ${removedCommandCount} command${removedCommandCount === 1 ? '' : 's'}`;
+    }
     if (restoredCount > 0) {
       line += `, restored ${restoredCount} displaced file${restoredCount === 1 ? '' : 's'}`;
     }
@@ -102,6 +110,7 @@ function main(argv, options) {
 
   const dispatchOptions = {
     platformRoots: opts.platformRoots,
+    platformCommandsRoots: opts.platformCommandsRoots,
     xskRoot: opts.xskRoot,
   };
 

package/lib/adapters/opencode.js

@@ -11,4 +11,10 @@ function skillsRoot(options) {
   return path.join(home, '.config', 'opencode', 'skills');
 }
 
-module.exports = { PLATFORM, skillsRoot };
+function commandsRoot(options) {
+  const opts = options || {};
+  const home = opts.home || os.homedir();
+  return path.join(home, '.config', 'opencode', 'commands');
+}
+
+module.exports = { PLATFORM, skillsRoot, commandsRoot };

package/lib/capability.js

@@ -4,7 +4,7 @@ const fs = require('node:fs');
 const path = require('node:path');
 
 const { defaultXskRoot, isSafePath } = require('./manifest');
-const { rootFor, ALL_PLATFORMS } = require('./install');
+const { rootFor, commandsRootFor, ALL_PLATFORMS } = require('./install');
 const { computeStatus } = require('./status');
 
 const REQUIRED_NODE_MAJOR = 20;
@@ -77,9 +77,36 @@ function doctor(options) {
       pass: isWritableDir(root),
       detail: isWritableDir(root) ? 'writable or creatable' : 'not writable',
     });
+
+    let commandsRoot;
+    try {
+      commandsRoot = commandsRootFor(platform, opts.platformCommandsRoots);
+    } catch (e) {
+      checks.push({
+        name: `writable-${platform}-commands`,
+        label: `${platform} commands dir writable`,
+        pass: false,
+        detail: `could not resolve commands dir: ${e.message}`,
+      });
+      continue;
+    }
+    if (commandsRoot) {
+      const writableCommandsRoot = isWritableDir(commandsRoot);
+      checks.push({
+        name: `writable-${platform}-commands`,
+        label: `${platform} commands dir writable (${commandsRoot})`,
+        pass: writableCommandsRoot,
+        detail: writableCommandsRoot ? 'writable or creatable' : 'not writable',
+      });
+    }
   }
 
-  const status = computeStatus({ platforms, xskRoot, platformRoots: opts.platformRoots });
+  const status = computeStatus({
+    platforms,
+    xskRoot,
+    platformRoots: opts.platformRoots,
+    platformCommandsRoots: opts.platformCommandsRoots,
+  });
   let checkedManifests = 0;
   let invalidManifests = 0;
   let driftedManifests = 0;

package/lib/install.js

@@ -29,6 +29,42 @@ function rootFor(platform, platformRoots) {
   return adapter.skillsRoot();
 }
 
+function commandsRootFor(platform, platformCommandsRoots) {
+  if (platformCommandsRoots && platformCommandsRoots[platform]) {
+    return platformCommandsRoots[platform];
+  }
+  const adapter = require(`./adapters/${platform}.js`);
+  return typeof adapter.commandsRoot === 'function' ? adapter.commandsRoot() : null;
+}
+
+// A command file is a flat, markerless `.md` recorded in installed_paths whose
+// basename is not the skill file (`SKILL.md`) or the ownership marker. The
+// function set is basename-only in places, so ownership/classification keys on
+// the basename; membership under commandsRoot is the operational-semantics check.
+function isCommandFilePath(p) {
+  const base = path.basename(p);
+  return base !== 'SKILL.md' && base !== MARKER && base.endsWith('.md');
+}
+
+// opencode command body: the generated skill content (already carrying the
+// `description:` frontmatter) plus, when the content lacks `$ARGUMENTS`, a
+// skill-referring invocation section ending in a fenced `$ARGUMENTS` placeholder.
+function buildCommandFileContent(skillContent) {
+  if (skillContent.includes('$ARGUMENTS')) {
+    return skillContent;
+  }
+  const prefix = skillContent.endsWith('\n') ? skillContent : `${skillContent}\n`;
+  return (
+    `${prefix}\n` +
+    '## opencode invocation arguments\n\n' +
+    'Use these arguments when running the skill above:\n\n' +
+    '```text\n' +
+    '$ARGUMENTS\n' +
+    '```\n\n' +
+    'If no arguments were supplied, follow the default usage.\n'
+  );
+}
+
 function writeGeneratedFile(targetPath, content, label) {
   atomicWriteFile(targetPath, content, {
     dirLabel: `${label} dir`,
@@ -79,6 +115,7 @@ function previousInstallState(platform, xskRoot) {
     backupsByTarget: new Map(),
     installedDirs: new Set(),
     installedFiles: new Set(),
+    installedCommands: new Set(),
     installedHashesByTarget: new Map(),
   };
   let previous;
@@ -96,10 +133,11 @@ function previousInstallState(platform, xskRoot) {
   if (!validate(previous, { expectedPlatform: platform })) {
     throw new Error(`manifest for ${platform} failed shape validation; refusing to install`);
   }
+  const installedCommands = new Set(previous.installed_paths.filter(isCommandFilePath));
   const installedDirs = new Set(
     previous.installed_paths.filter((p) => {
       const base = path.basename(p);
-      return base !== 'SKILL.md' && base !== MARKER;
+      return base !== 'SKILL.md' && base !== MARKER && !isCommandFilePath(p);
     }),
   );
   const installedFiles = new Set(
@@ -110,6 +148,7 @@ function previousInstallState(platform, xskRoot) {
     backupsByTarget: new Map(previous.backups.map((b) => [b.target, { target: b.target, backup: b.backup }])),
     installedDirs,
     installedFiles,
+    installedCommands,
     installedHashesByTarget: new Map(installedHashes.map((h) => [h.target, h.sha256])),
   };
 }
@@ -232,7 +271,7 @@ function restorePathState(snapshot) {
   }
 }
 
-function capturePlatformSnapshot({ platform, skillsRoot, xskRoot, skills }) {
+function capturePlatformSnapshot({ platform, skillsRoot, commandsRoot, xskRoot, skills }) {
   const seen = new Set();
   const paths = [];
   const platformBackupDir = path.join(xskRoot, 'install', 'backups', platform);
@@ -256,6 +295,12 @@ function capturePlatformSnapshot({ platform, skillsRoot, xskRoot, skills }) {
     add(path.join(skillDir, MARKER));
     add(path.join(xskRoot, 'install', 'backups', platform, `${skill.name}.SKILL.md.bak`));
   }
+  if (commandsRoot) {
+    add(commandsRoot);
+    for (const skill of skills) {
+      add(path.join(commandsRoot, `${skill.name}.md`));
+    }
+  }
   // Cover the prior manifest's owned paths too, so an uninstall-first reset of
   // skills no longer in the install set can still be rolled back on failure.
   let prior = null;
@@ -267,12 +312,14 @@ function capturePlatformSnapshot({ platform, skillsRoot, xskRoot, skills }) {
   if (prior && typeof prior === 'object') {
     const priorPaths = Array.isArray(prior.installed_paths) ? prior.installed_paths : [];
     for (const p of priorPaths) {
-      if (!isInsideDir(p, skillsRoot)) {
+      const insideSkills = isInsideDir(p, skillsRoot);
+      const insideCommands = commandsRoot ? isInsideDir(p, commandsRoot) : false;
+      if (!insideSkills && !insideCommands) {
         continue;
       }
       add(p);
       const base = path.basename(p);
-      if (base === 'SKILL.md' || base === MARKER) {
+      if (insideSkills && (base === 'SKILL.md' || base === MARKER)) {
         add(path.dirname(p));
       }
     }
@@ -299,7 +346,7 @@ function restorePlatformSnapshot(snapshot) {
   }
 }
 
-function installPlatform({ platform, skillsRoot, xskRoot, version, skills }) {
+function installPlatform({ platform, skillsRoot, commandsRoot, xskRoot, version, skills }) {
   const manifest = create(platform, version);
   const installed = [];
   const backups = [];
@@ -314,6 +361,13 @@ function installPlatform({ platform, skillsRoot, xskRoot, version, skills }) {
 
   try {
     ensurePlatformRoot(skillsRoot);
+    if (commandsRoot) {
+      const commandsRootExisted = fs.existsSync(commandsRoot);
+      ensurePlatformRoot(commandsRoot);
+      if (!commandsRootExisted) {
+        createdThisRun.push(commandsRoot);
+      }
+    }
     for (const skill of skills) {
       const built = buildSkill(skill);
       const skillDir = path.join(skillsRoot, skill.name);
@@ -419,6 +473,36 @@ function installPlatform({ platform, skillsRoot, xskRoot, version, skills }) {
         assertReusableBackupRecord(backup, backupDir);
         backups.push({ target: backup.target, backup: backup.backup });
       }
+
+      if (commandsRoot) {
+        const commandFile = path.join(commandsRoot, `${skill.name}.md`);
+        const commandContent = buildCommandFileContent(built.content);
+        assertNotSymlink(commandFile, 'command file');
+        const commandFileExisted = fs.existsSync(commandFile);
+        if (commandFileExisted) {
+          const stat = fs.statSync(commandFile);
+          const existingCommandContent = fs.readFileSync(commandFile);
+          // Command files carry no ownership marker, so adoption rests solely on
+          // a hash match against the prior manifest: adopt a previously-installed
+          // generated command file, refuse a user-edited or unrecorded one.
+          const adoptable = isPreviouslyInstalledGeneratedContent({
+            existingContent: existingCommandContent,
+            builtContent: commandContent,
+            previousHash: installedHashesByTarget.get(commandFile),
+            wasInstalled: previousState.installedCommands.has(commandFile),
+          });
+          if (!adoptable) {
+            throw new Error(`refusing to overwrite user-edited command file: ${commandFile}`);
+          }
+          overwrittenThisRun.push({ target: commandFile, content: existingCommandContent, mode: stat.mode });
+        }
+        writeGeneratedFile(commandFile, commandContent, 'command file');
+        if (!commandFileExisted) {
+          createdThisRun.push(commandFile);
+        }
+        installed.push(commandFile);
+        installedHashes.push({ target: commandFile, sha256: contentSha256(commandContent) });
+      }
     }
 
     manifest.installed_paths = installed;
@@ -444,6 +528,7 @@ function install(options) {
   try {
     for (const platform of selectedPlatforms) {
       const skillsRoot = rootFor(platform, opts.platformRoots);
+      const commandsRoot = commandsRootFor(platform, opts.platformCommandsRoots);
       const applicable = skillsToInstall.filter((s) => s.platforms.includes(platform));
       if (applicable.length === 0) {
         summary.platforms[platform] = { platform, installed: [], backups: [], manifest: null, skipped: true };
@@ -452,7 +537,7 @@ function install(options) {
       // Snapshot the full platform state (including the prior manifest's owned
       // paths) before any mutation, so the uninstall-first reset and the
       // install roll back together on any failure.
-      const snapshot = capturePlatformSnapshot({ platform, skillsRoot, xskRoot, skills: applicable });
+      const snapshot = capturePlatformSnapshot({ platform, skillsRoot, commandsRoot, xskRoot, skills: applicable });
       snapshots.push(snapshot);
 
       // Uninstall-first: remove the prior owned state before regenerating, so a
@@ -463,7 +548,7 @@ function install(options) {
       // retained skill in place -- re-adopting a marker-less generated file, or
       // refusing to overwrite a user-edited owned skill (which rolls back). An
       // invalid prior manifest is the one case we refuse outright.
-      const reset = uninstallPlatform({ platform, xskRoot, skillsRoot });
+      const reset = uninstallPlatform({ platform, xskRoot, skillsRoot, commandsRoot });
       if (reset.invalid) {
         throw new Error(`refusing to reinstall ${platform}: existing manifest is invalid; uninstall or fix it first`);
       }
@@ -471,6 +556,7 @@ function install(options) {
       summary.platforms[platform] = installPlatform({
         platform,
         skillsRoot,
+        commandsRoot,
         xskRoot,
         version,
         skills: applicable,
@@ -490,6 +576,9 @@ module.exports = {
   installPlatform,
   atomicWriteFile,
   rootFor,
+  commandsRootFor,
+  isCommandFilePath,
+  buildCommandFileContent,
   PACKAGE_NAME,
   MARKER,
   ALL_PLATFORMS,

package/lib/manifest.js

@@ -83,15 +83,35 @@ function isInsideDir(child, parent) {
 function validateOperationalSemantics(options) {
   const opts = options || {};
   const skillsRoot = opts.skillsRoot;
+  // Optional second owned root for platforms (opencode) that install flat command
+  // files outside skillsRoot. Platforms without a commandsRoot stay skillsRoot-only.
+  const commandsRoot = opts.commandsRoot;
   const paths = Array.isArray(opts.manifest && opts.manifest.installed_paths) ? opts.manifest.installed_paths : [];
   for (const p of paths) {
-    if (!isInsideDir(p, skillsRoot)) {
+    const isCommandPath = isManifestCommandFilePath(p);
+    const insideSkills = isInsideDir(p, skillsRoot);
+    const insideCommands = commandsRoot ? isInsideDir(p, commandsRoot) : false;
+    if (isCommandPath) {
+      if (!commandsRoot) {
+        return { valid: false, reason: `command path requires commands root: ${p}` };
+      }
+      if (!insideCommands) {
+        return { valid: false, reason: `command path escapes commands root: ${p}` };
+      }
+      continue;
+    }
+    if (!insideSkills) {
       return { valid: false, reason: `installed path escapes platform root: ${p}` };
     }
   }
   return { valid: true };
 }
 
+function isManifestCommandFilePath(p) {
+  const base = path.basename(p);
+  return base !== 'SKILL.md' && base.endsWith('.md');
+}
+
 function copyInstalledHashes(records) {
   if (!Array.isArray(records)) {
     return [];

package/lib/skills.js

@@ -27,17 +27,31 @@ const skills = [
   {
     name: 'xsk-write-req',
     description:
-      'Turn plain-language needs into a grounded requirement document in requirements/, with a self-audit gate before it is finalized.',
+      'Turn plain-language needs into a grounded requirement document in .xsk/requirements/, with a self-audit gate before it is finalized.',
     platforms: ALL_PLATFORMS.slice(),
     fragmentBase: 'write-req',
   },
   {
     name: 'xsk-archive-req',
     description:
-      'Archive the active requirement document into requirements/archive/ and leave zero active docs.',
+      'Archive the active requirement document into .xsk/requirements/archive/ and leave zero active docs.',
     platforms: ALL_PLATFORMS.slice(),
     fragmentBase: 'archive-req',
   },
+  {
+    name: 'xsk-point',
+    description:
+      'Research one aspect into .xsk/points/ to a decision-complete landed plan using xsk-think discipline, then persist and manage it as a named point document.',
+    platforms: ALL_PLATFORMS.slice(),
+    fragmentBase: 'point',
+  },
+  {
+    name: 'xsk-consume-point',
+    description:
+      'Fold selected .xsk/points into one .xsk/requirements doc via xsk-write-req, archiving consumed points write-before-remove and leaving unconsumed points active.',
+    platforms: ALL_PLATFORMS.slice(),
+    fragmentBase: 'consume-point',
+  },
   {
     name: 'xsk-check',
     description: