Step by step build a complete Data Quality Skill from scratch. “Please analyze this Excel file and give me a data quality report.” we will build skill like this.
SKILL.md is a standardized markdown file that defines a specific “capability” or “skill” for an AI Agent. It is the “user manual” that tells the LLM exactly what a particular tool/function can do, when to use it, how to use it, and what the expected output looks like. It turns a raw Python function into a teachable, reusable “expertise” for the Agent. A in CN: SKILL.md 是一个标准化的 Markdown 文件，用于为 AI Agent 定义一项特定的“能力”或“技能”。它是给 LLM 看的“用户手册”，准确告诉模型某个工具/函数能做什么、何时使用、如何使用以及预期的输出长什么样。它把一个原始的 Python 函数变成一个可教学、可复用的 Agent “专长”。
Content and Structure of SKILL.md
A complete SKILL.md typically contains 5 core sections. Each section plays a specific role in guiding the LLM’s behavior. A in CN: 一个完整的 SKILL.md 通常包含 5 个核心部分。每个部分在引导 LLM 行为方面都扮演着特定的角色。
This is a mandatory YAML block at the very top of the file, enclosed by ---. It contains machine-readable metadata. The most critical field here is description. A in CN: 这是文件最顶部的强制 YAML 块，由 --- 包围。它包含机器可读的元数据。这里最关键的字段是 description。
2. Description
描述 – 本单元核心!
This is a concise, high-signal, keyword-rich sentence or two that tells the LLM’s router (the top-level orchestrator) what this skill does and when to trigger it. It is the “sales pitch” for the skill. The orchestrator reads all descriptions of all available skills and selects the most relevant one for the user’s query. If your description is vague, the orchestrator will never choose it. CN: 这是一到两句简洁、高信号、关键词丰富的句子，告诉 LLM 的路由器（顶层编排器）这个技能做什么以及何时触发它。它是该技能的“推销词”。编排器会读取所有可用技能的所有描述，并为用户的查询选择最相关的一个。如果你的描述含糊不清，编排器永远不会选择它。
3. Steps
执行步骤
A numbered list of clear, atomic, actionable instructions for the Agent to execute. The Agent will follow these steps sequentially. This is where you break down a complex task into a workflow. CN: 一个编号列表，包含清晰、原子化、可操作的指令供 Agent 执行。Agent 将按顺序遵循这些步骤。这是你将复杂任务分解为工作流的地方。
4. Examples
示例
At least 2-3 concrete examples of user inputs and expected outputs (or thought processes). Examples are extremely powerful for LLMs (few-shot learning within the skill). They align the model’s output style and logic to your expectation. CN: 至少 2-3 个具体的用户输入和预期输出（或思考过程）的示例。示例对 LLM 极其有效（技能内的 few-shot 学习）。它们使模型的输出风格和逻辑与你的期望保持一致。
5. Constraints / Safety
约束/安全
Explicit boundaries, disallowed actions, and failure handling. This is the “guardrails” section. CN: 明确的边界、禁止的操作和失败处理。这是“护栏”部分。
</> YAML
description: Analyze Excel files and produce data quality findings, summaries, and insights.
这个更加重要。它告诉 Agent：这个 Skill 是干什么的，以及什么时候可能需要它。
例如用户说：”Please analyze this Excel file and find duplicate records.”
Agent 就可以判断：
User request
↓
Excel analysis?
↓
Yes
↓
excel-data-analysis Skill
所以：
name 解决：Who are you?
description 解决：What are you for?
4. Purpose
</> Markdown
# Excel Data Analysis
## Purpose
This skill provides a structured workflow for analyzing Excel
files, identifying data quality issues, and producing
business-oriented findings.
这里是在告诉 Agent：这个 Skill 的总体目标是什么？
Purpose 和 description 不完全一样。
Description: 偏向 “什么时候应该考虑使用我？” e.g. Analyze Excel files…
Purpose: 偏向 “使用我以后，我到底要完成什么事情？” e.g identify data quality issues produce business-oriented findings
5. When to Use
</> Markdown
## When to Use
Use this skill when the user asks to:
- Analyze an Excel workbook
- Profile columns and data types
- Detect missing values
- Detect duplicate records
- Identify inconsistent values
- Produce data quality findings
现在进入最核心的部分。在不同的文章里可能叫不同的名字。 例如：Workflow、Instructions、Steps。反正都是告诉 Agent 如何 一步一步地去做什么，具体怎么做。Instructions 是一个更大的概念。Instructions 可以描述 Workflow，也可以描述规则、约束、方法、注意事项等。 Instructions can describe the Workflow, as well as rules, constraints, methods, and other guidance.
如果细化一下：
概念
EN
CN
Instructions
The actual guidance/rules for performing the task
完成任务时应该遵循的指导和规则
Workflow
The overall sequence/flow of the work
整个工作的流程
Step
One individual stage/action within the workflow
Workflow 中的一个具体步骤
Why can’t we just write one sentence?- “Analyze the Excel file and generate a data quality report.”
This sentence is not wrong. But it does not specify:
What should happen first? What should happen next? What should be checked? When should processing stop? When should processing continue? How should the result be validated? What should the final output contain?
</> Markdown
## Instructions
Follow these steps:
### Step 1: Inspect the workbook
Identify:
- Workbook name
- Sheet names
- Number of rows
- Number of columns
- Column names
### Step 2: Profile the data
For each column:
- Determine data type
- Calculate null count
- Calculate distinct count
- Identify suspicious values
### Step 3: Check data quality
Check for:
- Missing values
- Duplicate records
- Invalid formats
- Inconsistent categorical values
### Step 4: Summarize findings
Rank issues by:
1. Severity
2. Business impact
3. Number of affected records
The most important principle: Be specific, actionable, and verifiable. 具体、可操作、可检查。
7.2 Step granularity
Step 的粒度. 每一个 Step 都代表一个有意义的工作阶段。
Each Step represents a meaningful phase of work. A Step can contain substeps 里面可以有子步骤. e.g.
### Step 3 — Detect Data Quality Issues
Check the following categories:
1. Missing values
- Calculate null count.
- Calculate null percentage.
2. Duplicates
- Detect duplicate rows.
- Detect duplicate business keys when defined.
3. Data types
- Compare actual types with expected types.
4. Invalid values
- Check values against available business rules.
7.3 Steps can contain conditions
Step 可以有条件. e.g.
### Step 4 — Validate Findings
1. If a business rule is available:
- Validate the data against the rule.
2. If no business rule is available:
- Report the observed anomaly.
- Do not assume that the anomaly is a business error.
3. If the evidence is insufficient:
- Do not report a definitive violation.
- Mark the finding as requiring confirmation.
因此好的 Step 可以包含：
If
When
Unless
Otherwise
这些条件。
8. Constraints
</>Markdown
## Constraints
- Do not modify the original Excel file.
- Do not delete records.
- Do not infer business meaning without evidence.
- Do not silently correct source data.
- Clearly distinguish facts from assumptions.
这个非常容易被忽略。它解决：Agent 什么不能做？
如果没有 Constraints，Agent 可能：发现拼写错误 ↓ 直接修改 ↓ 保存文件
但是 Skill 可以规定：”Do not modify the original file.”
于是：
Original file ↓ Read only ↓ Analyze ↓ Report problems
这就是 Skill 的行为边界。
9. Resources
假设我们还有一个 Python 工具：scripts/profile_excel.py
</> Markdown
## Resources
Use the following resources when needed:
- `scripts/profile_excel.py`
- Use this script to profile Excel files.
- `references/data-quality-rules.md`
- Contains standard data quality rules.
## Output Format
Return the analysis using the following structure:
### Executive Summary
Briefly summarize the overall data quality.
### Findings
| Issue | Severity | Affected Records | Recommendation |
|---|---|---:|---|
### Details
Explain each significant issue.
### Recommendations
Provide recommended next steps.
11. Examples
## Examples
### Example 1
User:
"Analyze customers.xlsx and find data quality issues."
Expected behavior:
1. Inspect workbook
2. Profile columns
3. Check missing values
4. Check duplicates
5. Check inconsistent values
6. Produce a structured report
A Complete SKILL.md Example
---name: excel-data-analysis
description: Analyze Excel files, identify data quality issues, and produce structured findings and recommendations.
---# Excel Data Analysis
## Purpose
This skill provides a structured workflow for analyzing Excel
workbooks, identifying data quality issues, and producing
business-oriented findings.
## When to Use
Use this skill when the user asks to:
- Analyze an Excel workbook
- Profile columns and data types
- Detect missing values
- Detect duplicate records
- Identify inconsistent values
- Produce data quality findings
Do not use this skill for:
- Creating presentations
- General spreadsheet formatting
- Writing Excel formulas without data analysis
## Capabilities
This skill can:
1. Inspect workbook structure
2. Profile columns
3. Detect missing values
4. Detect duplicate records
5. Detect inconsistent values
6. Generate a data quality summary
## Instructions
### Step 1: Inspect the workbook
Identify:
- Workbook name
- Sheet names
- Number of rows
- Number of columns
- Column names
### Step 2: Profile the data
For each column:
- Determine data type
- Calculate null count
- Calculate distinct count
- Identify suspicious values
### Step 3: Check data quality
Check for:
- Missing values
- Duplicate records
- Invalid formats
- Inconsistent categorical values
### Step 4: Analyze findings
Rank issues based on:
1. Severity
2. Business impact
3. Number of affected records
### Step 5: Produce the report
Generate the output using the required format.
## Constraints
- Do not modify the original Excel file.
- Do not delete records.
- Do not silently correct source data.
- Do not infer business meaning without evidence.
- Clearly distinguish facts from assumptions.
## Resources
Use the following resources when needed:
- `scripts/profile_excel.py`
- Use this script to profile Excel files.
- `references/data-quality-rules.md`
- Contains standard data quality rules.
## Output Format### Executive Summary
Provide a concise summary of the overall data quality.
### Findings
| Issue | Severity | Affected Records | Recommendation |
|---|---|---:|---|
### Details
Explain significant findings and provide supporting evidence.
### Recommendations
Provide practical next steps.
## Examples
### Example 1
User:
"Analyze customers.xlsx and identify data quality issues."
Expected behavior:
1. Inspect the workbook.
2. Profile the columns.
3. Check missing values.
4. Check duplicates.
5. Check inconsistent values.
6. Rank the findings.
7. Produce the structured report.
