claude-howto-zh-cn: Chinese Claude Code guide with a fixed learning order and localization validation

A localization of luongnv89/claude-howto that adds learning structure for Chinese beginners

luongnv89/claude-howto is an English guide to Claude Code covering slash commands, memory, skills, hooks, MCP, subagents and plugins. claude-howto-zh-cn forks that repository and rebuilds it for Chinese readers who have Claude Code installed but are stuck at three practical gaps: official documentation explains what each feature does but not how to combine them for real tasks; which feature to learn before another is unclear; and examples can be copied but not modified into custom workflows.

Addressing these gaps required restructuring explanations around learning order, comparing easily confused concepts (slash commands vs skills vs memory vs hooks vs plugins) and adding warnings for examples where a translated field silently breaks the command.

This is not an official Anthropic project. Its README states it is an unofficial Chinese localization fork, with source attribution and sync strategy in UPSTREAM.md. Users who want the original English version can follow the badge link to luongnv89/claude-howto directly.

Ten modules in a fixed sequence, with three entry points keyed to current experience

Content is organized into ten numbered modules. In the recommended order: 01-slash-commands, 02-memory, 08-checkpoints, 10-cli, 03-skills, 06-hooks, 05-mcp, 04-subagents, 09-advanced-features and 07-plugins. Directory numbers do not match the learning sequence; LEARNING-ROADMAP.md gives the correct order.

Three entry points are documented in the README table. Users who can only open Claude Code and chat start at 01-slash-commands, estimated at about 2.5 hours. Users who have worked with CLAUDE.md and a few commands start at 03-skills, estimated at about 3.5 hours. Users already working with hooks, MCP or subagents start at 09-advanced-features, estimated at about 5 hours.

CATALOG.md provides a full feature overview in table form, while QUICK_REFERENCE.md covers install commands, paths and common scenarios. Both are intended as lookups rather than sequential reading.

Copying the templates into a project: the quick-start commands and the minimum 1-hour setup

A 15-minute path for users who want to run something before reading the full guide is in the README. Replacing /path/to/your-project with the actual project path:

mkdir -p /path/to/your-project/.claude/commands
cp 01-slash-commands/optimize.md /path/to/your-project/.claude/commands/
cp 02-memory/project-CLAUDE.md /path/to/your-project/CLAUDE.md
mkdir -p ~/.claude/skills
cp -r 03-skills/code-review-specialist ~/.claude/skills/

This adds one slash command, one project-level memory file and one reusable skill. After the first copy, /optimize becomes callable in Claude Code.

For a minimum viable 1-hour configuration, the README extends the sequence:

cp 01-slash-commands/*.md .claude/commands/
cp 02-memory/project-CLAUDE.md ./CLAUDE.md
cp -r 03-skills/code-review-specialist ~/.claude/skills/

This variant copies all slash commands in the module and leaves hooks, MCP, subagents and plugins to a second session.

What the localization rule protects: eight categories that must stay in English

Eight categories are explicitly listed as never renamed for Chinese compatibility: directory names and file names, slash command names, skill/subagent/plugin names, YAML frontmatter keys, JSON/YAML keys, CLI flags and environment variable names, MCP server names, and executable content inside code blocks.

Phrased as a principle in the project: terminology stays accurate, explanations are localized in Chinese. A user reading Chinese text will encounter terms like skills, CLI, hooks, MCP and subagents untranslated, with a Chinese explanation on their first appearance. Translating those terms into Chinese words breaks the connection to the actual commands and official documentation.

LOCALIZATION-STYLE.md documents the full rules. UPSTREAM.md covers sync strategy. Both files are required reading before making further localization changes.

5 hook types control how hooks run; 31 hook events control when: the 2026-08-06 sync separated these two axes

A sync on 2026-08-06 included a specific clarification: 5 hook types determine how a hook runs, 31 hook events determine when it runs, and both the README and the CLAUDE.md now explicitly state these two dimensions are not the same classification axis. Before this sync, the guide followed upstream material that left this distinction implicit.

For anyone writing a hook, this matters in practice. Picking a type (for example pre-tool-use) determines execution mode. Picking an event (one of 31 possible triggers) determines the firing condition. Conflating them produced configurations where users chose the wrong event for a desired behavior by reasoning from the type instead.

That same sync removed the httpx and tenacity dependencies, unified Ruff at a consistent minimum, and moved EPUB Mermaid rendering from a remote Kroki service to a local mmdc installation, affecting the CI environment rather than the guide content.

validate_localization.py checks five categories; the EPUB builder requires local mmdc

Two scripts in the scripts/ directory support ongoing maintenance. A validation script checks five categories before each commit:

uv run python scripts/validate_localization.py

It verifies Markdown relative links, YAML frontmatter, JSON/YAML parsing, shell script syntax and the presence of key executable identifiers in their original form. Running it after any modification to examples is the documented practice, particularly when the modification touches content near translated text.

An EPUB builder generates an offline Chinese-language ebook:

uv run scripts/build_epub.py --lang zh

A working local mmdc (Mermaid CLI) installation is required. After the 2026-08-06 sync, all Mermaid rendering uses mmdc rather than the Kroki HTTP service; arm64 limitations are documented in scripts/README.md. pyproject.toml specifies jinja2 and pyyaml as the only runtime dependencies.

Unofficial status, China-specific friction points and upstream tracking as ongoing cost

Four obstacles specific to Chinese developers are documented: GitHub access, GitHub Token permissions, package manager environments (npm/npx/uv/Python path differences), and network or proxy configuration. Windows and WSL differences are covered too. None of these appear as general troubleshooting sections; each is a pre-emptive warning placed before the relevant example so the reader does not run into it mid-installation.

Upstream commits from luongnv89/claude-howto are tracked on an ongoing basis. UPSTREAM.md describes continuous tracking with incremental Chinese-side updates; the 2026-08-06 sync notes document the commit range (b9a973b to 4f3fa85) as the reference boundary. New upstream additions are not immediately available in this fork.

v1.0.0 was the initial tagged version, published on 2026-03-30 as the first Chinese localization. MIT-licensed; Python 3.10 or later is required for the scripts.

Editorial conclusion

claude-howto-zh-cn suits Chinese-speaking engineers who are running Claude Code but need a structured learning path rather than scattered feature references. The localization rule that preserves all executable identifiers in English is the core constraint to understand before customizing: renaming a YAML frontmatter key, a CLI flag or a skill directory name in a personal fork breaks examples without any obvious error. Two steps to verify before starting: check LEARNING-ROADMAP.md to find the right entry point, and run validate_localization.py after any modification to confirm that frontmatter, JSON/YAML and shell syntax remain intact.

Frequently asked questions

Official sources

1. Issues
2. lhfer/claude-howto-zh-cn on GitHub
3. License: MIT
4. README
5. Releases