Skip to content

繁體中文 | 简体中文 | English

awesome-agentic-ai-zh Style Guide

This is the single source of truth for the catalog: terminology, entry schema, license notation, writing style, banned words.

Read this before opening a PR. Maintainers will use this guide to review.

📋 Table of Contents

1. Project entry schema

Every project entry uses this structure:

### [Repo Name](https://github.com/owner/repo) ⭐⭐⭐⭐

| Field | Value |
|---|---|
| Language | Python |
| Stars | ★ 12k+ |
| License | MIT |
| Recommendation | ⭐⭐⭐⭐ |

**What it teaches**: 1-2 sentences on what this project teaches at this stage.

**Best for**: 1 sentence on who should study this and why.

**Notes**: 1-3 sentences of personal evaluation. What's strong, what's weak, what to skip. (Optional.)

**Run it**:
\`\`\`bash
# minimal install / first-run command
\`\`\`

Required fields (GitHub repo entry)

For entries that are real GitHub repos: - Stars (★ Xk+ format, no thousands separator) - License (SPDX ID or annotated exception, see 5) - Recommendation (⭐ × N, see 2) - What it teaches, Best for

Required fields (non-repo entry: article / course / video / protocol / documentation)

Some entries are blogs, videos, official docs, or catalog hubs — not GitHub repos. For these: - Recommendation (required) - What it teaches, Best for (required) - Format (required, e.g. Article / Video / Course / Curated list / Specification) - Stars / License may be omitted (no GitHub repo to attach)

Example: an Anthropic — Building Effective Agents blog entry uses Format = Article + Recommendation, without Stars or License.

Optional fields

  • Language — primary programming language (Python / TypeScript / Chinese)
  • Last update / Status — flag if stale or maintenance slowed
  • Notes, Run it

Heading conventions

  • Stages 1-4 / 6 use ### [Repo](url)
  • Stage 5 / 7 / branches use #### [Repo](url) (when there's a parent H3 category)
  • Suffix with stars allowed: ### [Repo](url) ⭐⭐⭐⭐⭐ or sub-label: ### [Repo](url) ⭐ Official

2. Recommendation star definitions

Stars Meaning When to use
⭐⭐⭐⭐⭐ Must-read / must-run Skipping this will get you stuck in this stage
⭐⭐⭐⭐ Highly recommended Strong material to deepen the topic
⭐⭐⭐ Solid example Worth running for cross-reference
⭐⭐ Useful reference Browse if interested
⭐ Niche / advanced / for completeness Most readers can skip

Rules: - A repo cited in different stages / branches should have the same rating (unless audience-specific reason, then note it explicitly) - Don't inflate stars to "look encouraging." Honesty > politeness - Commercial products (Cursor, LangSmith, etc.) follow the same scale

3. Banned words & alternatives

This document is Traditional Chinese (zh-TW, Taiwan). The Chinese-side guide enumerates the zh-Hans slips to avoid. For the English companion files, the rules are simpler:

📌 Language tag convention (BCP 47 / W3C i18n): this repo uses .zh-Hans.md (not .zh-CN.md) for the Simplified Chinese mirror. Hans / Hant are BCP 47 script subtags, decoupled from region — Simplified Chinese is also used in Singapore and Malaysia, not only mainland China, so Hans is more accurate than CN. The canonical README.md content is zh-Hant-TW (Traditional Chinese, Taiwan conventions), kept unsuffixed as GitHub's default landing page. Region distinctions can be added later as zh-Hans-CN / zh-Hant-HK etc. Thanks to @xfq (W3C i18n lead) for flagging this in #9.

Avoid overclaim phrases

Avoid Use instead
"the best in the world" / "industry's strongest" "comprehensive" / "well-known" / "widely-used"
"production-grade" (when describing teaching material) "teaching-oriented" / "material to learn production patterns from"
"the only choice" / "definitive" "a good option" / "an entry-level pick"
"the most urgent" / "the most important" (just drop the modifier)
"authoritative reference" (unless truly the official spec) "important reference implementation" / "official template"
"no problem" (re: legal/license) "check the terms before use" / "verify the terms yourself"

4. English nouns to keep

Technical writing has terms that read more naturally in English than translated:

  • LLM, API, SDK, MCP
  • agent, tool use, function calling, prompt, prompt caching
  • framework, library, repo, commit, PR, branch
  • RAG, embedding, vector DB, retrieval, chunk, token
  • streaming, async, batch, webhook
  • marketplace, plugin, skill, hook
  • production (when meaning "production environment") — but the catalog deliberately avoids it in many places (see Chinese 3)
  • hello-world, hands-on exercise — keep (zh-TW canonical uses 動手練習; en mirror translates as hands-on exercise(s))

Test: Would a technical reader pause at the translated form? If yes, keep English.

5. License notation conventions

Direct SPDX

  • MIT
  • Apache-2.0
  • BSD-3-Clause
  • GPL-3.0
  • LGPL-3.0

Annotated exceptions

Situation Notation
No SPDX upstream NOASSERTION (no SPDX upstream; check LICENSE before use)
AGPL (copyleft) AGPL-3.0 + Notes: AGPL-3.0 license (copyleft) — derivative products that ship modifications must follow the terms.
Custom non-commercial NOASSERTION (custom non-commercial) + Notes: License is a custom non-commercial term — read the original terms before use.
Multiple per-plugin NOASSERTION (each plugin has its own license; check per plugin)
Creative Commons CC-BY-4.0, CC-BY-NC-SA-4.0, etc.

Rule: Never read a license as legal advice. Don't say "fine for personal use." Say "read the original terms before use."

6. Stage page template

The same template applies to two locations: - stages/0X-*.md — shared foundations (0-2) + Track B (Stage 3-7) - tracks/cli/AX-*.md — Track A (A1-A3) sub-stages also follow this template, with a higher proportion of cross-links (most entries reference existing Stage 5 / 7 / cli-agents-guide content)

Every stage (except Stage 0) should have:

# Stage N — Topic

> **English** | [繁體中文](./0N-slug.md)

⏱ **Time estimate**: N-M weeks (~X-Y hours)

[1-2 sentence description of the stage's core question]

## 📌 Learning Goals
- bullet 1
- bullet 2

## 🚪 Entry Conditions (Stage 1+ only)
You should have:
- ...

## 📚 Required Reading
1. [Link](url) — description
2. ...

## 🛠 Hands-on Exercises (do them, not just read)

### Exercise N: Title
Description.

[3-5 hands-on exercise items]

## 🎯 Curated Projects

### [Project Name](url) ⭐⭐⭐⭐
[entry schema per 1]

[N entries]

## ✅ Self-Check Before Stage N+1
Can you:
- [ ] ...
- [ ] ...

If yes → proceed to Stage N+1.
If no → ...

## 💡 What's Next (optional, mostly used in the last stage)

Stage 0 exception: can omit Curated Projects and Entry Conditions — it's a prerequisite gateway.

7. Branch page template

# For [audience] — Specialized Branch

> **English** | [繁體中文](./for-X.md)

> [← Back to main path README](../README.en.md) · Branching from end of Stage 7

## Use Cases
- bullet 1
- bullet 2

## Curated Projects

### Sub-category 1
#### [Project](url) ⭐⭐⭐⭐
[entry]

### Sub-category 2
...

## Required Reading
1. ...

## Workflows To Master
- bullet 1
- bullet 2

Branch entries can be more concise than stage entries (full schema table optional), but link + stars + 1-2 sentence description is the minimum.

8. Writing style

Sentence length

  • Single sentence ≤ 25-30 words for English
  • Break long sentences into two
  • Don't force English rhythm into translated Chinese (or vice versa)

Voice

  • Prefer active: "Claude calls the tool" ✓
  • Avoid passive: "The tool is called by Claude" ✗

"You" vs "we"

  • "You" first — this is learner-facing material
  • "I" for author opinion: "I recommend ..."
  • Avoid "we" (unless real co-authors exist)

Connectives

  • Prefer simple: "but, so, because"
  • Avoid: "however, therefore, hence"
  • Between stages: relative path [Stage 4](04-agent-frameworks.en.md)
  • Branch ↔ README: [← Back to main path](../README.en.md)
  • Cross-stage repo references: full name + link, not just "as cited earlier"
  • GitHub repo: https://github.com/owner/repo (no trailing slash)
  • Article / blog: full URL, bold title
  • Commercial product (Cursor, Make.com, etc.): official URL, not affiliate

Link text conventions

  • Repo entry heading: [owner/repo](url) or [Project Name](url)
  • In-prose citation: [Repo Name](url) or \owner/repo`` (inline code for short references)
  • Avoid: "click here," "press this"

This style guide covers "how to write an entry." For design rationale — why these 5 branches, why 7 stages — see:

Modifying this guide

PRs to this guide are welcome. Open an Issue first to discuss — terminology decisions affect 100+ entries.

Current maintainer: @WenyuChiou.