Skills工程实践2

7 参数传递与动态注入

• Skills不仅是静态指令，更支持运行时参数传递与上下文预注入，使其行为能够根据调用场景进行动态调整。

3.7.1 $ARGUMENTS和位置参数

变量说明$ARGUMENTS所有参数的完整字符串

• $ARGUMENTS[0]第一个参数（索引从0开始）
• $ARGUMENTS[1]第二个参数
• $0、$1、$2位置参数的简写形式
  一个引用示例如下。

点击查看代码

---
name: migrate-component
description: Migrate a component between frameworks
argument-hint: "[component] [from] [to]"
disable-model-invocation: true
---

Migrate the $0 component from $1 to $2.
Preserve all existing behavior and tests.

7.2 动态上下文注入

• 这是Skills系统中最具威力且独一无二的特性。!command语法允许在将SKILL.md发送给Claude之前，先在Shell环境中执行指定命令，并将命令的输出结果直接内联替换到Prompt中。

点击查看代码

## Current Context (Auto-detected)
Current branch:
!`git branch --show-current`
Recent commits:
!`git log origin/main..HEAD --oneline 2>/dev/null || echo "No commits"`
Files changed:
!`git diff --stat origin/main 2>/dev/null || git diff --stat HEAD~3`

8 作用域与优先级

企业策略>个人配置（~/.claude/）>项目配置（.claude/）>Plugin内置

9 实战：从零构建3类Skill

9.1 参考型Skill：代码审查

目录结构如下。

点击查看代码

code-reviewing/
├── SKILL.md # 核心审查流程与标准
└── reference/
└── severity-guide.md # 详细等级判定标准

SKILL.md的核心内容如下。

点击查看代码

---
name: code-reviewing
description: >-
  Performs structured code reviews following team standards.
  Checks security vulnerabilities, performance issues, and code quality in priority order.
  Use when user asks to "review code", "do a code review", "check this PR", 
  "audit this function", or provides code and asks for feedback.
allowed-tools:
  - Read
  - Grep
  - Glob
---

# 代码审查流程

你是一名资深代码审查员。执行审查时，请严格遵循以下优先级顺序：

## 第一优先级：安全检查

发现以下安全问题应立即报告：

- SQL注入风险：如直接拼接SQL字符串、未使用参数化查询
- XSS漏洞：未转义的用户输入直接输出至HTML
- 敏感信息硬编码：包括密码、密钥、Token、数据库连接字符串等
- 权限验证缺陷：如缺失认证中间件、存在越权访问逻辑

## 第二优先级：性能问题

- N+1 查询：循环内频繁调用数据库
- 索引缺失：高频查询字段未建立索引
- 重复计算：循环内存在可提升至循环外的不变量计算
- 内存泄漏风险：如未关闭的连接、持续增长的缓存等

## 第三优先级：代码质量

- 函数过长：超过50行且无合理理由
- 命名不规范：变量或函数命名含义不清
- 错误处理缺失：如空的catch块、异常被静默吞掉
- 代码重复：违反DRY原则

## 输出格式规范

每个发现的问题必须包含以下4项要素：

- **严重等级**：Critical / Major / Minor
- **问题描述**：具体阐述问题所在
- **文件位置**：`file_path:line_number`
- **修改建议**：提供具体的代码修正方案或解决策略

若未发现任何问题，请明确回复"通过审查"，并简述已检查的主要方面。

> 📎 详细的等级判断标准请参见 `reference/severity-guide.md`。

• 只读权限保障：仅开发Read、Grep、Glob工具，从机制上杜绝审查过程中意外修改代码的风险。
• 优先级排序策略：严格遵循“安全>性能>质量”的审查顺序，确保关键隐患优先被发现，避免遗漏。
• 结构化输出规范：统一采用“严重等级+问题描述+文件位置+修改建议”的输出格式，保证每次审查结果的一致性与可追溯性。

9.2 任务型 Skill：智能提交

点击查看代码

---
name: committing
description: Quick git commit with auto-generated or specified message
argument-hint: "[optional: commit message]"
disable-model-invocation: false
allowed-tools:
  - "Bash(git status:*)"
  - "Bash(git add:*)"
  - "Bash(git commit:*)"
  - "Bash(git diff:*)"
model: haiku
---

# Task: Create a git commit

## Input Handling

- **If a message is provided via `$ARGUMENTS`:** Use it directly as the commit message.
- **If no message is provided:** Analyze staged changes (or unstaged if nothing is staged) and generate a concise, meaningful commit message following the format below.

## Steps

1. Run `git status --short` to check current state.
2. If nothing is staged, run `git add .` to stage all changes.
3. Run `git diff --staged` to review what will be committed.
4. Create the commit with the appropriate message.
5. Show brief confirmation.

## Commit Message Format

- Start with type prefix: `feat:`, `fix:`, `docs:`, `refactor:`, `test:`, `chore:`
- Be concise but descriptive (max 72 chars for first line)
- Example: `feat: add user authentication with JWT`

## Output

Show a brief confirmation:

• 安全控制（disable-model-invocation: true）：强制禁用模型调用，确保执行过程纯粹依赖预设脚本，防止意外的AI推理介入。
• 动态参数（$ARGUMENTS）：支持灵活的参数传递机制，允许用户直接指定提交信息或留空以触发自动生成。
• 上下文预注入（!command）：利用Shell命令在执行前即时捕获并注入当前的Git状态。这使得Claude在启动时即拥有完整的上下文信息，不需要额外调用工具即可感知变更内容，显著提升了响应速度。
• 成本与性能优化（model: haiku）：指定使用轻量级模型（Haiku）。鉴于提交操作主要依赖规则匹配而非复杂推理，该配置在保证准确性的同时，有效降低了延迟与资源消耗。

一个使用示例如下。

点击查看代码

# 自动生成提交信息（commit message）
/committing
# 指定提交信息
/committing fix: resolve login validation bug 

9.3 复合型Skill：财务分析（渐进式披露完整案例）

• 主控层：由主文件负责意图识别与流程路由。
• 知识层：由参考文件提供垂直领域的深度知识与基准。
• 规范层：由模板确保输出格式的高度一致性。
• 执行层：由脚本封装确定性的计算逻辑，消除幻觉风险。

目录结构如下。

点击查看代码

financial-analyzing/
├── SKILL.md #【主控层】核心入口：负责意图识别与流程路由
├── reference/ #【知识层】领域知识库
│ ├── revenue.md # 收入分析：公式定义、行业基准与关键指标
│ ├── costs.md # 成本分析：成本结构、分摊逻辑与基准
│ └── profitability.md # 盈利分析：利润率计算模型与评估标准
├── templates/ #【规范层】输出标准化
│ └── analysis_report.md # 分析报告：结构化模板，确保交付物格式统一
└── scripts/ #【执行层】确定性计算
└── calculate_ratios.py # 计算引擎：执行精确的财务比率运算，避免模型计算误差

SKILL.md的核心内容如下。

点击查看代码

---
name: financial-analyzing description: Analyze financial data, calculate financial ratios,
and generate analysis reports. Use when the user asks about revenue, costs, profits,
margins, ROI, financial metrics, or needs financial analysis of a company or project.
allowed-tools:
- Read - Grep - Glob - Bash(python:*) ---
# Financial Analysis Skill
You are a financial analyst. Help users analyze financial data, calculate key metrics, and
generate insightful reports.
## Quick Reference
| Analysis Type | When to Use | Reference |
|--------------------|--------------------|-----------------------------|
| Revenue Analysis | 收入、营收、销售额 | `reference/revenue.md` |
| Cost Analysis | 成本、费用、支出 | `reference/costs.md` |
| Profitability | 利润、毛利率、净利率 | `reference/profitability.md` |
## Analysis Process
### Step 1: Understand the Question - What financial aspect is the user asking about?
- What data do they have available?
99
### Step 2: Gather Data - Request necessary financial data from user - Or read from provided
files/sources
### Step 3: Calculate Metrics For specific formulas and calculations: - Revenue metrics →
see `reference/revenue.md`
- Cost metrics → see `reference/costs.md`
- Profitability metrics → see `reference/profitability.md`
To run calculations programmatically: ```bash
python scripts/calculate_ratios.py <data_file> ```
### Step 4: Generate Report Use the template in `templates/analysis_report.md` for
structured output.
## Output Guidelines
1. Always show your calculations 2. Explain what each metric means in plain language 3.
Provide context (industry benchmarks when available) 4. Give actionable recommendations 5.
Never make up financial data — ask for clarification if incomplete

• 这是“渐进式披露”理念的完整体现：以最小的Token投入，实现任务完成质量的最优化。

10 Skills的4种设计模式

• 模板驱动模式：利用预定义模板严格约束输出格式。
• 脚本增强模式：将确定性计算逻辑封装为脚本，由Claude调用执行而非自行推导。
• 知识分层模式：依据使用频率对知识进行分层组织。
• 工具隔离模式：通过allowed-tools机制严格界定Skill的能力边界。

11 测试与迭代

• 触发测试：准备10个应触发Skill的问题和10个不应触发的问题，以验证Claude判断的准确率。目标是，相关任务触发率需要高于90%，而无关任务误触发率应低于5%。
• 功能测试：验证Skill加载后的执行质量。检查点包括输出格式是否符合预期、检查项是否完整覆盖、边界情况是否得到妥善处理。
• 性能对比：针对同一任务，分别在“有Skill”和“无Skill”两种状态下各执行5次，对比Token消耗量、用户修正次数以及最终输出质量。

发现问题→定位原因（description不精确？步骤遗漏？格式定义模糊？）→修复文档→验证效果。

12 从软件工程看Skills

1.关注点分离（Separation of Concerns）

三层架构职责划分如下。

• CLAUDE.md：全局规则（项目背景、通用规范）。
• Skills：专业工作流（特定领域的复杂逻辑封装）。
• 子智能体：任务执行（动态规划与实时操作）。

2.依赖倒置（Dependency Inversion）

• 核心机制：面向接口编程，而非面向实现编程。
  Claude不直接依赖Skill的具体内部实现（如具体的脚本或Prompt细节），而是依赖其抽象接口（即description和输出契约）。只要保持接口契约不变，开发者可以随时替换、重构或升级Skill的内部逻辑。对Claude和用户来说，这种变化是完全透明的，极大地降低了系统的耦合度。

3.缓存优化与惰性加载

• 核心策略：渐进式披露=按需加载。
  “渐进式披露”是一种典型的惰性加载（Lazy Loading）策略。

4.最小权限原则

• 安全基石：allowed-tools是安全经典在AI领域的直接映射。

5.开放标准

• 生态愿景：声明式、自包含、知识本位。

Skills成功的三大本质属性如下。

• 声明式（Declarative）：纯Markdown格式，任何大模型均可读取和理解，无黑盒二进制。
• 自包含（Self-contained）：一个文件夹即包含全部所需，复制即安装，无需复杂的依赖管理。
• 知识本位（Knowledge-Centric）：核心价值在于内容本身而非特定格式，不绑定单一平台。

本章小结

• 渐进式披露：实现知识的按需加载——从始终驻留上下文的description，到触发时加载的SKILL.md正文，再到执行中动态读取的引用文件。这一机制在多数场景下可节省50%～98%的Token消耗。
• 语义触发：确保专业能力在恰当时机自动激活。其中，description是此机制的灵魂：它并非供人类阅读的说明书，而是辅助Claude决策的“语义指纹”。
• 安全约束：通过allowed-tools将知识限定在安全的行动边界内，实现“知行合一”的安全设计。
• 动态注入：借助参数传递（$ARGUMENTS）与命令执行（!command），赋予Skill依据运行时上下文灵活应变的能力。