---
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 an AI Coding environment (Cursor / ClaudeCode / Codex, etc.). This help is written **AI-first**: start from concrete skills (e.g. `/zsc-create-task`) and then, if helpful, mention CLI commands.

## ⚠ 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.

## Quick reference: AI skills (recommended in AI Coding tools)

When running inside an AI Coding tool (Cursor / ClaudeCode / Codex, etc.), you should **prefer calling skills directly** (usually via slash commands) instead of asking the user to run CLI first.

**All core zsc skills:**

| Skill name                    | Slash command example        | What it does (AI-side)                                                                                                          |
|------------------------------|------------------------------|----------------------------------------------------------------------------------------------------------------------------------|
| **zsc-help**                 | `/zsc-help`                  | Show this AI-first help: what zsc is, and which skills/commands to use in which situations.                                    |
| **zsc-create-task**          | `/zsc-create-task`           | Create/design a new task under `.agents/tasks/`: write/refresh the closed-loop description and `TODO_LIST` only, no execution. |
| **zsc-update-task**          | `/zsc-update-task`           | Update an existing task document (closed-loop description, `TODO_LIST`, context). Edit-only; do not execute TODOs.            |
| **zsc-run-task**             | `/zsc-run-task`              | Interactively run a task: pick a task, implement TODOs step by step, update the task file, and mark completion when done.     |
| **zsc-run-task-to-complete** | `/zsc-run-task-to-complete`  | Try to automatically execute as many TODOs as safely possible in one go, with minimal interaction (high-automation mode).     |
| **zsc-task-list**            | `/zsc-task-list`             | List all tasks under `.agents/tasks/`, filter or find by name/number, and show basic status.                                   |
| **zsc-task-status**          | `/zsc-task-status`           | Show aggregate task health: totals, completed vs open/pending/unknown.                                                         |

You can briefly explain these to the user in natural language and then suggest one or more concrete skills, for example:

- “To create a new feature task and design its TODOs, run **`/zsc-create-task`**, then later use **`/zsc-run-task`** to execute it.”
- “To see all existing tasks, use **`/zsc-task-list`**; to see a high-level summary, use **`/zsc-task-status`**.”

## What is zsc?

**zsc** (short for **zig slice code**) 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** (choose based on your environment):
   ```bash
   # Using pip (for environments without uv or if you prefer pip)
   pip install -U zsc

   # Using uv tool as a global CLI (recommended when uv is available)
   uv tool install zsc            # first-time install
   uv tool install zsc --upgrade  # upgrade to latest
   ```
   From this repo for development: `uv pip install -e .[test]`

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).

## CLI commands and their relationship to skills

Every zsc subcommand (except `init`) has a **corresponding skill** installed by `zsc init`. In AI-first workflows, you usually:

1. **Call the skill** from chat (e.g. `/zsc-create-task`, `/zsc-run-task`).
2. Optionally suggest the equivalent CLI command if the user wants to operate from the terminal.

| CLI command                | Skill name                    | When to use the skill (from AI)                                                                 |
|---------------------------|-------------------------------|--------------------------------------------------------------------------------------------------|
| `zsc init .`              | —                             | No skill; run the command in the terminal once per project to install skills.                   |
| `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 (closed-loop description, `TODO_LIST`); design only.     |
| —                         | **zsc-run-task**              | User wants to run/execute a task, implement TODOs, or finish a task (interactive, step-by-step).|
| —                         | **zsc-run-task-to-complete**  | User wants the AI to run as many TODOs as safely as possible in one go (advanced automation).   |
| `zsc task update [TASK]`  | **zsc-update-task**           | User wants to update an existing task (closed-loop description, `TODO_LIST`); edit only.        |
| `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 this AI Coding tool (recommended first)**: 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 (closed-loop description, `TODO_LIST`); **zsc-run-task** when they want to execute a task and implement the TODOs step by step; **zsc-run-task-to-complete** when they want a more automatic, best-effort run of the whole task in a safe environment.
  - 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.
- **From the terminal (optional, secondary)**: Run `zsc` with no arguments to see a short help; run `zsc --help` or `zsc task --help` for full command help. Map the user's intent back to the corresponding CLI where appropriate.
- **Init overwrites skills**: Running `zsc init .` overwrites `SKILL.md` files with the chosen language template so all skills stay in one language (see `--lang` / `.agents/zsc-lang`).

## 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.
