# How Atomic Skill Design Prevents Anti-Patterns in cangjie-skill

> Discover how atomic skill design in cangjie-skill prevents anti-patterns. Learn about the six invariants that ensure robust, maintainable, and verifiable skill development.

- Repository: [kangarooking/cangjie-skill](https://github.com/kangarooking/cangjie-skill)
- Tags: best-practices
- Published: 2026-08-16

---

**Atomic skill design prevents anti-patterns by enforcing six strict invariants—atomicity, traceability, verifiability, boundaries, evolvability, and user participation—that constrain each skill to a single methodology unit with mandatory source citations, explicit triggers, guard clauses, and automated test coverage.**

The `kangarooking/cangjie-skill` repository implements a rigorous methodology for converting book knowledge into executable Claude skills. By codifying requirements into the `templates/SKILL.md.template` and enforcing them across six pipeline stages, the framework systematically eliminates the design flaws that plague naive knowledge-to-code conversions.

## The Six Invariants That Block Anti-Patterns

According to [`methodology/00-overview.md`](https://github.com/kangarooking/cangjie-skill/blob/main/methodology/00-overview.md), the cangjie-skill pipeline mandates six invariants that directly neutralize common skill-design anti-patterns before they reach production.

### Invariant 1: Atomicity (原子性) Eliminates "Catch-All" Skills

**Over-large "catch-all" skills** attempt to cover multiple topics, creating vague triggers and rarely useful outputs. The atomicity rule states that one skill handles exactly one methodology unit and cannot be "big and comprehensive" (大而全). This forces the **A2 description** to remain concise (≤ 300 characters) and tightly scoped, preventing scope creep at the design stage.

### Invariant 2: Traceability (可追溯) Fixes Undocumented Origins

**Untraceable skills** lack provenance, making maintenance and verification impossible. Every skill must declare `source_book` and `source_chapter` metadata in its frontmatter. This invariant guarantees that every recommendation can be linked back to its original source material, creating an audit trail from book to binary.

### Invariant 3: Verifiability (可验证) Stops Noisy Triggers

**Unverifiable triggers** activate in irrelevant contexts, causing "noise" calls that degrade user experience. The [`methodology/04-stage2-ria-plus.md`](https://github.com/kangarooking/cangjie-skill/blob/main/methodology/04-stage2-ria-plus.md) specification requires the **A2 (Future Trigger)** section to enumerate concrete scenarios, language signals, and clear distinctions from neighboring skills. Stage 4 **pressure-testing** then validates that triggers fire correctly and only in appropriate contexts.

### Invariant 4: Boundaries (边界) Prevent Over-Use

**Missing boundaries** lead to skills being invoked when they should not apply. The **B (Boundary)** section in the skill template explicitly states *when NOT* to use the skill and lists author-cited failure modes. This "防止乱调用" (prevent random invocation) guard clause ensures the skill self-rejects when misapplied.

### Invariant 5: Evolvability (可进化) Enables Continuous Improvement

**Static skills** without test data cannot be iteratively refined. Every skill must ship a [`test-prompts.json`](https://github.com/kangarooking/cangjie-skill/blob/main/test-prompts.json) file compatible with `darwin-skill`, enabling automated regression testing. This invariant transforms skills from static scripts into living components that can evolve with user feedback.

### Invariant 6: User Participation (用户参与) Catches Misalignment Early

**Orphaned pipelines** proceed without stakeholder validation, risking misalignment with expectations. The methodology mandates user review after **stage 0** (skeleton) and **stage 1.5** (candidate selection), catching conceptual mismatches before implementation investment.

## The R-I-A1-A2-E-B Structure as an Anti-Pattern Firewall

The `templates/SKILL.md.template` enforces a six-part structure that operationalizes the invariants:

- **R (Reading)**: The source material excerpt
- **I (Interpretation)**: Author's core concept explanation
- **A1 (Past Application)**: Historical usage examples
- **A2 (Future Trigger)**: Specific activation conditions and linguistic signals
- **E (Execution)**: Step-by-step implementation logic
- **B (Boundary)**: Explicit non-usage conditions and failure modes

This structure prevents the **ambiguous trigger** anti-pattern by forcing concrete scenario definitions in A2, while the B section acts as a runtime guard against the **context mismatch** anti-pattern.

## Pressure Testing Validates the Design

Before delivery, each skill undergoes **stage 4 pressure-testing** documented in [`methodology/06-stage4-pressure-test.md`](https://github.com/kangarooking/cangjie-skill/blob/main/methodology/06-stage4-pressure-test.md). This process verifies that:

1. Triggers activate only in specified scenarios
2. Boundary conditions correctly reject inappropriate queries
3. The skill returns to the correct neighboring skill when boundaries are hit

This validation step ensures that theoretical anti-pattern protections hold under real-world load.

## Example: An Atomic Skill Implementation

Below is a minimal atomic skill that adheres to the six invariants, demonstrating how the structure prevents anti-patterns in practice:

```markdown
---
name: inversion-thinking
description: |
  当用户在权衡方案、犹豫不决时，且说出“我该怎么选择”“两者哪个更好”等话语时触发。  
  不适用：纯信息查询、要求提供事实数据的情境。
source_book: 《穷查理宝典》 查理·芒格
source_chapter: 第三讲
tags: [decision, mental-model, cognitive-bias]
related_skills: []
---

## R — Reading

> “逆向思维：先想办法让自己不做决定，然后再逆向思考怎样才能让自己必须做决定。”

## I — Interpretation

作者把逆向思维概括为：先假设所有选项都不可行，找出唯一的阻碍点，再逆向推导出最佳决策路径。

## A1 — Past Application

- **案例1**：在投资组合选择时，先排除所有不符合风险容忍度的资产，剩下唯一符合条件的标的即为推荐。

## A2 — Future Trigger ★

- **情境**：用户表达“我不知道该怎么选”“两个方案都有优势”  
- **语言信号**：*怎么决定*、*该选哪个*、*犹豫不决*  
- **区别**：不同于“决策树”skill，后者要求用户提供明确的层级结构。

## E — Execution

1. 列出所有可行选项。  
2. 对每个选项标记阻碍点。  
3. 选择阻碍点最少的选项。  
4. 若仍有多余选项，回到步骤 2。

## B — Boundary

- **不要**在用户仅询问“某个概念的定义”时触发。  
- **警告**：如果用户已提供完整的决策框架，则使用“决策树”skill 更合适。

```

This implementation demonstrates **atomicity** by covering only "逆向思维" (inversion thinking), **traceability** via the source book citation, **verifiability** through specific trigger phrases in A2, and **boundary protection** through explicit non-usage conditions in the B section.

## Summary

- **Atomic skill design** in `kangarooking/cangjie-skill` enforces six invariants that block common anti-patterns before production.
- **Scope limitation** via atomicity prevents "catch-all" skills that trigger vaguely.
- **Source citation requirements** eliminate untraceable knowledge fragments.
- **Explicit trigger definitions** in A2 sections reduce false-positive activations.
- **Boundary declarations** in B sections act as guard clauses against misuse.
- **Mandatory test files** enable regression testing and skill evolution.
- **User review gates** at stages 0 and 1.5 catch misalignment early.

## Frequently Asked Questions

### What is the primary anti-pattern that atomic skill design targets?

The primary target is the **"catch-all" skill** that attempts to cover broad topic ranges, resulting in vague triggers and low utility. By enforcing **Invariant 1 (Atomicity)** through the [`methodology/00-overview.md`](https://github.com/kangarooking/cangjie-skill/blob/main/methodology/00-overview.md) specification, cangjie-skill restricts each skill to a single methodology unit, ensuring tight scope and high specificity.

### How does the A2 section prevent false trigger activations?

The **A2 (Future Trigger)** section mandates concrete scenario descriptions, specific language signals, and differentiation from related skills. According to [`methodology/04-stage2-ria-plus.md`](https://github.com/kangarooking/cangjie-skill/blob/main/methodology/04-stage2-ria-plus.md), this section must list exact activation conditions, which are then validated during stage 4 pressure-testing to confirm the skill only fires in appropriate contexts.

### Why is the B (Boundary) section critical for production skills?

The **B section** prevents the **missing boundaries** anti-pattern by explicitly documenting when *not* to use the skill. As specified in the R-I-A1-A2-E-B template, this section lists failure modes and guard clauses, ensuring the skill rejects queries outside its domain rather than generating incorrect or irrelevant outputs.

### What role does [`test-prompts.json`](https://github.com/kangarooking/cangjie-skill/blob/main/test-prompts.json) play in the methodology?

The **evolvability invariant** requires every skill to include a [`test-prompts.json`](https://github.com/kangarooking/cangjie-skill/blob/main/test-prompts.json) file compatible with `darwin-skill`. This enables automated regression testing during stage 4, ensuring that modifications to the skill do not break trigger logic or boundary conditions, thereby supporting safe iterative refinement.