---
name: zsc-help
description: Skill for introducing zsc and its usage to the user. Use when the user asks what zsc is, how to use zsc, how to use zsc skills, or wants an overview of zsc commands and the corresponding AI skills.
---

# zsc-help

Use this skill when the user needs an introduction to **zsc** or wants to understand how to use zsc and its skills in the AI Coding environment.

## ⚠ Scope boundary (mandatory, highest priority)

**Whenever this skill is used, regardless of the user's prompt:** This skill is for **introduction and suggestions only**. You may not create or modify any project files. You may only describe zsc, suggest commands (e.g. `zsc task list`), and suggest which skill to use (e.g. zsc-create-task, zsc-run-task). Do not create tasks, edit task files, or change any code.

## What is zsc?

**zsc** is a CLI tool for initializing and managing a unified AI Agents task system in a project:

- It creates and maintains the **`.agents/`** and **`.agents/tasks/`** directory structure.
- It installs **zsc-* skills** into the current AI Coding tool (e.g. Cursor, Codex, ClaudeCode) so that the LLM can help with task creation, listing, and status.

## Installation and first-time setup

1. **Install zsc** (e.g. with uv):
   ```bash
   uv add zsc
   ```
   Or from this repo for development: `uv pip install -e .`

2. **Initialize the project** (run from project root):
   ```bash
   zsc init .
   ```
   This will:
   - Create `.agents/` and `.agents/tasks/` if missing.
   - Create skills directories for the current tool (e.g. `.cursor/skills/`, `.codex/skills/`, `.claudecode/skills/`).
   - Install all zsc-* skills (only when the target file does not exist; existing files are not overwritten).

## Commands and corresponding skills

Every zsc subcommand (except `init`) has a **corresponding skill** installed by `zsc init`. The LLM can use that skill when the user wants to do the same thing from the chat.

| CLI command           | Skill name        | When to use the skill |
|-----------------------|-------------------|------------------------|
| `zsc init .`           | —                 | No skill; run the command. |
| `zsc task list`        | **zsc-task-list** | User wants to see all tasks, find a task, or know open vs completed. |
| `zsc task new NAME`   | **zsc-create-task**  | User wants to create or design a task (闭环描述, TODO_LIST); design only, no execution. |
| —                     | **zsc-run-task**  | User wants to run/execute a task, implement TODOs, or finish a task. |
| `zsc task update [TASK]` | **zsc-update-task** | User wants to update an existing task (闭环描述, TODO_LIST); edit only, no execution. |
| `zsc task status`     | **zsc-task-status** | User wants a summary (counts: total, completed, open) or “task health”. |
| —                     | **zsc-help**      | User asks what zsc is or how to use zsc/skills (this skill). |

## How to suggest usage to the user

- **From the terminal**: Run `zsc` with no arguments to see a short help; run `zsc --help` or `zsc task --help` for full command help.
- **From this AI Coding tool**: Tell the user they can:
  - Use **zsc-help** (e.g. in Cursor: `/zsc-help`) to get this introduction again.
  - Use **zsc-create-task** when creating or designing a task; **zsc-update-task** when updating an existing task's content (闭环描述, TODO_LIST); **zsc-run-task** when they want to execute a task and implement the TODOs.
  - Use **zsc-task-list** when they want to list or find tasks.
  - Use **zsc-task-status** when they want a quick summary of task counts/health.
- **Idempotent init**: Running `zsc init .` again does not overwrite existing skill files; it only adds missing ones.

## Optional: run CLI for the user

When the user wants to list tasks or see status, you can suggest they run in the project root:

- `zsc task list`   — list all tasks with status
- `zsc task status` — show total / completed / open counts

When they want to create a new task:

- `zsc task new <feat_name>` — creates `task_{no}_{feat_name}/` and `task_{no}_{feat_name}.md` template; use **zsc-create-task** to design 闭环描述 and TODO_LIST.

When they want to update an existing task (refresh 闭环描述, TODO_LIST):

- `zsc task update [TASK]` — show task file path; use **zsc-update-task** (e.g. `/zsc-update-task` in Cursor) to edit the task document only.

When they want to run/execute a task:

- Use **zsc-run-task** (e.g. `/zsc-run-task` in Cursor): pick the task, implement TODOs step by step, update the task file, and mark completion when done.
