---
name: zsc-help
description: 用于向用户介绍 zsc 及其用法的技能。当用户询问 zsc 是什么、如何使用 zsc、如何使用 zsc 技能，或需要 zsc 命令与对应 AI 技能概览时使用。回复请使用中文。
---

# zsc-help

当用户需要了解 **zsc** 或希望在 AI 编程环境中（Cursor / ClaudeCode / Codex 等）理解 zsc 及其技能用法时使用本技能。**本帮助以 AI First 为原则：优先介绍具体技能命令（如 `/zsc-create-task`），再补充命令行。回复请使用中文。**

## ⚠ 操作边界（强制，最高优先级）

**只要使用了本技能，无论用户提示词说什么：** 本技能**仅用于介绍与建议**。不得创建或修改项目内任何文件。只能介绍 zsc、建议运行哪些命令（如 `zsc task list`）、以及建议使用哪些技能（如 zsc-create-task、zsc-run-task）。不得创建任务、编辑任务文件或修改任何代码。

## 快速速查：AI 技能一览（在 AI 工具中优先使用）

在 AI 编程工具（Cursor / ClaudeCode / Codex 等）里，**应优先直接调用技能**（通常是输入斜杠命令）来完成任务，而不是先要求用户手动跑 CLI。

**zsc 所有核心技能：**

| 技能名                        | 典型斜杠命令示例          | 主要作用（在 AI 侧）                                                                                 |
|-----------------------------|---------------------------|------------------------------------------------------------------------------------------------------|
| **zsc-help**                | `/zsc-help`               | 展示本 AI First 帮助：介绍 zsc 是什么，以及各技能/命令在什么场景下使用。                            |
| **zsc-create-task**         | `/zsc-create-task`        | 在 `.agents/tasks/` 下创建/设计新任务：编写/刷新闭环描述与 `TODO_LIST`，只设计不执行。              |
| **zsc-update-task**         | `/zsc-update-task`        | 更新已有任务文档（闭环描述、`TODO_LIST`、上下文等），只编辑任务设计，不真正执行 TODO。             |
| **zsc-run-task**            | `/zsc-run-task`           | 交互式运行任务：选择任务、逐步实现 TODO、更新任务文件，完成后标记为 Done。                        |
| **zsc-run-task-to-complete**| `/zsc-run-task-to-complete` | 在安全前提下，尽量一口气自动执行尽可能多的 TODO，减少中途交互（高自动化模式）。                   |
| **zsc-task-list**           | `/zsc-task-list`          | 列出 `.agents/tasks/` 下所有任务，可按名称/编号查找，并查看基础状态。                              |
| **zsc-task-status**         | `/zsc-task-status`        | 查看任务整体健康度：总数、已完成 vs 未完成/未知 等统计。                                           |

你可以先用简洁中文向用户解释，再给出一个或多个具体技能建议，例如：

- 「想为一个新功能创建任务并设计 TODO，可以先用 **`/zsc-create-task`** 设计，再用 **`/zsc-run-task`** 来执行。」
- 「想看当前有哪些任务，可以用 **`/zsc-task-list`**；想看整体完成度，可以用 **`/zsc-task-status`**。」

## zsc 是什么？

**zsc**（全称 **zig slice code**）是一个在项目中初始化并管理统一 AI Agents 任务体系的 CLI 工具：

- 创建并维护 **`.agents/`** 与 **`.agents/tasks/`** 目录结构。
- 将 **zsc-* 技能** 安装到当前 AI 编程工具（如 Cursor、Codex、ClaudeCode）中，便于 LLM 协助任务创建、列表与状态查看。

## 安装与首次配置

1. **安装 zsc**（根据环境选择其一）：
   ```bash
   # 使用 pip（适用于未安装 uv 或习惯用 pip 的环境）
   pip install -U zsc

   # 使用 uv tool 作为全局工具（已安装 uv 时推荐）
   uv tool install zsc            # 首次安装
   uv tool install zsc --upgrade  # 升级到最新版本
   ```
   在本仓库开发时，可使用本地可编辑安装：`uv pip install -e .[test]`

2. **在项目根目录初始化**：
   ```bash
   zsc init .
   ```
   将会：
   - 若不存在则创建 `.agents/` 与 `.agents/tasks/`。
   - 为当前工具创建技能目录（如 `.cursor/skills/`、`.codex/skills/`、`.claudecode/skills/`）。
   - 安装全部 zsc-* 技能（仅当目标文件不存在时写入，不覆盖已有文件）。
   - 首次运行时会提示选择技能提示语言（中文/English）。

## CLI 命令与技能之间的关系

除 `init` 外，每个 zsc 子命令都有由 `zsc init` 安装的**对应技能**。在 AI First 流程下，一般是：

1. **先在对话里调用技能**（如 `/zsc-create-task`、`/zsc-run-task`）完成主要工作；
2. 如果用户偏好终端或需要脚本化，再补充说明对应的 CLI 命令。

| CLI 命令                  | 技能名                       | 从 AI 侧何时使用该技能                                         |
|---------------------------|------------------------------|----------------------------------------------------------------|
| `zsc init .`              | —                            | 无对应技能；建议用户在项目中至少运行一次以安装技能。           |
| `zsc task list`           | **zsc-task-list**            | 用户想查看任务列表、按名称/编号找任务、区分进行中与已完成。    |
| `zsc task new NAME`       | **zsc-create-task**          | 用户想创建或设计任务（闭环描述、`TODO_LIST`）；仅设计不执行。 |
| —                         | **zsc-run-task**             | 用户想运行/执行任务、实现 TODO 或完成任务（交互式、逐步执行）。|
| —                         | **zsc-run-task-to-complete** | 用户希望在安全前提下尽量一口气自动跑完整个任务的 TODO（高自动化）。 |
| `zsc task update [TASK]`  | **zsc-update-task**          | 用户想更新已有任务（闭环描述、`TODO_LIST` 等）；仅编辑不执行。|
| `zsc task status`         | **zsc-task-status**          | 用户想要汇总（总数、已完成、进行中）或「任务健康度」。        |
| —                         | **zsc-help**                 | 用户问 zsc 是什么或如何使用 zsc/技能（本技能）。               |

## 如何向用户建议用法

- **在本 AI 编程工具中（优先推荐）**：可告知用户：
  - 使用 **zsc-help**（例如在 Cursor 中 `/zsc-help`）再次查看本介绍。
  - 创建或设计任务时使用 **zsc-create-task**；更新已有任务内容（闭环描述、`TODO_LIST`）时使用 **zsc-update-task**；要按步骤执行任务、实现 TODO 时使用 **zsc-run-task**；在安全环境中希望尽量一口气自动跑完整个任务时，可考虑使用 **zsc-run-task-to-complete**。
  - 想列出或查找任务时使用 **zsc-task-list**。
  - 想快速看任务数量/健康度时使用 **zsc-task-status**。
- **在终端（可选，其次）**：无参数运行 `zsc` 可看简短帮助；`zsc --help` 或 `zsc task --help` 查看完整命令。必要时再向用户解释 CLI 与技能的对应关系。
- **幂等初始化**：再次运行 `zsc init .` 不会覆盖已有技能文件，只会补全缺失项。

## 可选：代用户执行 CLI

当用户想列出任务或查看状态时，可建议在项目根目录执行：

- `zsc task list`   — 列出所有任务及状态
- `zsc task status` — 显示总数 / 已完成 / 进行中

当用户想创建新任务时：

- `zsc task new <feat_name>` — 创建 `task_{no}_{feat_name}/` 及同名 `task_{no}_{feat_name}.md` 模板；用 **zsc-create-task** 设计闭环描述与 TODO_LIST。

当用户想更新已有任务（刷新闭环描述、TODO_LIST）时：

- `zsc task update [TASK]` — 显示任务文件路径；使用 **zsc-update-task**（如 Cursor 中 `/zsc-update-task`）仅编辑任务文档。

当用户想运行/执行任务时：

- 使用 **zsc-run-task**（如 Cursor 中 `/zsc-run-task`）：选定任务、按步实现 TODO、更新任务文件，完成后执行完成步骤。
