How to Add New Features to Zhangxuefeng-Skill: A Declarative Guide to Extending Agent Capabilities

You add new features to zhangxuefeng-skill by editing the declarative markdown files—primarily SKILL.md—to extend decision heuristics, add research sources, or define new trigger phrases, with no compilation or dependency management required.

zhangxuefeng-skill is a markdown-based Agent-Skill that runs on any runtime supporting the Agent Skills protocol, including Claude Code, Codex, Cursor, OpenClaw, and Hermes. Because the entire behavior is defined declaratively in markdown files rather than compiled code, adding new features requires only text edits to specific files in the repository. This architecture makes extending the skill straightforward, version-controlled, and instantly effective upon installation.

Understanding the Declarative Architecture

Unlike traditional software that requires compilation or binary assets, zhangxuefeng-skill operates entirely through markdown declarations. The runtime loads the repository and interprets these files to determine behavior, decision logic, and response patterns.

The Core Configuration File

The SKILL.md file serves as the single source of truth for the skill’s behavior. Located at the repository root, this file contains:

• YAML front-matter (lines 1-7) defining metadata such as name, description, and version
• Trigger phrases (around line 8) that activate the skill
• Key Sources table (lines 49-57) referencing external research
• Decision Heuristics section (lines 195-202) containing the numbered logic rules that drive responses

Supporting Assets Directory

The repository organizes supplemental content into specific directories:

• references/research/ — Contains markdown files serving as ground truth for fact-checking
• examples/ — Houses dialogue demonstrations that function as regression tests and user documentation
• README.md — Provides installation instructions and high-level feature linkages (lines 74-78 for examples section)

Five Methods to Add New Features to Zhangxuefeng-Skill

1. Extend Decision Heuristics in SKILL.md

To add a new decision-making rule—such as an AI-risk assessment heuristic—locate the Decision Heuristics (决策启发式) section in SKILL.md near lines 195-202. Append a new numbered item to the list. The skill’s answer engine iterates over these heuristics when constructing responses, automatically applying any new rules you add.

2. Integrate Additional Research Sources

To incorporate new data, such as industry reports or updated statistics:

• Create a new markdown file in references/research/ (e.g., 07-ai-risk.md)
• Reference this file in the Key Sources table of SKILL.md (lines 49-57)
• The runtime loads the entire repository, making your new data available for fact-checking during skill execution

3. Create Custom Example Dialogues

Demonstrate new features and provide regression testing by:

• Creating a new file in examples/ (e.g., ai-risk-demo.md)
• Linking to this file from the README’s Examples section (lines 74-78)
• These examples serve as both user documentation and test cases for the skill’s logic

4. Expose New Trigger Phrases

To activate the skill with additional utterances, add new bullets under the Trigger phrases paragraph in SKILL.md near line 8. The runtime matches user input against these phrases to determine when to invoke the skill.

5. Update Skill Metadata

Modify the YAML front-matter at the top of SKILL.md (lines 1-7) to update the skill’s name, description, or version identifier. This metadata is read by the skill loader to register the skill correctly in the runtime environment.

Step-by-Step Implementation Examples

Adding an AI-Risk Check Heuristic

Locate the decision heuristics list in SKILL.md and add the new rule:

# In SKILL.md, locate the "决策启发式" list (around line 195) and add:

8. **AI-risk 检验** — 评估目标行业/岗位在 2026-2028 年的 AI 替代概率；如果替代风险 > 30% 且家庭背景不具备转行缓冲，则直接给出"别走这个路"的结论。

Creating a New Research File

Create a markdown file in the research directory:

# references/research/07-ai-risk.md

## AI-risk 报告（2026）

- 2025-2026 年 AI 替代率统计（来源：IDC、麦肯锡），
- 各行业 AI 替代概率表（表格），
- 推荐的防御性职业列表。

Linking Research to SKILL.md

Update the Key Sources table to reference your new file:

### 决策启发式

...
| 8 | **AI-risk 检验** ... |

Adding a Custom Trigger Phrase

Extend the activation conditions in the front-matter:

# In the front-matter of SKILL.md (line 8-10):

> 当用户说 "AI 时代怎么办" 或 "AI-风险怎么办" 时也应激活此 skill。

Adding an Example Dialogue

Create a demonstration file:

# examples/ai-risk-demo.md

> 用户: 我想学人工智能专业，靠谱吗？
> 张雪峰: 先说你几分、哪个省、家里是啥背景……（AI-risk 检验）...

Then update the README to showcase it:

## 示例

- [AI-risk 示例对话](https://github.com/alchaincyf/zhangxuefeng-skill/blob/main/examples/ai-risk-demo.md)

Summary

• No compilation required — Changes to SKILL.md or supporting markdown files take effect immediately after installation or running npx skills add again.
• Edit SKILL.md to modify decision heuristics (lines 195-202), trigger phrases (line 8), metadata (lines 1-7), or source references (lines 49-57).
• Add research by creating files in references/research/ and linking them in the Key Sources table.
• Create examples in the examples/ directory and link them from README.md (lines 74-78) to provide test cases and documentation.
• Version control all changes through standard git workflows, as the repository contains no binary assets or secrets.

Frequently Asked Questions

Do I need to compile the code after adding new features?

No compilation is necessary. Because zhangxuefeng-skill is pure markdown, any changes to SKILL.md or supporting files are instantly effective after a fresh install or after running the skill installation command again. The runtime interprets the markdown directly without building binary assets.

Can I add features without modifying SKILL.md?

Some features require editing SKILL.md—specifically new decision heuristics and trigger phrases. However, you can add supplementary research data solely by creating files in references/research/, though you should reference these in SKILL.md’s Key Sources table (lines 49-57) for the skill to utilize them effectively in responses.

How do I test new features before submitting changes?

Create an example dialogue file in the examples/ directory demonstrating the new feature in action. According to the repository structure, these files serve as regression tests. You can also run the skill locally in a compatible runtime (Claude Code, Cursor, etc.) and verify that your new heuristics or trigger phrases activate correctly.

What runtime environments support these modifications?

The skill runs on any runtime implementing the Agent Skills protocol, including Claude Code, Codex, Cursor, OpenClaw, and Hermes. Because the modifications are purely declarative markdown, they work identically across all supported runtimes without environment-specific adjustments.

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