Chapter 7 · Skills: On-Demand Domain Knowledge Packs

Chapter goals: Master the structure and conventions of SKILL.md, understand the cost model of progressive disclosure, and learn to organize domain knowledge into reusable跨-project skill assets.

7.1 What Problem Skills Solve

There's a problem with writing knowledge into the agent function: every round costs tokens. But most专业领域知识 (refund processes, code review checklists, deployment manuals) is only needed at特定 moments.

Skills (技能) package this knowledge as on-demand loading:

Component	Visibility	Purpose
name + description	Always visible (one line in目录)	Model uses it to judge whether to activate
instructions (body)	Loaded only after activation	Full操作 process
Supporting files	Loaded only on explicit read	Checklists, templates, reference docs

This is progressive disclosure: mount dozens of skills,平时 only花几十行目录的 token; when a task matches, the model激活 reads the full text.

7.2 Writing a Skill目录

A skill on磁盘 is just a directory containing SKILL.md:

src/skills/refunds/
├─ SKILL.md        # frontmatter +操作 process
└─ POLICY.md       # Supporting file: loaded only when the model主动 reads

<!-- src/skills/refunds/SKILL.md -->
---
name: refunds
description: End-to-end handle customer refund requests. Use when the customer requests a refund or disputes a charge.
---

Follow this流程 for every refund request:

1. Confirm the order ID and refund reason.
2. Read `POLICY.md` and verify whether the reason meets refund conditions.
3. If eligible: use the `issue_refund` tool to process the refund andconfirm the amount with the customer.
4. If not: explain the具体规则 clause triggered and offer an alternativefrom the policy.

Frontmatter conventions (Flue validates per the Agent Skills开放标准):

• name required: lowercase letters/numbers/hyphens, ≤64 chars, must match the directory name;
• description required: non-empty, ≤1024 chars — it carries全部路由 decision;
• license / compatibility / metadata optional, informational only;
• Unknown fields are ignored (compatible with other hosts' skills), but .env, private keys, and other机密 files are硬 errors at打包 time.

7.3 Import and Mount

Skills are statically imported like普通 modules — at build time Flue识别 imports, validates frontmatter, and bundles the entire directory:

// src/agents/support-agent.ts
'use agent';
import { useModel, useSkill } from '@flue/runtime';
import refunds from '../skills/refunds/SKILL.md'; // Directly import the markdown file

export function SupportAgent() {
  useModel('anthropic/claude-haiku-4-5');
  useSkill(refunds); // One-line mount
  return 'Answer customer support questions clearly and accurately; follow the refund流程 when relevant.';
}

Rules and技巧:

// ✅ Static import —解析 at build time; editing the skill directory takes effect instantly in dev
import refunds from '../skills/refunds/SKILL.md';

// ❌ Dynamic import causes a build error directly
// const bad = await import('../skills/refunds/SKILL.md');

// ✅ Import skills from npm packs (包 needs to export SKILL.md and子 paths)
import review from '@acme/review-skills/review/SKILL.md';

// ⚠️ Same-name skills can only be mounted once per render; duplicate mounts throw
useSkill(refunds);
// useSkill(refunds2); // If refunds2.name is also 'refunds' → throw

7.4 Conditional Mounting: Unlocking Skills Mid-Session

All resource类 Hooks support conditional declaration — combined with persistent state you can实现 "stage unlock":

'use agent';
import { useModel, usePersistentState, useSkill, useAgentStart } from '@flue/runtime';
import basicSupport from '../skills/basic-support/SKILL.md';
import escalationPlaybook from '../skills/escalation/SKILL.md';

export function SupportAgent() {
  useModel('anthropic/claude-haiku-4-5');
  const [vip] = usePersistentState('vip', false);

  // Basic skill always available
  useSkill(basicSupport);

  // Escalation playbook only enters the目录 after the flag flips;
  // runtime播报s the目录变化 to the model without busting已缓存的 prompt
  if (vip) {
    useSkill(escalationPlaybook);
  }

  // Async check user tier at session start and unlock
  useAgentStart(async () => {
    // ...query CRM then flip vip标志 via setPersistentState
  });

  return 'Handle customer inquiries; use available professional skills when needed.';
}

7.5 Designing High-Quality Skills

---
name: review-pr
description: Perform structured review on a Pull Request. Use when the user requests a code review or checks before merging.
---

Review流程:

1. Read the PR description and变更 file list to understand the改动 intent.
2. Read the review checklist in `CHECKLIST.md` and核对 item by item.
3. Classify每个问题 by severity: blocker / suggestion / nit.
4. Output a summary report; blocker issues必须 give修复建议.

Four经验:

// Skill引用的类型: importing SKILL.md yields a强类型 SkillReference,
// not a bare string — passing the wrong type throws at compile time
import type { SkillReference } from '@flue/runtime';
import refunds from '../skills/refunds/SKILL.md';

// Type-wise it is exactly this:
const ref: SkillReference = refunds; // ✅
// const bad: SkillReference = 'refunds'; // ❌ compile error: string is not a skill reference

1. description is the sole routing basis: write "what it does + when to use it" ("use when..."句式);
2. SKILL.md body holds only流程: move大块参考资料 to supporting files, reference them by relative path in the body;
3. Skills are assets: open format means the same skill works with Claude Code and其他 harness, and can be引入从第三方原样;
4. Short内容 use defineSkill inline definition — no need to建目录 for three lines of instructions.

7.6 Chapter Summary

• Skill = name + description (常驻目录) + instructions (loaded on activation) + supporting files (loaded on explicit read);
• Progressive disclosure lets多 skills不增加日常 token负担;
• SKILL.md follows the Agent Skills开放标准: name matches目录名, description carries路由;
• Static import is declaration; dynamic import is a build error; same name can only mount once;
• Conditional mounting + persistent state实现会话中途解锁能力.

🧪 随堂测验

点击你认为正确的选项。答错时会展示正确答案与原因解析。

1. When does the skill's description become visible to the model?

2. Regarding SKILL.md frontmatter, which field is mandatory?

3. Which skill导入方式 causes a build error?

4. When do supporting files (e.g., POLICY.md) enter the model context?

🛠️ Hands-On Exercises

1. Turn your team's SOP into a skill directory (SKILL.md + one supporting file); mount on a测试 agent and验证 the activation behavior.
2. 故意 violate conventions (name mismatched with目录 name, overly long description); observe Flue's validation报错 messages.
3. Use persistent state to implement "paid users unlock advanced skills"; verify the model truly cannot see it under a free account.

Skills can now load on demand. Next,接入更大的世界: MCP Tool Ecosystem.