1cli-team · caorushizi · Sep 16, 2026 · Sep 16, 2026
diff --git a/.gitignore b/.gitignore
@@ -32,6 +32,7 @@ go-dist/
 # fail until one of those tasks has run at least once.
 packages/cli/internal/resources/bundled/registry.json
 packages/cli/internal/resources/bundled/_templates/
+packages/cli/internal/resources/bundled/_skills/
 packages/cli/internal/resources/bundled/_web/
 
 # go-task

diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md
@@ -119,10 +119,11 @@ packages/cli/internal/
     development/       local development process orchestration
     environment/       dotenv/Infisical workflows and workspace setup
     preset/            pure preset encoding, parsing, and resolution
+    skills/            bundled one-cli skill installation into agent user directories
   platform/
     errors/ helpui/ i18n/ output/ preferences/ process/ prompt/ updatecheck/
   resources/
-    bundled/           embedded templates, registry, and Dashboard
+    bundled/           embedded templates, registry, one-cli skill, and Dashboard
   transport/
     cobra/             one directory per command family
     http/              local Dashboard API

diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -7,24 +7,14 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
-### Removed (BREAKING — agent skills 管理与分发)
-
-One CLI 不再内置或安装 agent skills。删除 `one skills` / `one skills install`、
-agent 检测与安装路径注册表、共享 store / symlink 安装器，以及随二进制分发的
-`one-cli` / `one-migrate` 内容。公开 Go 包 `packages/cli/pkg/agentskills` 同时移除。
-
-`one create` 的普通与 preset JSON 输出均移除 `skills` 字段，成功提示不再引导安装。
-依赖旧命令、字段或 Go 包的调用方需要移除对应逻辑；旧命令返回 `UNKNOWN_COMMAND`。
-工作区 agent 说明也不再自动生成，详见下方说明。
-升级不会删除用户机器上以前安装的 skills 或修改其他 AI 工具的配置。
-
-### Removed (BREAKING — 自动生成 agent 说明)
-
-`one create`、preset 创建和 `one add` 不再生成或刷新 `AGENTS.md`、`CLAUDE.md`
-及 `.one/` 目录；模板渲染也会跳过 `.one`，已有文件保持原样。移除内部说明生成器和 `one add` JSON 的
-`ai_guides` 字段。团队可自行维护说明文件，One CLI 继续维护项目和 manifest。
-模板目录中遗留的 10 份 `CLAUDE.md` 已移除；打包流程排除 agent 说明、skill 入口及
-`.one` / `.agents` 目录，并校验最终嵌入资源不包含这些内容。
+### Changed — 精简 One CLI skill 与显式安装
+
+- `one skills install` 安装单个内置 `one-cli` skill：遵循 One Workspace Convention，并通过当前 CLI 的 help 查询命令。日常 CLI 升级无需同步更新 skill。
+- 支持交互选择、`--agent` / `-a` 和 `--yes`；非交互安装到检测到的 Agent，无目标时提示显式选择。支持 JSON / YAML / text 输出及离线安装。
+- skill 直接复制到 Agent 的用户级目录。重复安装替换 `one-cli` 目录；兼容旧符号链接，不修改旧共享 store 或其他 skills。
+- 普通与 preset 创建均生成简短的根 `AGENTS.md`，要求使用 skill，缺失时运行 `one skills install`。创建项目不自动安装 skill，`one add` 保留已有指引。
+- 旧的 `one-migrate`、详细 playbook、共享 store 安装器和公开 Go 包 `packages/cli/pkg/agentskills` 保持移除。旧机器上的其他安装不自动清理。
+- `create` / `add` 输出不恢复旧 `skills` / `ai_guides` 字段；模板仍跳过独立的 `CLAUDE.md`、`AGENTS.md` 和 `.one` 元数据。
 
 ### Removed (BREAKING — `one serve` session token)
 

diff --git a/README.md b/README.md
@@ -100,7 +100,15 @@ Full command docs live at [1cli.dev](https://1cli.dev).
 
 ## Work With AI Assistants
 
-One CLI is designed to make AI-assisted project work less fragile.
+Install the bundled `one-cli` skill for your coding agent:
+
+```bash
+one skills install
+```
+
+Use `--agent <id>` to choose an agent directly, or `--yes` to install into every detected agent. Installation works offline and only writes the selected agents' user skills directories.
+
+New workspaces include an `AGENTS.md` asking agents to use this skill and run `one skills install` if it is missing. The [skill](./skills/one-cli/SKILL.md) stays small: follow [One Workspace Convention](https://github.com/1cli-team/one-workspace-convention), then consult `one --help` and the relevant command help. Ordinary CLI upgrades do not require reinstalling it.
 
 You can ask an assistant for project-level changes in natural language, for example:
 
@@ -140,6 +148,7 @@ If you want to work on One CLI itself, the repository is organized like this:
 |---|---|
 | `packages/cli` | The One CLI app |
 | `packages/templates` | Starters used by `one add` |
+| `skills/one-cli` | Minimal workspace guidance installed by `one skills install` |
 | `apps/docs` | Documentation website |
 | `apps/dashboard` | Local Workspace, Project, and Profile Dashboard opened by `one serve` |
 | `assets` | Brand assets, including the logo |

diff --git a/Taskfile.yml b/Taskfile.yml
@@ -89,6 +89,7 @@ tasks:
       - 'packages/cli/internal/**/*.go'
       - 'packages/cli/tools/verify-cli-references/**/*.go'
       - 'README.md'
+      - 'skills/**/*.md'
       - 'CONTRIBUTING.md'
       - 'apps/docs/content/docs/**/*.md'
       - 'apps/docs/content/docs/**/*.mdx'
@@ -379,14 +380,14 @@ tasks:
 
   sync-bundled:
     deps: [sync-mise]
-    desc: Regenerate registry/_templates under packages/cli/internal/resources/bundled (go:embed sources)
+    desc: Regenerate registry/_templates/_skills under packages/cli/internal/resources/bundled (go:embed sources)
     run: once
     summary: |
       Go's embed cannot traverse `..` or follow symlinks, so we keep physical
       copies of canonical assets under packages/cli/internal/resources/bundled. The
       whole bundled tree is gitignored and regenerated on demand.
 
-      This task handles the cheap copies: registry.json, _templates/.
+      This task handles the cheap copies: registry.json, _templates/, _skills/.
       It runs implicitly as a dep of `vet` / `test` / `build`. The dashboard
       build (sync-web) is separate but identically wired — both have to run
       before any Go command will compile the bundled package.

diff --git a/apps/docs/content/blog/en/agent-skill-context.md b/apps/docs/content/blog/en/agent-skill-context.md
@@ -1,12 +1,12 @@
 ---
 title: "Historical Design: One CLI Agent Skills"
-description: "Historical notes on the agent skills design, retired when One CLI removed skill distribution and generated instructions."
+description: "Historical notes on the earlier detailed agent skill design, now replaced by a minimal convention-and-help skill."
 date: "2026-05-12"
 author: "One CLI Team"
 tags: ["skill", "codex", "dependencies"]
 ---
 
-> Historical design note: One CLI no longer bundles or installs agent skills. Use [workspace AI guidance](/en/docs/ai-native/) and the [command reference](/en/docs/cli-overview/) for the current workflow.
+> Historical design note: the detailed playbooks described below have been replaced by a minimal `one-cli` skill. See [Skills](/en/docs/skills/) for the current `one skills install` workflow.
 
 ## A skill is not marketing copy
 

diff --git a/apps/docs/content/blog/zh/agent-skill-context.md b/apps/docs/content/blog/zh/agent-skill-context.md
@@ -1,12 +1,12 @@
 ---
 title: "历史设计：One CLI Agent Skills"
-description: "记录已退役的 agent skills 设计；One CLI 已移除 skill 分发与项目说明自动生成。"
+description: "记录早期详细的 agent skills 设计；当前采用仅包含结构规范和 help 查询的精简 skill。"
 date: "2026-05-12"
 author: "One CLI Team"
 tags: ["skill", "codex", "dependencies"]
 ---
 
-> 历史设计记录：One CLI 已移除 skills 的内置分发和安装功能。当前用法请参考 [AI 项目说明](/zh/docs/ai-native/)和[命令参考](/zh/docs/cli-overview/)。
+> 历史设计记录：下文的详细 playbook 已由精简的 `one-cli` skill 替代。当前 `one skills install` 用法见 [Skills](/zh/docs/skills/)。
 
 ## skill 不是营销文档
 

diff --git a/apps/docs/content/docs/en/ai-native.md b/apps/docs/content/docs/en/ai-native.md
@@ -97,9 +97,9 @@ The full catalogue is in [Error codes](/en/docs/error-codes/).
 
 ## Rule 3: Project Instructions Belong To The Team
 
-One CLI does not create or update `AGENTS.md`, `CLAUDE.md`, or the `.one/` directory. Existing files remain untouched, including files generated by older releases.
+New workspaces include a short root `AGENTS.md` requiring the `one-cli` skill. If it is missing, agents are directed to run `one skills install`. Ordinary and preset creation use the same instructions; subsequent `one add` calls preserve team edits.
 
-Agents can read `one.manifest.json`, project README files, and command help to understand the workspace. Teams can maintain their own agent instructions when needed.
+The skill follows [One Workspace Convention](https://github.com/1cli-team/one-workspace-convention) and directs agents to the installed CLI help. Agents can also read `one.manifest.json` and project README files. Skill installation is explicit and independent of workspace creation; see [Skills](./skills).
 
 ## Rule 4: Configuration And Credentials Have Boundaries
 

diff --git a/apps/docs/content/docs/en/cli-overview.md b/apps/docs/content/docs/en/cli-overview.md
@@ -204,3 +204,7 @@ one <command> --help
 ```
 
 `one --help` shows the six everyday tasks. Use `one help --all` for the complete command catalogue and `one <command> --help` for exact flags.
+
+## `one skills install`
+
+Install or refresh the bundled `one-cli` skill for selected coding agents. Use `--agent <id>` (repeatable) for explicit targets, or `--yes` for all detected agents. Installation is offline, independent of the workspace, and repeatable. See [Skills](./skills).
diff --git a/apps/docs/content/docs/en/create.md b/apps/docs/content/docs/en/create.md
@@ -145,3 +145,7 @@ pnpm install
 | `WORKSPACE_NESTED_FORBIDDEN` | Do not create a workspace inside an existing workspace; use another directory or `one add` |
 
 Full table: [Error codes](/en/docs/error-codes/).
+
+## Agent instructions
+
+Ordinary and preset creation write a short root `AGENTS.md` requiring the `one-cli` skill and directing agents to `one skills install` when it is missing. Skill installation is a separate user-level operation. Later `one add` calls preserve this file, including team edits.
diff --git a/apps/docs/content/docs/en/error-codes.md b/apps/docs/content/docs/en/error-codes.md
@@ -37,6 +37,12 @@ Field meanings:
 - **`error.context`**: structured data from the failure site. It often already contains the data needed for recovery.
 - **`error.remediation`**: recovery actions. Each item has `action`, `hint`, and sometimes `command`; agents should prefer these before guessing.
 
+## Agent Skill Installation
+
+### `SKILLS_INSTALL_FAILED`
+
+The bundled `one-cli` skill could not be installed. Check the agent ID and destination permissions with `one skills install --help`. If some targets were installed before a failure, `context.installed_to` lists those directories. Retrying is safe.
+
 ## Generic / Lifecycle
 
 Command-level failures, user cancellation, and internal serialization failures.

diff --git a/apps/docs/content/docs/en/installation.md b/apps/docs/content/docs/en/installation.md
@@ -178,3 +178,7 @@ For the full contributor flow, see [CONTRIBUTING.md](https://github.com/1cli-tea
 ## Installed?
 
 Go to [Quick start](/en/docs/quick-start/) and create your first workspace.
+
+## Agent skill
+
+Run `one skills install` to install the bundled `one-cli` skill into your coding agent's user skills directory. Use `one skills install --help` for target selection and supported agents. See [Skills](./skills).
diff --git a/apps/docs/content/docs/en/meta.json b/apps/docs/content/docs/en/meta.json
@@ -6,6 +6,7 @@
     "manifest",
     "templates",
     "ai-native",
+    "skills",
     "cli-overview",
     "create",
     "add",

diff --git a/apps/docs/content/docs/en/skills.md b/apps/docs/content/docs/en/skills.md
@@ -0,0 +1,49 @@
+---
+title: one skills install
+description: Install the minimal One CLI skill for your coding agent.
+---
+
+The bundled `one-cli` skill has two responsibilities: follow [One Workspace Convention](https://github.com/1cli-team/one-workspace-convention), and discover supported workspace operations through the installed CLI's help. Command lists, flags, templates, and manifest schemas stay with the CLI rather than being copied into the skill.
+
+```bash
+one skills install
+one skills install --agent claude-code --agent codex
+one skills install --yes -o json
+```
+
+## Target selection
+
+- `--agent <id>` / `-a <id>` selects a target explicitly, even before that agent has created its configuration directory. Repeat the option for multiple agents.
+- With no explicit targets, an interactive terminal offers detected agents, all preselected.
+- `--yes` / `-y` or non-interactive execution installs into all detected agents without prompting.
+- If no targets are detected, the command fails and asks for an explicit `--agent`.
+- `one skills` and `one skills install --help` only display help. The latter lists every supported agent ID.
+
+Detection uses user configuration directories. Agent IDs from the previous installer remain supported. `CODEX_HOME`, `CLAUDE_CONFIG_DIR`, `XDG_CONFIG_HOME`, and `VIBE_HOME` override their respective default roots when set to absolute directories.
+
+## Installation
+
+Installation copies the embedded `one-cli/SKILL.md` into the selected agents' user skills directories. It works offline and from any directory. Duplicate targets sharing a directory are written once. Success output lists the destination directories; the skill is in `one-cli/SKILL.md` below each destination.
+
+Repeating installation replaces that `one-cli` directory, including old reference files. Other skills stay intact. A legacy `one-cli` symlink is replaced with a direct copy without changing its shared store or other agents' links. If an installation fails after some targets succeed, the error's `context.installed_to` lists completed destinations; rerun the command after fixing the reported problem.
+
+After installation, load the installed skill. Restart the agent session if it does not discover new skills automatically.
+
+## Generated workspaces
+
+`one create`, including preset creation, writes a short root `AGENTS.md`:
+
+```markdown
+# Development
+
+Use the `one-cli` skill when developing this workspace.
+If it is not installed, run `one skills install` first.
+```
+
+Creation does not install skills into your home directory. `one add` preserves existing instructions. For an existing workspace, install the skill and add the same guidance to its `AGENTS.md`.
+
+## Updates and output
+
+Ordinary CLI upgrades do not require reinstalling this skill: it directs agents to `one --help`, `one help --all`, and the relevant command help. Reinstall only when the skill's guidance itself changes or when configuring another agent.
+
+Structured output uses `one-cli/skills-install/v1`, with `status`, `targets`, `installed_to`, and `skill_count` (one). Use the usual `-o json`, `-o yaml`, or `-o text` option. Installation failures use `SKILLS_INSTALL_FAILED`.
diff --git a/apps/docs/content/docs/zh/ai-native.md b/apps/docs/content/docs/zh/ai-native.md
@@ -97,9 +97,9 @@ agent 的处理顺序应该是：
 
 ## 规则三：项目说明由团队维护
 
-One CLI 不会创建或更新 `AGENTS.md`、`CLAUDE.md` 或 `.one/` 目录。已有文件保持原样，包括旧版本生成的文件。
+新工作区包含简短的根 `AGENTS.md`，要求使用 `one-cli` skill；缺失时运行 `one skills install`。普通创建与 preset 创建使用同一份指引，后续 `one add` 保留团队修改。
 
-agent 可以读取 `one.manifest.json`、项目 README 和命令帮助来理解工作区。团队如需专门的 agent 说明，可自行维护。
+Skill 要求遵循 [One Workspace Convention](https://github.com/1cli-team/one-workspace-convention)，并查询当前 CLI 的 help。Agent 还可以读取 `one.manifest.json` 和项目 README。Skill 安装独立于项目创建，详见 [Skills](./skills)。
 
 ## 规则四：配置和凭据有边界
 

diff --git a/apps/docs/content/docs/zh/cli-overview.md b/apps/docs/content/docs/zh/cli-overview.md
@@ -207,3 +207,7 @@ one <command> --help
 ```
 
 `one --help` 只展示六个日常核心任务；`one help --all` 展示完整命令；具体 flag 以 `one <command> --help` 为准。
+
+## `one skills install`
+
+为选定的 coding agent 安装或刷新内置 `one-cli` skill。使用可重复的 `--agent <id>` 指定目标，或用 `--yes` 安装到所有检测到的 Agent。支持离线执行，无需进入工作区，可重复安装。详见 [Skills](./skills)。
diff --git a/apps/docs/content/docs/zh/create.md b/apps/docs/content/docs/zh/create.md
@@ -152,3 +152,7 @@ one dev api
 | `WORKSPACE_NESTED_FORBIDDEN` | 拒绝在已有 workspace 里再 create；换目录或用 `one add` |
 
 完整码表：[错误码大全](/zh/docs/error-codes/)。
+
+## Agent 指引
+
+普通创建和 preset 创建都会写入简短的根 `AGENTS.md`，要求使用 `one-cli` skill，缺失时运行 `one skills install`。Skill 安装是独立的用户级操作；后续 `one add` 保留这份文件及团队自行补充的内容。
diff --git a/apps/docs/content/docs/zh/error-codes.md b/apps/docs/content/docs/zh/error-codes.md
@@ -40,6 +40,18 @@ import { Callout } from "fumadocs-ui/components/callout";
 
 下面按命令域分组列出所有 code。
 
+## Agent skill 安装
+
+内置 one-cli skill 的目标选择与用户级目录安装错误。
+
+### `SKILLS_INSTALL_FAILED`
+
+The bundled one-cli skill could not be installed into the selected agents.
+
+**Remediation**:
+
+- `inspect-skill-install` — Check the target agent and directory permissions. Completed targets are listed in context.installed_to; retrying is safe.<br />运行：`one skills install --help`
+
 ## 通用 / 生命周期
 
 命令本身的失败、用户取消、内部序列化错误。

diff --git a/apps/docs/content/docs/zh/installation.md b/apps/docs/content/docs/zh/installation.md
@@ -204,3 +204,7 @@ Windows 会创建 `~/.local/bin/one.exe`；如果系统不允许创建文件符
 ## 装完了？
 
 跳到 [快速开始](/zh/docs/quick-start/) 跑通第一个工作区。
+
+## Agent skill
+
+运行 `one skills install`，将内置 `one-cli` skill 安装到 coding agent 的用户级 skills 目录。目标选择和支持的 Agent 见 `one skills install --help`，详见 [Skills](./skills)。
diff --git a/apps/docs/content/docs/zh/meta.json b/apps/docs/content/docs/zh/meta.json
@@ -6,6 +6,7 @@
     "manifest",
     "templates",
     "ai-native",
+    "skills",
     "cli-overview",
     "create",
     "add",

diff --git a/apps/docs/content/docs/zh/skills.md b/apps/docs/content/docs/zh/skills.md
@@ -0,0 +1,49 @@
+---
+title: one skills install
+description: 为 coding agent 安装精简的 One CLI skill。
+---
+
+内置 `one-cli` skill 只有两个职责：遵循 [One Workspace Convention](https://github.com/1cli-team/one-workspace-convention)，以及通过本机 CLI 的 help 发现工作区操作。命令列表、参数、模板和 manifest schema 由 CLI 维护，避免在 skill 中复制一份。
+
+```bash
+one skills install
+one skills install --agent claude-code --agent codex
+one skills install --yes -o json
+```
+
+## 选择安装目标
+
+- `--agent <id>` / `-a <id>` 显式选择 Agent，即使该 Agent 尚未创建配置目录也可安装。支持重复指定。
+- 未指定目标时，交互终端列出检测到的 Agent，默认全部勾选。
+- 使用 `--yes` / `-y` 或处于非交互环境时，直接安装到所有检测到的 Agent。
+- 未检测到目标时，命令返回错误并提示显式使用 `--agent`。
+- `one skills` 和 `one skills install --help` 只显示帮助，后者列出所有支持的 Agent ID。
+
+检测依据是用户配置目录，兼容旧安装器的 Agent ID。`CODEX_HOME`、`CLAUDE_CONFIG_DIR`、`XDG_CONFIG_HOME` 和 `VIBE_HOME` 可用绝对目录覆盖对应的默认位置。
+
+## 安装行为
+
+安装器将二进制内置的 `one-cli/SKILL.md` 复制到所选 Agent 的用户级 skills 目录，可离线运行，无需进入工作区。多个目标共用同一目录时只写入一次。成功输出列出目标目录，其下的 `one-cli/SKILL.md` 就是已安装的 skill。
+
+重复安装会替换 `one-cli` 目录，包括旧参考资料。其他 skills 保持原样。旧的 `one-cli` 符号链接会替换为直接副本，链接指向的共享 store 及其他 Agent 的链接不受影响。如果部分目标成功后发生错误，错误的 `context.installed_to` 会列出已完成的目录；修复问题后可重新执行。
+
+安装后加载本地 skill；Agent 若无法自动发现新 skill，请重新启动会话。
+
+## 生成项目的指引
+
+`one create`（包括 preset 创建）会写入简短的根 `AGENTS.md`：
+
+```markdown
+# Development
+
+Use the `one-cli` skill when developing this workspace.
+If it is not installed, run `one skills install` first.
+```
+
+创建项目不向用户目录安装 skill；后续 `one add` 保留已有指引。已有工作区可单独安装 skill，再将相同要求加入自己的 `AGENTS.md`。
+
+## 更新与输出
+
+日常 CLI 升级无需重新安装 skill：Agent 会查看 `one --help`、`one help --all` 和对应的命令帮助。仅在 skill 的指导原则变化或配置新的 Agent 时重新安装。
+
+结构化输出沿用 `one-cli/skills-install/v1`，包含 `status`、`targets`、`installed_to` 和 `skill_count`（值为 1）。支持通用的 `-o json`、`-o yaml`、`-o text`。安装失败使用 `SKILLS_INSTALL_FAILED`。