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

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

---
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 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, 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 play in the methodology?

The evolvability invariant requires every skill to include a 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.

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