# Main Components of the zhangxuefeng-skill Codebase: A Complete Architecture Guide > Explore the zhangxuefeng-skill codebase. Understand its six core components: manifest, docs, knowledge base, examples, assets, and license. Get a complete architecture guide. - Repository: [花叔/zhangxuefeng-skill](https://github.com/alchaincyf/zhangxuefeng-skill) - Tags: architecture - Published: 2026-06-27 --- **The zhangxuefeng-skill repository is organized as a self-contained skill package containing six logical components: a YAML skill manifest, core documentation, a six-file knowledge base, example interactions, visual assets, and an MIT license.** The **zhangxuefeng-skill** codebase is a portable, data-driven skill package designed for Agent-Skills-compatible runtimes. Hosted at `alchaincyf/zhangxuefeng-skill`, this repository embodies Zhang Xuefeng's decision-making perspective through a structured architecture that separates metadata, documentation, and factual knowledge. ## Component Architecture Overview The repository follows a strict separation of concerns across six distinct layers. Each component serves a specific function in the skill's lifecycle, from runtime registration to conversation generation. The six core components are: - **Skill Manifest** ([`SKILL.md`](https://github.com/alchaincyf/zhangxuefeng-skill/blob/main/SKILL.md)) – Declares skill identity and activation triggers - **Core Documentation** ([`README.md`](https://github.com/alchaincyf/zhangxuefeng-skill/blob/main/README.md)) – User guides and mental model descriptions - **Knowledge Base** (`references/research/`) – Factual research and interview transcripts - **Example Interaction** ([`examples/demo-conversation.md`](https://github.com/alchaincyf/zhangxuefeng-skill/blob/main/examples/demo-conversation.md)) – Demonstration conversations - **Visual Assets** (`assets/`) – Visual branding materials - **License** (`LICENSE`) – Legal reuse terms ## The Six Core Components ### Skill Manifest (SKILL.md) The **Skill Manifest** serves as the YAML front-matter that registers the skill with any compatible runtime. Located at [`SKILL.md`](https://github.com/alchaincyf/zhangxuefeng-skill/blob/main/SKILL.md) (lines 1-10), this file declares the skill as `zhangxuefeng-perspective` and defines auto-activation triggers such as "用张雪峰的视角". The manifest also encodes the **回答工作流** (answer workflow), specifying that the skill performs web searches and applies mental models like **社会筛子论** (social filter theory) and **选择 > 努力** (choice over effort) when generating responses. ### Core Documentation (README.md) The **Core Documentation** in [`README.md`](https://github.com/alchaincyf/zhangxuefeng-skill/blob/main/README.md) (lines 3-31, 80-130) provides human-readable installation instructions and high-level design explanations. This component explains the skill's purpose and showcases example dialogues. Critical installation commands are documented here: ```bash # Install the skill using the npx skills CLI npx skills add alchaincyf/zhangxuefeng-skill ``` The README also catalogues the mental models that the skill references during decision analysis, including employment-rate projections and salary benchmarks. ### Knowledge Base (references/research/) The **Knowledge Base** consists of six markdown files containing distilled writings, interview transcripts, and analytical frameworks. These read-only resources fuel the skill's factual answers. The runtime does not execute code against these files; they are static references accessed during the "Step 2: 张雪峰式研究" phase of the workflow. The six research files are: 1. [`references/research/01-writings.md`](https://github.com/alchaincyf/zhangxuefeng-skill/blob/main/references/research/01-writings.md) – Core writings and essays 2. [`references/research/02-conversations.md`](https://github.com/alchaincyf/zhangxuefeng-skill/blob/main/references/research/02-conversations.md) – Interview transcripts 3. [`references/research/03-expression-dna.md`](https://github.com/alchaincyf/zhangxuefeng-skill/blob/main/references/research/03-expression-dna.md) – Linguistic patterns and expression DNA 4. [`references/research/04-external-views.md`](https://github.com/alchaincyf/zhangxuefeng-skill/blob/main/references/research/04-external-views.md) – External critiques and perspectives 5. [`references/research/05-decisions.md`](https://github.com/alchaincyf/zhangxuefeng-skill/blob/main/references/research/05-decisions.md) – Decision analysis frameworks 6. [`references/research/06-timeline.md`](https://github.com/alchaincyf/zhangxuefeng-skill/blob/main/references/research/06-timeline.md) – Historical timeline and career trajectory data ### Example Interaction (examples/demo-conversation.md) The **Example Interaction** component demonstrates concrete behavior through a full turn-by-turn chat. Located at [`examples/demo-conversation.md`](https://github.com/alchaincyf/zhangxuefeng-skill/blob/main/examples/demo-conversation.md), this file shows how the skill performs role-playing, data lookup, and deterministic-style output. Developers use this file as a test case to verify that the skill loads correctly and produces the expected "张雪峰式" (Zhang Xuefeng-style) analysis format. ### Visual Assets (assets/) The **Assets** directory contains visual materials used by the README and optional UI front-ends. The primary file, `assets/hero.gif`, provides the hero animation displayed on the repository's front page. These components are purely cosmetic but improve the onboarding experience. ### License (LICENSE) The **License** component at `LICENSE` provides the legal framework for reuse. The repository operates under the MIT license, permitting free modification and redistribution of the skill package. ## How the Components Work Together The zhangxuefeng-skill operates as a **data-driven pipeline** that connects these components in sequence: 1. **Runtime Registration** – The Agent-Skills-compatible runtime parses [`SKILL.md`](https://github.com/alchaincyf/zhangxuefeng-skill/blob/main/SKILL.md) to register the skill and load activation triggers. 2. **User Onboarding** – Developers reference [`README.md`](https://github.com/alchaincyf/zhangxuefeng-skill/blob/main/README.md) for installation (`npx skills add`) and mental model descriptions. 3. **Knowledge Retrieval** – Upon activation, the skill accesses the `references/research/` directory to fetch employment statistics, salary data, and decision frameworks. 4. **Response Generation** – The skill generates answers using the workflow defined in [`SKILL.md`](https://github.com/alchaincyf/zhangxuefeng-skill/blob/main/SKILL.md), referencing the knowledge base to produce analyses like "2026年计算机专业的就业率是92%，中位数年薪15万". ## Installation and Usage Deploying the skill requires only the manifest and knowledge base components. Execute the installation via the skills CLI: ```bash # Install the skill (single-line installer works on any supported runtime) npx skills add alchaincyf/zhangxuefeng-skill ``` After installation, activate the skill by typing a trigger phrase in any supported agent (Claude Code, Codex, Cursor, etc.): ```text 用张雪峰的视角帮我分析一下计算机专业的前景 ``` The runtime automatically handles the web-search step and knowledge-base lookup as described in the "Step 2: 张雪峰式研究" section of [`SKILL.md`](https://github.com/alchaincyf/zhangxuefeng-skill/blob/main/SKILL.md). ## Summary - **zhangxuefeng-skill** is a self-contained skill package with six logical components structured for Agent-Skills compatibility. - **[`SKILL.md`](https://github.com/alchaincyf/zhangxuefeng-skill/blob/main/SKILL.md)** acts as the YAML manifest that registers the skill and defines activation triggers and the answer workflow. - **[`README.md`](https://github.com/alchaincyf/zhangxuefeng-skill/blob/main/README.md)** provides installation instructions (`npx skills add`) and documents mental models like **社会筛子论**. - **`references/research/`** contains six markdown files (01-writings through 06-timeline) that serve as the read-only knowledge base. - **[`examples/demo-conversation.md`](https://github.com/alchaincyf/zhangxuefeng-skill/blob/main/examples/demo-conversation.md)** demonstrates expected skill behavior for testing purposes. - **`assets/hero.gif`** and **`LICENSE`** complete the package with visual branding and MIT licensing terms. ## Frequently Asked Questions ### What is the purpose of the SKILL.md file? [`SKILL.md`](https://github.com/alchaincyf/zhangxuefeng-skill/blob/main/SKILL.md) serves as the **skill manifest** that declares the package as `zhangxuefeng-perspective` to any Agent-Skills-compatible runtime. It contains YAML front-matter defining activation triggers (e.g., "用张雪峰的视角") and specifies the multi-step answer workflow that combines web search with knowledge-base retrieval. ### How does the knowledge base differ from the README? The **README.md** provides human-readable documentation and installation instructions, while the **knowledge base** (`references/research/`) contains six specialized markdown files with factual data, interview transcripts, and decision frameworks. The runtime reads the knowledge base during execution but treats these files as static resources rather than executable code. ### Can I modify the research files without breaking the skill? Yes. The knowledge base files ([`01-writings.md`](https://github.com/alchaincyf/zhangxuefeng-skill/blob/main/01-writings.md) through [`06-timeline.md`](https://github.com/alchaincyf/zhangxuefeng-skill/blob/main/06-timeline.md)) are **read-only resources** referenced by the skill during its "Step 2: 张雪峰式研究" phase. Modifying these files updates the factual data available to the skill without altering the execution logic defined in [`SKILL.md`](https://github.com/alchaincyf/zhangxuefeng-skill/blob/main/SKILL.md), provided the YAML structure remains intact. ### What runtime environments support this skill package? The zhangxuefeng-skill package is compatible with any **Agent-Skills-compatible runtime**, including Claude Code, Codex, and Cursor. The `npx skills add alchaincyf/zhangxuefeng-skill` command works across all supported environments, parsing the [`SKILL.md`](https://github.com/alchaincyf/zhangxuefeng-skill/blob/main/SKILL.md) manifest to register the skill and its activation triggers automatically.