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

> Add new features to zhangxuefeng-skill by editing declarative markdown files No compilation needed Extend agent capabilities with new decision heuristics research sources or trigger phrases

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

---

**You add new features to `zhangxuefeng-skill` by editing the declarative markdown files—primarily [`SKILL.md`](https://github.com/alchaincyf/zhangxuefeng-skill/blob/main/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`](https://github.com/alchaincyf/zhangxuefeng-skill/blob/main/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`](https://github.com/alchaincyf/zhangxuefeng-skill/blob/main/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`](https://github.com/alchaincyf/zhangxuefeng-skill/blob/main/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`](https://github.com/alchaincyf/zhangxuefeng-skill/blob/main/07-ai-risk.md))
- Reference this file in the *Key Sources* table of [`SKILL.md`](https://github.com/alchaincyf/zhangxuefeng-skill/blob/main/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`](https://github.com/alchaincyf/zhangxuefeng-skill/blob/main/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`](https://github.com/alchaincyf/zhangxuefeng-skill/blob/main/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`](https://github.com/alchaincyf/zhangxuefeng-skill/blob/main/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`](https://github.com/alchaincyf/zhangxuefeng-skill/blob/main/SKILL.md) and add the new rule:

```yaml

# 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:

```markdown

# 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:

```markdown

### 决策启发式

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

```

### Adding a Custom Trigger Phrase

Extend the activation conditions in the front-matter:

```yaml

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

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

```

### Adding an Example Dialogue

Create a demonstration file:

```markdown

# examples/ai-risk-demo.md

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

```

Then update the README to showcase it:

```markdown

## 示例

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

```

## Summary

- **No compilation required** — Changes to [`SKILL.md`](https://github.com/alchaincyf/zhangxuefeng-skill/blob/main/SKILL.md) or supporting markdown files take effect immediately after installation or running `npx skills add` again.
- **Edit [`SKILL.md`](https://github.com/alchaincyf/zhangxuefeng-skill/blob/main/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`](https://github.com/alchaincyf/zhangxuefeng-skill/blob/main/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`](https://github.com/alchaincyf/zhangxuefeng-skill/blob/main/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`](https://github.com/alchaincyf/zhangxuefeng-skill/blob/main/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`](https://github.com/alchaincyf/zhangxuefeng-skill/blob/main/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.