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

Contributing to the alchaincyf/zhangxuefeng-skill project involves editing markdown files—primarily SKILL.md, documents in references/research/, and 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 – 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 – 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:

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 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.

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.

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).

Create Example Dialogues

Show the skill handling new question types (e.g., "AI 产业的未来"). Add Q&A blocks to 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 into a new file (e.g., SKILL.en.md) and update the front-matter, or edit README.md directly.

Step-by-Step Contribution Guide

Follow this standard Git workflow to submit changes:

1. Fork and clone the repository.

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

2. Create a descriptive branch.

   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 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.

   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 (lines 95-102):

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

Example 2: Adding a Research Source

Create references/research/07-interview-2024.md:

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

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

Then update the model in SKILL.md:

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

Example 3: Adding a Demo Conversation

Append to examples/demo-conversation.md:

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

Key Files Every Contributor Should Know

File	Purpose	Direct Link
README.md	High-level description, installation commands (npx skills add ...), and quick-start guide.	/blob/main/README.md
SKILL.md	Runtime manifest containing the skill manifest, workflow, mind-models, and expression DNA.	/blob/main/SKILL.md
references/research/*.md	Primary research material backing every claim.	/tree/main/references/research
examples/demo-conversation.md	Real-world dialog snippets for testing and documentation.	/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 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 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, uploading research to references/research/, or expanding 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 (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) 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 using a relative GitHub URL like /blob/main/references/research/07-interview-2024.md.

Can I translate the skill into other languages?

Yes. To localize the skill, fork SKILL.md into a new file (e.g., 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}