# How to Contribute to the alchaincyf/zhangxuefeng-skill Project: A Complete Guide

> Learn how to contribute to the alchaincyf/zhangxuefeng-skill project by editing markdown files and submitting a GitHub Pull Request. No build steps needed.

- Repository: [花叔/zhangxuefeng-skill](https://github.com/alchaincyf/zhangxuefeng-skill)
- Tags: how-to-guide
- Published: 2026-06-27

---

**Contributing to the alchaincyf/zhangxuefeng-skill project involves editing markdown files—primarily [`SKILL.md`](https://github.com/alchaincyf/zhangxuefeng-skill/blob/main/SKILL.md), documents in `references/research/`, and [`examples/demo-conversation.md`](https://github.com/alchaincyf/zhangxuefeng-skill/blob/main/examples/demo-conversation.md)—to add new mind-models, decision heuristics, or research sources, then submitting a standard GitHub Pull Request with no build steps required.**

The alchaincyf/zhangxuefeng-skill repository is a self-contained Agent-Skills package compatible with any runtime supporting the Agent Skills protocol. Because the entire skill is implemented as pure markdown and YAML, you can contribute to the alchaincyf/zhangxuefeng-skill project without writing compiled code or managing complex dependencies. This guide walks through the repository architecture, contribution areas, and the exact workflow to get your changes merged.

## Understanding the Repository Architecture

The skill follows a flat file structure where all logic and content lives in text files that require no compilation.

### Core Components

The repository is organized around three primary artifacts:

- **[`SKILL.md`](https://github.com/alchaincyf/zhangxuefeng-skill/blob/main/SKILL.md)** – The runtime-consumed manifest containing front-matter (`name`, `description`), role-play rules, and the answer workflow. According to the source code, this file defines the deterministic three-step process (classification → research → response) at lines 48-52, which forces the agent to fetch fresh data before replying to factual queries.
- **`references/research/`** – A directory of markdown files containing primary sources, interview transcripts, and factual backing material. Every claim in the skill must reference a file here.
- **[`examples/demo-conversation.md`](https://github.com/alchaincyf/zhangxuefeng-skill/blob/main/examples/demo-conversation.md)** – Sample dialogues demonstrating the skill in action, linked from the README under "效果示例" at lines 35-38.

### The Agentic Workflow Constraint

All contributions must respect the **three-step Agentic workflow** defined in [`SKILL.md`](https://github.com/alchaincyf/zhangxuefeng-skill/blob/main/SKILL.md):

1. **Classification** – Parse the user intent.
2. **Research** – Perform a web search for factual queries (mandatory before answering).
3. **Response** – Generate the reply using the retrieved data.

If you add any new mind-model that answers concrete questions, you must explicitly state in the model's description that the agent must first perform a web search, as enforced by the workflow at [`SKILL.md`](https://github.com/alchaincyf/zhangxuefeng-skill/blob/main/SKILL.md) lines 48-52.

## Contribution Areas

You can improve the skill by working in these specific domains:

### Add New Mind-Models

Define fresh cognitive models (e.g., "AI-Resilience") with a one-sentence summary, evidence citations, and usage notes. Append these to the `## 核心心智模型` section in [`SKILL.md`](https://github.com/alchaincyf/zhangxuefeng-skill/blob/main/SKILL.md).

### Define Decision Heuristics

Propose concise rules-of-thumb (e.g., "技术栈兼容性检验") describing when to apply them. Add these as bullets to the **"8条决策启发式"** list located at lines 95-102 of [`SKILL.md`](https://github.com/alchaincyf/zhangxuefeng-skill/blob/main/SKILL.md).

### Expand Research Sources

Contribute new primary sources (interview transcripts, blog posts) that back existing models. Create a new markdown file under `references/research/` and reference it from the model's *证据* block using relative GitHub URLs (e.g., [`/blob/main/references/research/07-interview-2024.md`](https://github.com/alchaincyf/zhangxuefeng-skill/blob/main//blob/main/references/research/07-interview-2024.md)).

### Create Example Dialogues

Show the skill handling new question types (e.g., "AI 产业的未来"). Add Q&A blocks to [`examples/demo-conversation.md`](https://github.com/alchaincyf/zhangxuefeng-skill/blob/main/examples/demo-conversation.md) to demonstrate the three-step workflow in action.

### Documentation and Localization

Clarify installation steps or translate the skill. Fork [`SKILL.md`](https://github.com/alchaincyf/zhangxuefeng-skill/blob/main/SKILL.md) into a new file (e.g., [`SKILL.en.md`](https://github.com/alchaincyf/zhangxuefeng-skill/blob/main/SKILL.en.md)) and update the front-matter, or edit [`README.md`](https://github.com/alchaincyf/zhangxuefeng-skill/blob/main/README.md) directly.

## Step-by-Step Contribution Guide

Follow this standard Git workflow to submit changes:

1. **Fork and clone** the repository.

   ```bash
   git clone https://github.com/<your-username>/zhangxuefeng-skill.git
   cd zhangxuefeng-skill
   ```

2. **Create a descriptive branch**.

   ```bash
   git checkout -b feature/add-ai-resilience-model
   ```

3. **Edit the appropriate files** using the existing GitHub-flavored markdown style. Keep the front-matter of [`SKILL.md`](https://github.com/alchaincyf/zhangxuefeng-skill/blob/main/SKILL.md) unchanged unless renaming the skill. When adding research sources, cite them with markdown links pointing to the raw file in the repo.

4. **Run a sanity check** by rendering the markdown locally to verify formatting. The repository provides no automated tests, but you can validate syntax by installing the skill locally: `npx skills add ./` from the clone directory.

5. **Commit with a clear message**.

   ```bash
   git add SKILL.md references/research/07-interview-2024.md
   git commit -m "Add 'AI-Resilience' mind-model with supporting interview"
   ```

6. **Push and open a Pull Request** against `main`. Fill the PR template describing the purpose and any required runtime changes, then request review from the maintainers.

7. **Address review feedback** and merge once approved.

## Practical Contribution Examples

### Example 1: Adding a Decision Heuristic

Insert a new bullet under the "8条决策启发式" list in [`SKILL.md`](https://github.com/alchaincyf/zhangxuefeng-skill/blob/main/SKILL.md) (lines 95-102):

```markdown
- **「AI‑Resilience」检验**：评估一个岗位在未来 5‑10 年内被 AI 替代的风险。  
  - **何时使用**：用户询问 “AI 会不会抢走这份工作？”  
  - **做法**：先搜索「<岗位> AI 替代率 2026」获取最新统计；若风险 > 30% → 建议转型或提升硬技能。  

```

### Example 2: Adding a Research Source

Create [`references/research/07-interview-2024.md`](https://github.com/alchaincyf/zhangxuefeng-skill/blob/main/references/research/07-interview-2024.md):

```markdown

# 2024 年访谈 – 张雪峰谈 AI 与教育

- **来源**：B 站直播，2024‑03‑15  
- **要点**  
  - AI 只能替代 “低端编码”，而系统设计、架构仍需人类。  
  - 推荐“计算机+AI”双轨学习路径。  
- **引用**：在模型“就业倒推法”中加入 “AI‑Resilience 检验” 时使用此访谈作为证据。

```

Then update the model in [`SKILL.md`](https://github.com/alchaincyf/zhangxuefeng-skill/blob/main/SKILL.md):

```markdown
**证据**：  
- …  
- [2024 访谈 – AI 与教育](/blob/main/references/research/07-interview-2024.md)

```

### Example 3: Adding a Demo Conversation

Append to [`examples/demo-conversation.md`](https://github.com/alchaincyf/zhangxuefeng-skill/blob/main/examples/demo-conversation.md):

```markdown
**用户**: 我想知道 AI 方向的专业还能不能报？  
**张雪峰**: 先问你分数、省份、家里背景。你是哪儿的，几分？  
**张雪峰**: 你家没有矿，我跟你说 AI 方向现在就业率 68%，而且 AI‑Resilience 检验显示 2028‑2030 年会有 35% 的岗位被模型覆盖。  
**张雪峰**: 建议选计算机+AI 双专业，或者去 985 以上的学校找 AI 实验室做项目。  

```

## Key Files Every Contributor Should Know

| File | Purpose | Direct Link |
|------|---------|-------------|
| **[`README.md`](https://github.com/alchaincyf/zhangxuefeng-skill/blob/main/README.md)** | High-level description, installation commands (`npx skills add ...`), and quick-start guide. | [`/blob/main/README.md`](https://github.com/alchaincyf/zhangxuefeng-skill/blob/main//blob/main/README.md) |
| **[`SKILL.md`](https://github.com/alchaincyf/zhangxuefeng-skill/blob/main/SKILL.md)** | Runtime manifest containing the skill manifest, workflow, mind-models, and expression DNA. | [`/blob/main/SKILL.md`](https://github.com/alchaincyf/zhangxuefeng-skill/blob/main//blob/main/SKILL.md) |
| **`references/research/*.md`** | Primary research material backing every claim. | `/tree/main/references/research` |
| **[`examples/demo-conversation.md`](https://github.com/alchaincyf/zhangxuefeng-skill/blob/main/examples/demo-conversation.md)** | Real-world dialog snippets for testing and documentation. | [`/blob/main/examples/demo-conversation.md`](https://github.com/alchaincyf/zhangxuefeng-skill/blob/main//blob/main/examples/demo-conversation.md) |

## Summary

- **No code compilation required**: The alchaincyf/zhangxuefeng-skill project uses pure markdown and YAML, making contributions accessible to anyone comfortable with text editing.
- **Respect the three-step workflow**: All factual answers must follow the classification → research → response pattern, with mandatory web search for concrete questions.
- **Edit [`SKILL.md`](https://github.com/alchaincyf/zhangxuefeng-skill/blob/main/SKILL.md) for logic**: Add mind-models to `## 核心心智模型` and heuristics to the "8条决策启发式" list at lines 95-102.

- **Back claims with sources**: Place primary research in `references/research/` and cite using `/blob/main/` paths.
- **Demonstrate with examples**: Add tested conversation flows to [`examples/demo-conversation.md`](https://github.com/alchaincyf/zhangxuefeng-skill/blob/main/examples/demo-conversation.md) to show the skill handling new scenarios.

## Frequently Asked Questions

### Do I need to write code to contribute to alchaincyf/zhangxuefeng-skill?

No. Because the skill is a pure markdown package interpreted by Agent Skills runtimes, you only need to edit text files. **All contributions are text-based**—whether adding a new mind-model to [`SKILL.md`](https://github.com/alchaincyf/zhangxuefeng-skill/blob/main/SKILL.md), uploading research to `references/research/`, or expanding [`examples/demo-conversation.md`](https://github.com/alchaincyf/zhangxuefeng-skill/blob/main/examples/demo-conversation.md). No build steps, compilation, or automated testing infrastructure is required.

### What is the three-step Agentic workflow I must follow?

The **three-step Agentic workflow** is a deterministic process defined in [`SKILL.md`](https://github.com/alchaincyf/zhangxuefeng-skill/blob/main/SKILL.md) (lines 48-52) that governs how the agent responds to queries. It consists of: (1) **Classification** – parsing user intent, (2) **Research** – performing a mandatory web search for factual queries, and (3) **Response** – generating the answer using retrieved data. Any contribution that answers concrete questions must explicitly include a research step to avoid breaking the protocol.

### How do I add a new research source to back a mind-model?

Create a new markdown file under `references/research/` (e.g., [`07-interview-2024.md`](https://github.com/alchaincyf/zhangxuefeng-skill/blob/main/07-interview-2024.md)) containing the source details, key points, and a "引用" section explaining how to use it. Then reference this file in the **证据** (evidence) block of the relevant mind-model in [`SKILL.md`](https://github.com/alchaincyf/zhangxuefeng-skill/blob/main/SKILL.md) using a relative GitHub URL like [`/blob/main/references/research/07-interview-2024.md`](https://github.com/alchaincyf/zhangxuefeng-skill/blob/main//blob/main/references/research/07-interview-2024.md).

### Can I translate the skill into other languages?

Yes. To localize the skill, fork [`SKILL.md`](https://github.com/alchaincyf/zhangxuefeng-skill/blob/main/SKILL.md) into a new file (e.g., [`SKILL.en.md`](https://github.com/alchaincyf/zhangxuefeng-skill/blob/main/SKILL.en.md) for English), translate the content while preserving the front-matter structure, and update the `name` and `description` fields in the front-matter to reflect the new language. Submit the new file via a standard Pull Request against the `main` branch.