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

# zsc-help

当用户需要了解 **zsc** 或希望在 AI 编程环境中理解 zsc 及其技能用法时使用本技能。**回复请使用中文。**

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

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

## zsc 是什么？

**zsc** 是一个在项目中初始化并管理统一 AI Agents 任务体系的 CLI 工具：

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

## 安装与首次配置

1. **安装 zsc**（例如使用 uv）：
   ```bash
   uv add zsc
   ```
   或在本仓库开发时：`uv pip install -e .`

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

## 命令与对应技能

除 `init` 外，每个 zsc 子命令都有由 `zsc init` 安装的**对应技能**，用户从对话中希望做同样的事时，可调用该技能。

| CLI 命令            | 技能名           | 何时使用该技能                         |
|---------------------|------------------|----------------------------------------|
| `zsc init .`        | —                | 无对应技能；直接运行命令。             |
| `zsc task list`     | **zsc-task-list** | 用户想查看任务列表、按名称/编号找任务、区分进行中与已完成。 |
| `zsc task new NAME` | **zsc-create-task** | 用户想创建或设计任务（闭环描述、TODO_LIST）；仅设计，不执行。 |
| —                   | **zsc-run-task** | 用户想运行/执行任务、实现 TODO 或完成任务。 |
| `zsc task update [TASK]` | **zsc-update-task** | 用户想更新已有任务（闭环描述、TODO_LIST 等）；仅编辑，不执行。 |
| `zsc task status`   | **zsc-task-status** | 用户想要汇总（总数、已完成、进行中）或「任务健康度」。 |
| —                   | **zsc-help**     | 用户问 zsc 是什么或如何使用 zsc/技能（本技能）。 |

## 如何向用户建议用法

- **在终端**：无参数运行 `zsc` 可看简短帮助；`zsc --help` 或 `zsc task --help` 查看完整命令。
- **在本 AI 编程工具中**：可告知用户：
  - 使用 **zsc-help**（例如在 Cursor 中 `/zsc-help`）再次查看本介绍。
  - 创建或设计任务时使用 **zsc-create-task**；更新已有任务内容（闭环描述、TODO_LIST）时使用 **zsc-update-task**；要执行任务、实现 TODO 时使用 **zsc-run-task**。
  - 想列出或查找任务时使用 **zsc-task-list**。
  - 想快速看任务数量/健康度时使用 **zsc-task-status**。
- **幂等初始化**：再次运行 `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、更新任务文件，完成后执行完成步骤。
