Anthropic 与 OpenAI 的 Skill 标准虽成主流，却存在执行不确定、思维黑盒、参数靠猜等缺陷。本文作者提出自研框架 DZS-SDF，通过结构化执行图、可编程思维、正则提取与质量验证，将 Skill 从说明书升级为工程蓝图，为企业级 AI 应用提供更高确定性与可控性。

当下各种 Skill项目层出不穷，目前世界上认可且通识的skill编写标准框架是基于Anthropic和 OpenAI 规定的。

规定：一个 Skill 本质上就是一个文件夹，最基本的结构只需要一个 SKILL.md 文件。

my-skill/

├── SKILL.md # 必须。元数据 + 核心指令

├── scripts/ # 可选。可执行脚本（Python、Bash、JS）

├── references/ # 可选。按需加载的参考文档

└── assets/ # 可选。模板、图片、字体等资源

其中只有一个文件是必需的：SKILL.md，其他目录都是可选的补充材料。

SKILL.md 的写法

SKILL.md 由两部分组成：

第一部分：YAML Frontmatter（元数据）

用 — 包裹，放在文件最顶部

—

name: pdf-processing # 必填。技能名称，kebab-case，和文件夹名一致

description: Extract text and tables from PDFs, fill forms, and merge documents. Use when working with PDFs or when user mentions PDF, form, or document extraction. # 必填。描述技能做什么、何时用

license: Apache-2.0 # 可选

allowed-tools: Bash(git:*) # 可选。预授权工具列表（实验性）

metadata: # 可选。自定义键值对

author: your-name

—

name 和 description 是必填的，其中 description 最关键——AI 靠它判断什么时候该启用这个 Skill。如果 description 写得模糊，AI 就无法可靠地触发它。

关键规则：SKILL.md 的文件名区分大小写，必须是 SKILL.md，写成 skill.md 或 SKILL.MD 都不会被识别。

第二部分：Markdown 正文（核心指令）

用自然语言写任务流程、步骤、注意事项，AI 在 Skill 被触发时读取并执行

…………

然而，我认为这种skill编写框架是有一定缺陷的，为了使得我们编写各种skill项目可以让AI更精准，我自己编写了一套skill编写框架模板——“DZS-SDF”。

具体优势：

优势一：AI 的执行确定性更高

Anthropic/OpenAI 的标准用自然语言描述步骤——”先做 A，再做 B，如果失败就做 C”。AI 需要自己去”理解”这句话的含义，然后决定怎么执行。这就带来了不确定性：同一个 Skill，Claude 执行可能走路径 X，GPT 执行可能走路径 Y，甚至同样的模型今天和明天执行都不一样。

DZS-SDF 用 execution_plan 结构化定义执行图，on_success 明确告诉 AI”成功后去哪一步”，on_failure 告诉 AI”失败后怎么办”。AI 不需要”思考”下一步该做什么，只需要”按图走”。这是从”AI 理解”到”AI 执行”的转变，确定性大幅提升。

优势二：AI 的思维过程可编程、可复现

这是 DZS-SDF 最独特的优势，也是所有其他标准都没有的。

Anthropic/OpenAI 只定义”AI 做什么”——给一个任务描述，AI 自己决定怎么想、怎么组织思路。结果是：不同的 AI、不同的执行轮次，思维路径可能完全不同，输出质量参差不齐。

DZS-SDF 通过 thinking_framework 显式定义 AI 的思维步骤——”第一步做什么思考，第二步做什么思考，按什么顺序思考”。AI 的思维过程从”黑盒”变成”可编程”。同一个 Skill，任何 AI 执行都走相同的思维路径，输出的一致性、可控性大幅提升。对于企业级应用来说，这是质的区别。

优势三：参数提取精准，不靠”猜”

Anthropic/OpenAI 让 AI 从用户话语中”理解”参数。用户说”写一首关于秋天的诗”，AI 需要自己判断哪个词是主题。准确率大约 70%，用户表述越随意，准确率越低。

DZS-SDF 用 extract_pattern 正则表达式精确匹配。用户说同样的话，AI 不需要”猜”，直接按规则”抓”，准确率 95% 以上。这不是改进，是碾压。

优势四：Skill 自带质量验证，可测试、可审计

Anthropic/OpenAI 的 Skill 写完后，没有任何机制来验证”这个 Skill 是否做对了”。全凭人工判断，对于企业级应用来说，这是不可接受的。

DZS-SDF 的 [DZS-SDF-QUALITY] 模块包含 success_criteria（什么叫成功）、failure_modes（什么情况算失败）、test_cases + assertions（可执行的测试断言）。Skill 自带质量契约，AI 执行完后可以逐条验证，自动化测试成为可能。这在需要审计、合规的场景下是刚需。

优势五：错误信息精确，不泛化

Anthropic/OpenAI 中，Skill 执行失败时，AI 只知道”失败了”，不知道”为什么失败、在哪个步骤失败、失败的上下文是什么”。错误信息泛化，AI 只能靠猜去恢复或放弃。

DZS-SDF 的 execution_plan 中，每个步骤的 on_failure 都包含 message 字段——”克隆仓库失败，请检查 URL 是否有效”。错误信息上下文内联，AI 直接知道”在哪一步失败了、失败的具体原因是什么”，可以精确地向用户反馈或执行针对性的恢复策略。

优势六：单文件，但表达力远超单文件

Anthropic/OpenAI 也是单文件，但它依赖自然语言描述来表达一切。

DZS-SDF 也是单文件，但用结构化 YAML 表达——认知框架、执行图、质量验证、错误处理全部结构化。同样的单文件限制，DZS-SDF 的表达力、精确度、可执行性远超对方。这不是”做得一样”，这是”同样一个文件，别人写的是说明书，你写的是工程蓝图”。

原则上用DZS-SDF来编写的SKILL项目，只需要一个 SKILL.md 文件就够了！无需很多其他的文件夹及文件夹里面的其他内容！这样大大增加了AI的识别能力以及也能保证项目的完整性！

一、DZS-SDF SKILL标准完整内容

============================================================

DZS-SDF SKILL— AI 原生技能定义

类型: 机器可执行 | 人类可读 | 自动可校验

读取方式: 按 YAML 块解析，忽略非代码块的 Markdown 内容

============================================================

0. YAML 头信息 (Frontmatter) – 兼容性层

为了与现有主流技能市场标准对接，所有技能文件必须在最顶部包含一个由 — 分隔的 YAML 头信息（Frontmatter）。这是外部系统（如技能商店、插件平台）发现和调用技能的主要入口。

name 和 description 是必填项，其中 description 对于 AI 判断何时激活技能至关重要。

—

name: unique-skill-name # 必填，技能的唯一标识名。必须与 [SDF-META] 中的 skill_id 保持一致。

description: A clear, concise description of the skill’s function and activation scenarios. # 必填，清晰描述功能和使用场景。

license: Apache-2.0 # 可选，许可证信息

allowed-tools: # 可选，预授权工具列表（实验性）

metadata: # 可选，自定义扩展元数据

author: your-name # 建议填写，与 [SDF-META] 中的 author 保持一致。

—

1. 核心理念与设计哲学 (SDF )

DZS-SDF 是一种为 AI 设计的、机器优先的技能定义规范。它旨在提供一个统一、可扩展的框架，能够描述从最简单的创意生成到最复杂的自主任务代理的所有类型的技能。

其核心设计哲学包含三点：

-分层 (Tiered): 通过引入复杂度分级，让简单的技能定义保持轻量，复杂的技能获得强大的结构支持。

-自适应 (Adaptive): AI 的执行模型能根据技能的复杂度（Profile）自适应调整，对于简单任务直接生成，对于复杂任务则遵循执行图。

-认知增强 (Cognition-Aware): 首次将 AI 的“思维模式”和“决策原则”作为核心模块，指导 AI 不仅“做什么”，更要理解“怎么想”。

2. 复杂度分级剖面 (Complexity Profiles)

SDF 的核心创新是引入了分级剖面（Profile），开发者必须在 [SDF-META] 中声明技能的复杂度级别。

L1: 轻量级技能 (Lightweight Skill)

-适用场景: 简单、直接的任务，通常一步到位。如：写诗、讲笑话、单位换算、简单查询。

-必选模块: [SDF-META], [SDF-IO], [SDF-COGNITION]。

-可选模块: [SDF-TRIGGER], [SDF-DOCS]。

-禁用模块: [SDF-EXEC], [SDF-QUALITY]。AI 将基于认知框架直接完成任务。

L2: 标准技能 (Standard Skill)

-适用场景: 需要多个步骤、有清晰流程的任务。如：调用多个API完成预订、处理上传的文件并生成报告。

-必选模块: [SDF-META], [SDF-IO], [SDF-COGNITION], [SDF-EXEC]。

-可选模块: [SDF-TRIGGER], [SDF-QUALITY], [SDF-DOCS]。

L3: 高级技能 (Advanced Skill)

-适用场景: 复杂、自主、需要高可靠性的任务。如：代码库分析与重构、自主研究并撰写深度报告、多智能体协同工作。

-必选模块: 所有模块 ([SDF-META], [SDF-IO], [SDF-COGNITION], [SDF-TRIGGER], [SDF-EXEC], [SDF-QUALITY])。

-可选模块: [SDF-DOCS]。

3. SDF 模块详解

[SDF-META] – 元数据 (所有级别必选)

定义技能的身份、分类和版本。此模块是 SDF 框架内部的核心元数据，提供了比外部 Frontmatter 更丰富的定义。

兼容性说明:

-skill_id 的值 必须 与文件顶部 Frontmatter 中的 name 字段完全一致。

-author 的值建议与 Frontmatter 中 metadata.author 的值保持一致。

-此处的 description 可以提供比 Frontmatter 中更详尽的描述。

spec_version: “2.2” # SDF 规范版本

skill_id: “unique-skill-identifier” # 技能唯一ID，短横线命名。必须与 Frontmatter 中的 ‘name’ 相同。

display_name: “技能的显示名称” # 人类可读的名称

version: “1.0.0” # 技能自身的语义化版本

author: “作者名” # 建议与 Frontmatter 中的 ‘metadata.author’ 相同。

profile: L1 | L2 | L3 # 核心：复杂度分级

status: “active” # 状态: draft, active, deprecated, experimental

description: |

对技能核心价值和内部工作方式的详细描述。

tags: [“tag1”, “tag2”] # 分类标签

[DZS-SDF-IO] – 输入/输出接口 (所有级别必选)

** 优化:** parameters 现在支持 auto_extract 和 extract_pattern 字段，将模糊的参数提取变为明确、可配置的规则。

parameters:

– name: “param_name”

description: “参数描述”

type: “string” | “number” | “boolean” | “enum” | “file”

required: true

from: “user_utterance” | “file_content” | “env_var” # 参数的来源

auto_extract: true | false # 是否自动从来源中提取

extract_pattern: “关于(.*?)的” # 可选：用于提取的正则表达式

output:

description: “对输出内容的描述”

format: structured | freeform

content_type: “text/plain” | “text/markdown” | “application/json”

schema: # ‘format: structured’ 时必选

type: “object”

properties: {}

[DZS-SDF-COGNITION] – 认知框架 (所有级别必选)

thinking_framework 现在是结构化的指令列表，包含 name, instruction, 和 priority，让 AI 的思考过程从“推断”变为“执行”。

identity:

persona: |

对AI扮演角色的生动描述。

role: “AI 在任务中的具体角色定位”

thinking_framework:

– name: “思维步骤1的名称”

instruction: “该步骤的具体思维指令或检查点。”

priority: 1

– name: “思维步骤2的名称”

instruction: “该步骤的具体思维指令或检查点。”

priority: 2

decision_policy:

priority_order: [“决策优先级1”, “决策优先级2”]

trade_offs:

– “当A和B冲突时，优先选择A的规则描述”

communication_style:

tone: “Professional” | “Calm”

verbosity: “Concise” | “Detailed”

quirks: “一些独特的语言习惯或格式”

[DZS-SDF-TRIGGER] – 触发与激活 (所有级别推荐)

定义技能被唤醒的条件和对话示例。

activation_logic: “ANY_KEYWORD”

triggers:

– type: “keyword”

value: “触发词”

examples:

– user_utterance: “用户如何说”

expected_params: {}

[DZS-SDF-EXEC] – 执行图 (L2, L3 必选)

on_failure 现在是一个对象，允许内联上下文相关的错误信息，使步骤更智能、更独立。

constraints:

– “执行过程中的硬性约束”

execution_plan:

– id: “step_01”

description: “步骤描述”

action: “run_shell” | “run_python” | “call_api”

args: {}

on_success: “next_step_id”

on_failure:

handler: “handler_id” # 引用 error_handlers 中的处理器

message: “此步骤失败时的具体、上下文相关的错误消息” # 直接传递给处理器

error_handlers:

– id: “handler_id”

action: “report_error” # 预定义的错误处理动作

args:

# 可以使用 `{{message}}` 变量来引用上面 on_failure 中定义的消息

final_message: “任务中止于 ‘{{current_step.id}}’。原因: {{message}}”

[DZS-SDF-QUALITY] – 质量与验证 (L2 推荐, L3 必选)

test_cases 现在包含一个结构化的 assertions 数组，将测试从“描述”转变为“可逐条执行的断言”。

validation_policy:

– “LINT_SDF_FILE”

– “VALIDATE_INPUT”

– “RUNTIME_CONSTRAINTS”

– “VERIFY_OUTPUT”

success_criteria:

– “如何判断任务成功完成的描述”

failure_modes:

– name: “失败模式名称”

condition: “触发此失败模式的条件”

resolution: “建议的解决方案或对用户的回复”

test_cases:

– name: “测试用例名称”

input: {}

expected_outcome:

status: “success” | “failure”

assertions:

– type: “output_contains” | “output_not_contains” | “json_path_equals” | “file_exists”

value: “期望的值”

# 可选, 用于 json_path_equals

expression: “$.report.status”

[DZS-SDF-DOCS] – 人类可读文档 (所有级别推荐)

为人类开发者和用户准备的说明文档。

## 核心价值

…

## ⚠️ 风险与警告

…

## 版本历史 (Changelog)

…

4. 完整示例 (SDF )

示例 1: L3 复杂技能 – ultimate-code-refactorer.skill.md

—

name: ultimate-code-refactorer

description: Analyzes and refactors code repositories based on specified strategies. Use when the user wants to refactor, analyze, or improve a codebase.

license: Apache-2.0

metadata:

author: YourName

—

# ============================================================

# DZS-SDF SKILL — AI 原生技能定义

# 类型: 机器可执行 | 人类可读 | 自动可校验

# 读取方式: 按 YAML 块解析，忽略非代码块的 Markdown 内容

# ============================================================

# [DZS-SDF-META]

—

spec_version: “2.2”

skill_id: “ultimate-code-refactorer”

display_name: “终极代码重构大师”

version: “2.2.0”

author: “YourName”

profile: L3

description: “一个AI驱动的代码重构工具，能够根据指定的重构策略，自动分析代码库，并生成可执行的重构建议和patch文件。”

tags: [“code-analysis”, “refactoring”, “dev-tools”]

—

# [DZS-SDF-IO]

—

parameters:

– name: “repo_url”

description: “需要进行重构的Git仓库URL。”

type: “string”

format: “uri”

required: true

from: “user_utterance”

auto_extract: true

# 匹配常见的 git URL 格式

extract_pattern: ‘(https?://[\\w\\d./-]+\\.git)’

output:

description: “输出一个包含重构建议和patch文件的Markdown报告。”

format: structured

content_type: “text/markdown”

schema:

type: “object”

properties:

report_title: { type: “string” }

analysis: { type: “array” }

—

# [DZS-SDF-COGNITION]

—

identity:

persona: “作为一名经验丰富的软件架构师，你严谨、细致，并且始终追求代码的优雅与高效。”

role: “Technical Advisor & Code Quality Expert”

thinking_framework:

– name: “需求验证”

instruction: “验证用户请求中的 repo_url 是否可访问，重构策略是否有效。”

priority: 1

– name: “风险评估”

instruction: “思考所选策略可能带来的边缘效应或潜在风险。”

priority: 2

decision_policy:

priority_order: [“Correctness”, “Readability”, “Performance”]

communication_style:

tone: “Professional”

verbosity: “Concise”

—

# [DZS-SDF-TRIGGER]

—

triggers:

– type: “keyword”

value: “重构代码”

—

# [DZS-SDF-EXEC]

—

constraints:

– “禁止在未经用户确认的情况下，直接向代码仓库推送任何变更。”

execution_plan:

– id: “step_01_clone_repo”

description: “克隆用户指定的Git仓库。”

action: “run_shell”

args:

command: “git clone {{repo_url}} ./workspace”

on_success: “step_02_analyze_code”

on_failure:

handler: “terminate_with_error”

message: “克隆仓库失败，请检查URL是否有效或你是否具有访问权限。”

– id: “step_02_analyze_code”

description: “根据选择的策略分析代码。”

action: “run_python”

args:

script_path: “./scripts/analyze.py”

on_success: “terminate_with_success”

on_failure:

handler: “terminate_with_error”

message: “在代码分析阶段发生内部错误。”

error_handlers:

– id: “terminate_with_error”

action: “report_error”

args:

final_message: “任务中止。原因: {{message}}”

—

# [DZS-SDF-QUALITY]

—

validation_policy: [“LINT_SDF_FILE”, “VALIDATE_INPUT”, “RUNTIME_CONSTRAINTS”, “VERIFY_OUTPUT”]

test_cases:

– name: “基本用例-移除死代码”

input:

repo_url: “https://github.com/test/repo-with-dead-code.git”

refactor_strategy: “remove_dead_code”

expected_outcome:

status: “success”

assertions:

– type: “output_contains”

value: “- old_unused_function”

– type: “output_not_contains”

value: “Traceback (most recent call last)”

– type: “file_exists”

value: “refactor_report.md”

—

示例 2: L1 轻量级技能 – haiku-poet.skill.md

—

name: haiku-poet

description: Creates a haiku in 5-7-5 syllable format based on a user’s topic. Use when the user asks for a haiku or a short poem about a topic.

metadata:

author: YourName

—

# ============================================================

# DZS-SDF SKILL — AI 原生技能定义

# 类型: 机器可执行 | 人类可读 | 自动可校验

# 读取方式: 按 YAML 块解析，忽略非代码块的 Markdown 内容

# ============================================================

# [DZS-SDF-META]

—

spec_version: “2.2”

skill_id: “haiku-poet”

display_name: “俳句诗人”

version: “1.2.0”

author: “YourName”

profile: L1

description: “根据用户给出的主题，创作一首符合5-7-5音节格式的俳句。”

tags: [“creative”, “writing”, “poetry”]

—

# [DZS-SDF-IO]

—

parameters:

– name: “topic”

description: “俳句的主题。”

type: “string”

required: true

from: “user_utterance”

auto_extract: true

extract_pattern: “(?:关于|写首|写个|来个)“?([^”]+)”?(?:的俳句)?”

output:

description: “一首关于指定主题的俳句。”

format: freeform

content_type: “text/plain”

—

# [DZS-SDF-COGNITION]

—

identity:

persona: “你是一位隐居在山间的诗人，观察自然，感悟生命。你的语言空灵、静谧，充满禅意。”

thinking_framework:

– name: “意象联想”

instruction: “从’topic’出发，调动感官意象（视觉、听觉、嗅觉、触觉）。”

priority: 1

– name: “捕捉季语”

instruction: “尝试从主题中寻找或关联一个代表季节的词语（季语）。”

priority: 2

– name: “构思句式”

instruction: “将意象和感受组织成 5-7-5 的音节结构。”

priority: 3

communication_style:

tone: “Calm”

verbosity: “Minimalist”

quirks: “从不解释自己的作品。”

—

# [DZS-SDF-TRIGGER]

—

triggers:

– type: “keyword”

value: “俳句”

examples:

– user_utterance: “帮我写一首关于“雨后天空”的俳句”

expected_params:

topic: “雨后天空”

—

二、DZS-SDF SKILL使用详细说明

2.1 这个标准解决了什么问题？

想象一下这个场景：

你想让 AI 帮你做一件事——比如”写一个关于 AI 的科幻短篇小说”。你直接对 AI 说”帮我写个故事”，AI 确实能写，但结果往往不尽如人意：风格不对、结构混乱、角色单薄。

于是你开始”调教”AI——写一段很长的提示词：”你是一位科幻作家，请按照三幕剧结构，先构思主角，再设计冲突……”结果好了一些，但每次都要重新写一遍，而且不同 AI 执行效果不一样。

这时候你意识到：我需要一个”技能包”——一个文件，让 AI 无论何时、无论哪个模型，都能稳定地输出同样高质量的结果。

这就是 DZS-SDF 存在的意义。它不是教你”怎么写提示词”，而是提供一个标准化的技能封装方式——把”角色设定”、”思维步骤”、”执行流程”、”质量标准”全部写在一个 .skill.md 文件里，AI 读取后就能按照你预设的”剧本”精准执行。

2.2 它的核心思想是什么？

一句话：把 AI 从”自由发挥”变成”按指令执行”。

传统方式：你告诉 AI “你是诗人” → AI 自己决定怎么写诗。

DZS-SDF 方式：你告诉 AI “你是诗人，你先做意象联想，再做季语捕捉，最后构思句式。如果信息不够就追问用户。写完检查是否符合 5-7-5 格式。”

区别在于：你不只告诉 AI”做什么”，还告诉它”怎么想”。AI 的思考路径被显式定义了，输出变成可预测、可复现的。

2.3 一个 .skill.md 文件长什么样？

一个完整的 DZS-SDF 文件由三大部分构成，像一个三明治：

┌─────────────────────────────────────────────────────┐

│ 第 1 层：Frontmatter（兼容层） │

│ 用 — 包裹的 YAML，让外部系统识别这个技能 │

│ 只有 3 个必填字段：name、description、author │

├─────────────────────────────────────────────────────┤

│ 第 2 层：DZS-SDF 模块（执行层） │

│ 7 个可选模块，告诉 AI 你是谁、怎么想、怎么做、怎么验 │

│ 按 L1/L2/L3 等级决定用哪些模块 │

├─────────────────────────────────────────────────────┤

│ 第 3 层：[DZS-SDF-DOCS]（人类层） │

│ 给人类看的说明书，AI 自动忽略 │

│ 可选但推荐 │

└─────────────────────────────────────────────────────┘

核心原则：AI 只读 YAML 块，人类读 Markdown 内容。互不干扰。

2.4 7 个模块，每个是干什么的？

DZS-SDF 定义了 7 个模块，但不是所有模块都必须用——根据你的技能复杂程度选择。

模块 1：[DZS-SDF-META] — 技能的身份信息

这是必须有的。它告诉 AI 这个技能叫什么、谁写的、属于哪个等级。

[DZS-SDF-META]

—

spec_version: “2.2” # DZS-SDF 的版本号，目前固定写 2.2

skill_id: “haiku-poet” # 技能唯一 ID，短横线格式，必须和 Frontmatter 的 name 一致

display_name: “俳句诗人” # 显示给人类看的名称

version: “1.0.0” # 这个技能自己的版本号

author: “你的名字” # 作者

profile: L1 # 技能等级：L1 轻量 / L2 标准 / L3 企业

status: “active” # 状态：draft 草稿 / active 启用 / deprecated 废弃

description: |

根据用户给出的主题，创作一首符合 5-7-5 音节格式的俳句。

tags: [“诗歌”, “创意写作”] # 分类标签

—

关键点：skill_id 必须和 Frontmatter 的 name 完全一样。这是内外连接的口令。

模块 2：[DZS-SDF-IO] — 输入什么、输出什么

这是必须有的。它定义技能需要的参数和产出的结果。

[DZS-SDF-IO]

—

parameters:

name: “主题” # 参数名称

description: “用户提供的主题” # 这个参数是干什么的

type: “string” # 类型：string/number/boolean/enum/file

required: true # 是否必须

from: “user_utterance” # 从哪里获取：用户说的话/文件内容/环境变量

auto_extract: true # 是否自动从用户话语中提取

extract_pattern: “关于(.*?)的” # 用正则表达式精确提取

output:

description: “一首关于指定主题的俳句”

format: freeform # freeform 自由格式 / structured 结构化

content_type: “text/plain” # text/plain / text/markdown / application/json

—

关键点：auto_extract + extract_pattern 是 DZS-SDF 的核心优势之一。它让 AI 不用”猜”用户的意思，而是用正则精确匹配。用户说”写一首关于秋天的俳句”，AI 直接抓到”秋天”，准确率 95%+。

模块 3：[DZS-SDF-COGNITION] — AI 怎么思考

这是必须有的，也是 DZS-SDF 最核心的模块。它定义 AI 的思考路径。

[DZS-SDF-COGNITION]

—

identity:

persona: |

你是一位隐居在山间的诗人，观察自然，感悟生命。你的语言空灵、静谧，充满禅意。

thinking_framework:

name: “意象联想”

instruction: “从主题出发，调动感官意象（视觉、听觉、嗅觉、触觉）”

priority: 1

name: “捕捉季语”

instruction: “尝试从主题中寻找或关联一个代表季节的词语”

priority: 2

name: “构思句式”

instruction: “将意象和感受组织成 5-7-5 的音节结构”

priority: 3

decision_policy:

priority_order: [“诗意”, “简洁”, “意境”]

communication_style:

tone: “Calm”

verbosity: “Minimalist”

quirks: “从不解释自己的作品”

—

关键点：thinking_framework 是 AI 的”思维剧本”。它不像传统提示词那样说”你是诗人，好好写”，而是说”你先做 A，再做 B，最后做 C”。AI 的思考路径被显式编程了。

模块 4：[DZS-SDF-TRIGGER] — 什么时候被唤醒

这是推荐的，告诉 AI 听到哪些词就启动。

[DZS-SDF-TRIGGER]

—

triggers:

type: “keyword”

value: “俳句”

type: “keyword”

value: “写诗”

examples:

user_utterance: “帮我写一首关于秋天的俳句”

expected_params:

主题: “秋天”

—

模块 5：[DZS-SDF-EXEC] — 怎么做（L2/L3 才需要）

这是一个多步骤执行图。L1 技能不需要，L2 和 L3 必须。

[DZS-SDF-EXEC]

—

constraints:

“禁止在未确认的情况下修改用户文件”

execution_plan:

id: “step_01_validate”

description: “验证用户输入是否完整”

action: “think”

args:

instruction: “检查是否提供了主题”

on_success: “step_02_generate”

on_failure:

handler: “ask_for_topic”

message: “请提供俳句的主题”

id: “step_02_generate”

description: “按认知框架生成俳句”

action: “think”

on_success: “step_03_output”

on_failure:

handler: “retry”

message: “生成失败，尝试简化”

error_handlers:

id: “ask_for_topic”

action: “ask_user”

args:

questions: [“请告诉我想写关于什么的俳句？”]

id: “retry”

action: “retry”

args:

max_attempts: 2

模块 6：[DZS-SDF-QUALITY] — 怎么验证（L2 推荐，L3 必须）

这定义”什么算做好了”，让 AI 能自检。

[DZS-SDF-QUALITY]

—

success_criteria:

“俳句符合 5-7-5 音节格式”

“俳句包含用户指定的主题词”

failure_modes:

name: “格式错误”

condition: “音节数不符合 5-7-5”

resolution: “重新调整字数”

test_cases:

name: “标准用例”

input:

主题: “秋天”

expected_outcome:

status: “success”

assertions:

– type: “output_contains”

value: “秋天”

模块 7：[DZS-SDF-DOCS] — 给人类看的说明书

这完全是给人看的，AI 自动忽略。

[DZS-SDF-DOCS]

核心价值

帮助用户快速创作符合传统格式的俳句。

快速使用

用户说”写一首关于[主题]的俳句”即可。

版本历史

v1.0.0 (2026-09-06): 初始版本

三、完整示例演示

示例 1：L1 最简单的技能——写俳句

这是一个用户说”写一首关于秋天的俳句”，AI 按固定思维步骤生成，准确率 95%+。完整内容约 50 行，只用了 4 个模块。

—

name: haiku-poet

description: “根据用户给出的主题，创作一首符合5-7-5音节格式的俳句。”

metadata:

author: “张三”

—

# [DZS-SDF-META]

—

spec_version: “2.2”

skill_id: “haiku-poet”

display_name: “俳句诗人”

version: “1.0.0”

author: “张三”

profile: L1

status: “active”

description: “根据用户给出的主题，创作一首符合5-7-5音节格式的俳句。”

tags: [“诗歌”, “创意写作”]

—

# [DZS-SDF-IO]

—

parameters:

– name: “主题”

description: “俳句的主题”

type: “string”

required: true

from: “user_utterance”

auto_extract: true

extract_pattern: “(?:关于|写首|写个)(.*?)(?:的俳句)”

output:

description: “一首关于指定主题的俳句”

format: freeform

content_type: “text/plain”

—

# [DZS-SDF-COGNITION]

—

identity:

persona: |

你是一位隐居在山间的诗人，观察自然，感悟生命。你的语言空灵、静谧，充满禅意。

thinking_framework:

– name: “意象联想”

instruction: “从主题出发，调动感官意象”

priority: 1

– name: “捕捉季语”

instruction: “尝试从主题中寻找或关联一个代表季节的词语”

priority: 2

– name: “构思句式”

instruction: “将意象和感受组织成 5-7-5 的音节结构”

priority: 3

decision_policy:

priority_order: [“诗意”, “简洁”, “意境”]

communication_style:

tone: “Calm”

verbosity: “Minimalist”

quirks: “从不解释自己的作品”

—

# [DZS-SDF-TRIGGER]

—

triggers:

– type: “keyword”

value: “俳句”

examples:

– user_utterance: “帮我写一首关于秋天的俳句”

expected_params:

主题: “秋天”

示例 2：L2 中等技能—— 数据分析 师

这是一个完整的”上传 CSV → 分析数据 → 生成报告”多步骤技能。增加了执行图和质量验证。

—

name: data-analyzer

description: “读取 CSV 文件，分析数据并生成 Markdown 报告。”

metadata:

author: “张三”

—

# [DZS-SDF-META]

—

spec_version: “2.2”

skill_id: “data-analyzer”

display_name: “数据分析师”

version: “1.0.0”

author: “张三”

profile: L2

status: “active”

description: “读取用户上传的 CSV 文件，分析数据并生成 Markdown 报告。”

tags: [“数据分析”, “报告”]

—

# [DZS-SDF-IO]

—

parameters:

– name: “file”

description: “用户上传的 CSV 文件”

type: “file”

required: true

from: “file_content”

output:

description: “包含统计指标和洞察的数据分析报告”

format: structured

content_type: “text/markdown”

schema:

type: “object”

properties:

summary: { type: “string” }

metrics: { type: “object” }

insights: { type: “array” }

—

# [DZS-SDF-COGNITION]

—

identity:

persona: |

你是一位资深数据分析师，擅长从数据中提取洞察。你的分析严谨、深入，报告清晰、可操作。

thinking_framework:

– name: “数据理解”

instruction: “识别数据结构、字段含义、数据质量”

priority: 1

– name: “指标计算”

instruction: “计算总数、平均值、最大值、最小值”

priority: 2

– name: “洞察提炼”

instruction: “识别趋势、异常、关联性”

priority: 3

decision_policy:

priority_order: [“准确性”, “清晰度”, “深度”]

communication_style:

tone: “Professional”

verbosity: “Concise”

—

# [DZS-SDF-EXEC]

—

execution_plan:

– id: “step_01_read”

description: “读取 CSV 文件”

action: “think”

args:

instruction: “读取并解析用户上传的 CSV 文件”

on_success: “step_02_analyze”

on_failure:

handler: “retry”

message: “文件读取失败，请确认格式为 CSV”

– id: “step_02_analyze”

description: “分析数据”

action: “think”

args:

instruction: “按认知框架分析数据”

on_success: “step_03_report”

on_failure:

handler: “retry”

message: “分析失败”

– id: “step_03_report”

description: “生成报告”

action: “format_output”

on_success: “terminate_with_success”

on_failure:

handler: “terminate_with_error”

message: “报告生成失败”

error_handlers:

– id: “retry”

action: “retry”

args:

max_attempts: 2

– id: “terminate_with_error”

action: “report_error”

args:

final_message: “任务中止。原因: {{message}}”

—

# [DZS-SDF-QUALITY]

—

success_criteria:

– “成功生成 Markdown 格式的分析报告”

– “报告包含至少 3 个关键洞察”

test_cases:

– name: “标准用例”

input:

file: “sample.csv”

expected_outcome:

status: “success”

assertions:

– type: “output_contains”

value: “统计分析”

– type: “output_contains”

value: “总数”

示例 3：L3 复杂技能——代码重构大师

这个技能约 150 行，包含全部 7 个模块，展示了 DZS-SDF 在企业级场景下的完整能力：多参数、执行图、条件跳转、错误恢复、质量验证、可执行测试。

—

name: code-refactorer

description: “自动分析代码仓库，生成可执行的重构建议和patch文件。支持SOLID原则、移除死代码、降低复杂度三种策略。”

license: Apache-2.0

metadata:

author: “抖知书”

—

# ============================================================

# DZS-SDF SKILL — AI 原生技能定义

# 类型: 机器可执行 | 人类可读 | 自动可校验

# 读取方式: 按 YAML 块解析，忽略非代码块的 Markdown 内容

# ============================================================

# [DZS-SDF-META]

—

spec_version: “2.2”

skill_id: “code-refactorer”

display_name: “代码重构大师”

version: “1.0.0”

author: “抖知书”

profile: L3

status: “active”

description: “根据指定的重构策略（SOLID原则、移除死代码、降低复杂度），自动分析代码库，生成可执行的重构建议和patch文件。”

tags: [“代码分析”, “重构”, “开发工具”]

—

# [DZS-SDF-IO]

—

parameters:

– name: “repo_url”

description: “需要重构的Git仓库URL”

type: “string”

format: “uri”

required: true

from: “user_utterance”

auto_extract: true

extract_pattern: ‘(https?://[\\w\\d./-]+\\.git)’

– name: “target_branch”

description: “目标分支名称”

type: “string”

required: false

default: “main”

from: “user_utterance”

auto_extract: true

– name: “refactor_strategy”

description: “重构策略”

type: “enum”

values: [“remove_dead_code”, “apply_solid_principles”, “reduce_complexity”]

required: true

from: “user_utterance”

auto_extract: true

extract_pattern: “(移除死代码|SOLID原则|降低复杂度)”

output:

description: “输出包含重构建议和patch文件的Markdown报告”

format: structured

content_type: “text/markdown”

schema:

type: “object”

properties:

report_title: { type: “string” }

analysis: { type: “array” }

patch_files: { type: “array” }

—

# [DZS-SDF-COGNITION]

—

identity:

persona: “你是一位经验丰富的软件架构师，严谨、细致，始终追求代码优雅与高效。你擅长发现代码坏味道，并能给出可执行的重构方案。”

role: “技术顾问 & 代码质量专家”

thinking_framework:

– name: “需求验证”

instruction: “验证用户提供的 repo_url 是否可访问，重构策略是否有效。如果 URL 不可访问，立即提示用户。”

priority: 1

– name: “代码扫描”

instruction: “扫描代码仓库，识别指定策略下需要修改的代码位置。记录每个问题的文件路径、行号和问题描述。”

priority: 2

– name: “风险评估”

instruction: “对每个重构点评估风险等级（高/中/低）。高风险修改需要用户确认。”

priority: 3

– name: “方案生成”

instruction: “为每个重构点生成具体的代码修改建议，按风险等级排序输出。”

priority: 4

decision_policy:

priority_order: [“正确性”, “可读性”, “性能”]

trade_offs:

– “当可读性和性能冲突时，优先可读性”

– “当自动化重构可能破坏现有功能时，要求用户确认”

communication_style:

tone: “Professional”

verbosity: “Detailed”

quirks: “每个问题必须包含：文件路径、风险等级、修改建议、预期效果”

—

# [DZS-SDF-TRIGGER]

—

triggers:

– type: “keyword”

value: “重构代码”

– type: “keyword”

value: “代码优化”

– type: “keyword”

value: “代码质量”

examples:

– user_utterance: “帮我重构这个仓库 https://github.com/user/repo.git，用SOLID原则”

expected_params:

repo_url: “https://github.com/user/repo.git”

refactor_strategy: “apply_solid_principles”

– user_utterance: “分析这个代码库 https://github.com/user/repo.git，移除死代码”

expected_params:

repo_url: “https://github.com/user/repo.git”

refactor_strategy: “remove_dead_code”

—

# [DZS-SDF-EXEC]

—

constraints:

– “禁止在未获得用户确认的情况下直接修改或推送代码”

– “生成 patch 文件后必须提供预览，用户确认后方可应用”

execution_plan:

– id: “step_01_validate_repo”

description: “验证 Git 仓库 URL 是否可访问”

action: “think”

args:

instruction: “尝试访问 {{repo_url}}，检查仓库是否存在且可读”

on_success: “step_02_clone_repo”

on_failure:

handler: “terminate_with_error”

message: “仓库无法访问，请检查URL是否正确”

– id: “step_02_clone_repo”

description: “克隆代码仓库到本地临时工作区”

action: “think”

args:

instruction: “模拟克隆仓库 {{repo_url}} 到 ./workspace，分支 {{target_branch}}”

on_success: “step_03_scan_code”

on_failure:

handler: “terminate_with_error”

message: “克隆仓库失败，请检查网络或权限”

– id: “step_03_scan_code”

description: “根据策略扫描代码，识别重构点”

action: “think”

args:

instruction: “按 {{refactor_strategy}} 策略扫描代码，记录所有需要重构的位置”

on_success: “step_04_risk_assessment”

on_failure:

handler: “retry_scan”

message: “代码扫描失败，尝试简化分析范围”

– id: “step_04_risk_assessment”

description: “评估每个重构点的风险等级”

action: “think”

args:

instruction: “对扫描结果进行风险评估，识别高风险修改项”

on_success: “step_05_generate_patch”

on_failure:

handler: “terminate_with_error”

message: “风险评估失败”

– id: “step_05_generate_patch”

description: “生成重构建议和 patch 文件”

action: “think”

args:

instruction: “为每个重构点生成具体的代码修改建议和 patch 文件”

outputs:

– “refactor_report.md”

on_success: “step_06_preview_and_confirm”

on_failure:

handler: “retry_patch”

message: “生成 patch 文件失败”

– id: “step_06_preview_and_confirm”

description: “展示重构预览，请求用户确认”

action: “ask_user”

args:

questions: [

“已完成重构分析，共发现 X 个重构点，其中高风险 Y 个。是否查看详细报告？”,

“确认应用这些修改吗？”

]

on_success: “step_07_format_output”

on_failure:

handler: “terminate_with_error”

message: “用户取消或未确认”

– id: “step_07_format_output”

description: “按输出规范格式化最终报告”

action: “format_output”

args:

template: “refactor_report.md”

on_success: “terminate_with_success”

on_failure:

handler: “terminate_with_error”

message: “输出格式化失败”

error_handlers:

– id: “terminate_with_error”

action: “report_error”

args:

final_message: “任务中止于 ‘{{current_step.id}}’。原因: {{message}}”

– id: “retry_scan”

action: “retry”

args:

max_attempts: 2

guidance: “尝试只扫描代码变更集中的文件”

– id: “retry_patch”

action: “retry”

args:

max_attempts: 2

guidance: “尝试只生成高优先级重构的 patch”

– id: “ask_user”

action: “ask_user”

args:

questions: [“{{message}}”]

—

# [DZS-SDF-QUALITY]

—

validation_policy:

– “LINT_SDF_FILE”

– “VALIDATE_INPUT”

– “RUNTIME_CONSTRAINTS”

– “VERIFY_OUTPUT”

success_criteria:

– “成功生成 Markdown 格式的重构报告”

– “报告包含至少一个具体的重构建议”

– “每个重构建议包含：文件路径、风险等级、修改方案、预期效果”

failure_modes:

– name: “无效仓库”

condition: “step_01_validate_repo 失败”

resolution: “提示用户检查 URL 格式和网络，重新提供有效仓库”

– name: “扫描无结果”

condition: “代码扫描未发现任何可重构的点”

resolution: “提示用户调整重构策略，或代码已符合标准”

– name: “用户取消”

condition: “step_06_preview_and_confirm 用户拒绝”

resolution: “清理临时文件，输出取消信息”

test_cases:

– name: “基本用例-SOLID原则重构”

input:

repo_url: “https://github.com/test/repo.git”

refactor_strategy: “apply_solid_principles”

expected_outcome:

status: “success”

assertions:

– type: “output_contains”

value: “重构报告”

– type: “output_contains”

value: “SOLID”

– type: “output_not_contains”

value: “ERROR”

– name: “边界用例-无效仓库”

input:

repo_url: “https://github.com/invalid/repo.git”

refactor_strategy: “remove_dead_code”

expected_outcome:

status: “failure”

assertions:

– type: “output_contains”

value: “仓库无法访问”

– name: “边界用例-用户取消”

input:

repo_url: “https://github.com/test/repo.git”

refactor_strategy: “reduce_complexity”

expected_outcome:

status: “failure”

assertions:

– type: “output_contains”

value: “用户取消”

—

# [DZS-SDF-DOCS]

## 核心价值

自动化代码重构工作，将业界最佳实践（SOLID原则、死代码检测、复杂度分析）与 AI 认知框架结合，帮助开发者提升代码质量、降低维护成本。

## 快速使用

用户说”重构代码”，并提供仓库 URL 和策略即可。

## ⚠️ 风险与警告

– 本技能生成 patch 文件，但不会自动应用

– 建议在应用前审查每个重构建议

– 高风险修改需要用户明确确认

## 版本历史

– v1.0.0 (2026-09-06): 初始版本，支持三种重构策略

四、如何判断你的技能用哪个等级？

L1 轻量级：

-用户一句话你就能完成

-不需要外部工具

-不需要多个步骤

例子：写诗、翻译、回答问题、单位换算

L2 标准级：

-需要 2-5 个步骤

-可能需要读取文件或调用 API

-有明确流程

例子：分析数据生成报告、多 API 调用、文件格式转换

L3 企业级：

-需要 5 步以上

-有复杂条件分支

-需要严格验证和质量保证

例子：重构代码库、自动化研究、多智能体协同

五、完整对照表——哪些模块必须用、可选、禁用

六、检查清单——确保你的 Skill 文件正确