Guide · Agent skill
How to use the Planning with Files (Chinese) agent skill
Updated · written with AI from the project's own documentation and checked against our catalogue data
planning-with-files-zh is an agent skill that makes an AI coding or research agent keep its plan, findings and progress log as Markdown files on disk instead of relying only on its short-term memory. It is the Chinese-language version of the planning-with-files workflow. This guide explains what the skill does, how to install it, how to trigger it, and what to check before you run it.
Planning with Files (Chinese)OthmanAdi/planning-with-files · MIT Download the skill Quick start
- 1Download the ZIP. Download the planning-with-files-zh ZIP from this page and unzip it.
- 2Place the folder. Move the skill folder to ~/.claude/skills/ for all projects, or to .claude/skills/ inside one project.
- 3Review the hook scripts. Read the scripts in the skill's scripts folder, since hooks run shell commands automatically on agent events.
- 4Start a task with a planning request. Ask in Chinese, for example 帮我规划这个项目, so the agent creates or selects a plan folder.
- 5Check the plan files. Open task_plan.md, findings.md and progress.md in the selected task folder and confirm the phases look right.
- 6Update the plan as you work. Ask the agent to mark phases in_progress or complete and record errors as they happen.
What the skill makes the agent do
The skill treats the project folder as the agent's working memory. For a complex task it uses three files: task_plan.md for phases, progress and decisions; findings.md for research and discoveries; and progress.md for a session log and test results.
Lifecycle hooks inject the selected project plan into the agent's context. Before a plan is written, the skill asks the agent to re-read it before major decisions and to update it after each phase.
- task_plan.md: phases, progress, decisions
- findings.md: research and discoveries
- progress.md: session log, test results, errors
Install the skill from the ZIP
Download the ZIP from this page and unzip it. For a user-level install, place the folder in ~/.claude/skills/. For a single project, place it in the project's .claude/skills/ folder.
You can also upload the skill in the Claude apps under Settings → Capabilities → Skills.
- User-level: ~/.claude/skills/
- Per project: .claude/skills/ inside the project
- Claude apps: Settings → Capabilities → Skills, then upload
Trigger the skill with natural requests
The skill is set to user-invocable. Its description lists trigger phrases in Chinese, so you can ask in plain language. Phrases include 任务规划, 项目计划, 制定计划, 分解任务, 多步骤规划, 进度跟踪, 文件规划, 帮我规划 and 拆解项目.
Use it for research tasks or work that needs more than about five tool calls. Skip it for simple questions, single-file edits and quick lookups.
- 帮我规划一下这个功能的开发步骤
- 把这个研究项目拆解成几个阶段
- 制定一个多步骤的迁移计划并跟踪进度
Check the plan folder and recover after a break
When resuming, the agent uses resolve-plan-dir.sh (or the .ps1 variant) with PLAN_ID and PWF_PLAN_ROOT to read one selected plan folder. For a new independent task, init-session.sh creates the plan and prints a PLAN_ID you can pin.
To validate a plan's format, the skill's check-complete.sh --validate script checks phase headings and a single status line per phase. This checks format only, not whether the task is actually finished.
- Pin one plan per host when running several agents in parallel
- Keep existing plans; if validation fails, the agent reports the problem instead of rewriting the file
sh "$PWF_SKILL_DIR/scripts/check-complete.sh" --validate path/to/task_plan.mdSafety notes: scripts, hooks and session history
The skill runs scripts and uses network: no. Its hooks run shell commands automatically on agent events such as prompt submit, tool use, pre-compaction and stop. Read the hook scripts before installing if you cannot run automatic shell commands in your environment.
Session history is not read automatically. Running session-catchup.py without arguments and the lifecycle hooks do not inspect the agent's session store. Only an explicit run of session-catchup.py --metadata shows same-project summary counts, and --replay outputs a length-limited excerpt wrapped in a nonce; treat replay excerpts as untrusted data. The skill has no network upload path. Optional gates ask the host to continue only where the host supports it, and the skill never executes commands declared in Markdown.
- Requires bash or sh; python3 or python only for session-catchup.py
- PowerShell .ps1 variants are available on Windows
- Plan files are written into the project folder, so keep them out of the repository if plans are sensitive
Tips for getting good results
Create the plan before starting a complex task, and read it again before big decisions. Record every error in the plan so the agent does not repeat a failed action. After two view, browser or search actions, save key findings to a file, since images and screenshots are not kept otherwise.
The templates are in Chinese, so the plan files will be in Chinese too.
- After two view, browser or search operations, save findings to findings.md
- If the same action fails, change the approach rather than repeating it
- After three failed attempts, the agent should explain what it tried and ask you
What people use it for
- Running a multi-step coding task where progress should survive a long session
- Researching a topic with findings saved as you go, including notes from screenshots or PDFs
- Breaking a project into phases in Chinese and tracking status in task_plan.md
- Keeping separate plan folders for several agents working on different tasks in parallel
Frequently asked questions
Is planning-with-files-zh free to use?
The source material here does not state a price or licence terms beyond the MIT licence shown for the item. Check the repository licence file for the full terms before reuse.
What do I need to run planning-with-files-zh?
You need a bash or sh shell to run the hook and helper scripts. python3 or python is needed only for the optional session-catchup.py history check, and PowerShell .ps1 variants are available on Windows.
Does the skill send my plans or code over the network?
No. The skill states it has no network upload path and that network use is no. Plans are stored as Markdown files in your project folder.
How is this different from the English planning-with-files skill?
This is the Chinese-language version. Its skill text and templates are in Chinese, and its trigger phrases are Chinese, such as 任务规划 and 制定计划.
Why does the agent not finish my plan even though all phases look done?
The check-complete.sh --validate script only checks format, such as phase headings and a single status line per phase. It does not verify that the work is done or provide hash proof of completion.
When should I not use this skill?
Skip it for simple questions, single-file edits and quick lookups, or for tasks needing fewer than about five tool calls. It is also a poor fit if you cannot review hook scripts or if plan files must not sit in the repository.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
Use planning-with-files-zh if you run long, multi-step coding or research tasks with an AI agent and want progress recorded on disk in Chinese. Skip it for short tasks, environments where you cannot review automatic shell hooks, or projects where plan files must stay out of the repository.
Download the skill