AI Agent Skill 工程化（实战）：我如何把一年 AI 编程经验"数字化" -

前言

导读: 我之前对于设计 Skill 倾向于就是依据数据来支撑，现在理论讲完了，那么就来看真实案例。

这篇文章以 frontend-dev-prompt-craft Skill 为完整案例，带你走一遍从需求分析到 Eval 验证的 Skill 创建全流程。

📖 本文属于《AI Agent Skill 工程化》系列实战篇

案例仓库：

https://github.com/yangmeishux/frontend-team-marketplace/tree/main/plugins/frontend-team-toolkit/skills/frontend-dev-prompt-craft

这个技能是基于我的真实项目业务存在的，所有的数据与信息，都是基于之前我做过的所有业务的基础上做的。

可以说这个技能从某种层面上，就是复制了我个人的开发经验与个人开发经验。

数据与信息的来源，大概从一年前，我使Cursor开始，到现在我基本上是Cursor为主要，Claude Code + 阿里百炼和 Qoder 为次要。

我从使用AI工具进行编程的时候，就使用 markdown 记录下了我大部分需求开发的时候，与AI 进行对话 Chat 的时候，我记录下了一系列的相关提示词。

我某一天突然发现这些数据信息，还是可以让AI 帮我进行分析总结归类的。

这个其实就是我自己的经验与开发风格具体化的呈现。

提示词既是需求开发文档

需求开发的时候，我们没有办法直接对给AI一份文档就可以搞定所有，我们每个人不一样，写的提示词也是不一样的，我们发现一个问题：

每次给 AI 编码工具写提示词，格式五花八门。

有人写一段话，有人写列表，有人写需求文档截图。

结果呢？AI 理解不一致，效率忽高忽低。

为此我觉得，我可以将我之前记录的数据进行转换，我们团队需要：

需要一个 Skill 来统一转化模糊需求 →结构化提示词。

这就是 frontend-dev-prompt-craft Skill 的诞生背景。

而且这个技能还可以不断迭代，集大家的所有提示词，从而打造成团队的一个重要的工具。

一套集合了全部团队开发人员的提示词 Skill ，它依据真实的项目场景而诞生，意味了它集合了我们先用的所有的项目基础知识，那么它就可以对我们每个项目很熟悉，那么提示词就好根据项目非常的精准。

完整的提示词就是需求描述 也是需求开发文档。

一、需求分析：识别任务类型

第一步：回顾历史请求

团队回顾过去 100+ 次 AI 编码请求，分类归纳。

结果：8 种前端开发任务

类型	代码	适用场景	频率
页面功能开发	PAGE	新增页面、按钮、列表、表单	35%
UI还原	UI	设计稿还原、动画效果	15%
接口对接	API	Yapi文档、多接口联动	20%
技术方案设计	ARCH	架构重构、维护性问题	5%
批量重构	REFACTOR	域名替换、批量配置修改	10%
Bug调试	DEBUG	排查问题、修复Bug	10%
需求分析迭代	PRD	PRD生成开发文档、增量开发	3%
组件迁移	MIGRATE	跨项目迁移、替换依赖	2%

关键洞察：前端开发不是”一个任务”，而是”8 种任务类型”。每种类型需要不同的信息。

二、定义触发边界

触发条件

## trigger
用户需要将模糊的前端需求转化为结构化AI编码提示词时激活。包括：
- 用户说「帮我写个提示词」「帮我写个AI能懂的描述」
- 拆解PRD为编码任务
- 不知道如何向AI描述开发任务

不触发场景

## trigger_negation
- 用户直接要求写代码（不是要提示词）
- 非前端任务（后端、运维、测试等）
- 用户已有完善提示词，只想微调一句话

设计要点：

•触发要具体（可识别的用户语言）

•不触发要明确（边界清晰，避免误触发）

三、设计 Input Contract

每种类型需要不同的信息。我们定义 必填字段：

类型	必填字段	为什么必填
PAGE	页面位置、功能描述、数据来源、参考页面	信息不足会导致代码无法生成
UI	设计稿链接/截图、目标位置、交互要求	UI还原需要视觉参考
API	接口地址/Yapi链接、调用场景、字段映射	接口对接需要契约
ARCH	现状问题、目标架构、约束条件	方案设计需要边界
REFACTOR	修改范围、修改规则、影响评估	批量操作需要范围控制
DEBUG	预期行为、实际行为、复现信息、相关代码	调试需要具体症状
PRD	PRD链接/内容、开发阶段、相关代码位置	需求分析需要上下文
MIGRATE	源组件位置、目标项目、迁移策略	迁移需要路径

核心原则：必填字段 =信息不足就无法生成有效提示词的字段。

四、追问机制设计

追问规则

## followup_rules
当用户描述需求后：
1. 从关键词推断任务类型
2. 检查 Input Contract 必填字段
3. 缺失字段必须追问
4. 追问格式：「关于【字段名】，请补充：...」

追问示例

用户输入：

帮我写个用户列表页的提示词

Skill 行为：

•识别：PAGE 类型（关键词”列表页”）

•检查必填：页面位置？数据来源？功能描述？

•追问：

检测到【PAGE】类型任务。请补充以下信息：

1. 关于【页面位置】：这个列表页放在哪个路由下？
2. 关于【数据来源】：用户数据从哪个接口获取？（Yapi链接或接口地址）
3. 关于【功能描述】：列表需要哪些字段？是否需要筛选/排序/分页？

五、暂停检查点设计

三个必须暂停的场景：

场景	暂停原因	Skill 行为
多类型组合	需确认优先级	「检测到多个任务类型（PAGE + API），请确认优先顺序」
必填项缺失	信息不足无法生成	「请补充必填信息后再继续」
生产环境操作	风险高需确认	「涉及生产环境修改，请确认是否继续」

六、编写 SKILL.md（关键片段）

文件结构

frontend-dev-prompt-craft/
├── SKILL.md              # 技能定义（核心）
├── skill-meta.json       # 元数据 + Baseline
├── test-prompts.json     # 测试用例
├── skill-issues.jsonl    # 问题记录
├── CHANGELOG.md          # 变更日志
├── LEARNINGS.md          # 学习沉淀
└── README.md             # 使用指南

SKILL.md 核心内容（关键片段）

# frontend-dev-prompt-craft

## description
将模糊的前端需求转化为结构化的AI编码提示词。支持 8 种任务类型：PAGE/UI/API/ARCH/REFACTOR/DEBUG/PRD/MIGRATE。

## trigger
用户需要将模糊的前端需求转化为结构化AI编码提示词时激活。

## Input Contract
| 类型 | 必填字段 |
|------|----------|
| PAGE | 页面位置、功能描述、数据来源、参考页面 |
| UI | 设计稿链接、目标位置、交互要求 |
| API | 接口地址、调用场景、字段映射 |
| ARCH | 现状问题、目标架构、约束条件 |
| REFACTOR | 修改范围、修改规则、影响评估 |
| DEBUG | 预期行为、实际行为、复现信息、相关代码 |
| PRD | PRD链接、开发阶段、相关代码位置 |
| MIGRATE | 源组件位置、目标项目、迁移策略 |

## workflow
1. 识别任务类型（从关键词推断）
2. 检查 Input Contract 必填字段
3. 追问缺失信息
4. 加载对应模板
5. 填充生成提示词
6. 自检输出
7. 交付

## output_contract
每条提示词必须包含：
- 任务类型标签（如 [PAGE]）
- 结构化需求描述
- 验收标准
- 可直接复制使用

七、编写 test-prompts.json（关键片段）

测试用例结构

[
{
"id":1,
"prompt":"帮我写个用户列表页的提示词",
"expected":{
"task_type":"PAGE",
"behavior":"追问页面位置、数据来源、功能描述"
}
},
{
"id":2,
"prompt":"这个Figma设计稿帮我还原成Vue组件",
"expected":{
"task_type":"UI",
"behavior":"追问设计稿链接、目标位置、交互要求"
}
},
{
"id":4,
"prompt":"接口返回500错误，帮我排查一下",
"expected":{
"task_type":"DEBUG",
"behavior":"追问预期行为、实际行为、复现信息、相关代码"
}
}
// ...共 8 个用例
]

设计要点：每个类型至少 1 个测试用例，覆盖追问行为。

八、建立 Baseline

第一次跑 Eval

Skill: frontend-dev-prompt-craft
Test Prompts: 8 个

Eval Result:
- Test Prompts: 8/8 passing (100%)
- Regression: 3/3 (100%)
- Capability: 3/3 (100%)

Total: 14/14 passing (100%)✅

Baseline 记录（skill-meta.json 关键片段）

{
"skill_name":"frontend-dev-prompt-craft",
"version":"0.1.0",
"maturity":"draft",
"baseline":{
"regression_pass_rate":"3/3 (100%)",
"capability_pass_rate":"3/3 (100%)",
"test_prompts_pass_rate":"8/8 (100%)",
"total":"14/14 (100%)"
}
}

九、设置 skill-issues.jsonl

问题记录格式

{
"date":"2026-06-09",
"skill":"frontend-dev-prompt-craft",
"task_type":"PAGE",
"symptom":"追问了不必要的字段（参考页面非必填）",
"expected":"只追问必填字段",
"severity":"medium",
"source":"首次使用",
"converted_to_eval":false,
"status":"open"
}

设计要点：

•每个 issue 记录一个问题

•converted_to_eval 标记是否转化为测试用例

•status 跟踪问题状态

十、使用 skill-engineering 脚手架验证

# 验证 Skill 结构
python validate-skill.py frontend-dev-prompt-craft

# 输出
✅ SKILL.md 存在
✅ skill-meta.json 存在
✅ test-prompts.json 存在
✅ skill-issues.jsonl 存在
✅ 目录结构完整

PASS: Skill 结构验证通过

十、实战回顾

从真实的提示词文件数据出发，让AI对所有的四个提示词文档进行分析提炼。

创建提炼过程，截图如下：

真实需求演示：

我找了个需求，如下图：

不使用技能，AI理解的需求：

使用技能，AI理解的需求，并生成的提示词：

从上述的提示词可以看出来，只有你补充一下接口和相关的数据枚举值，那么这个生成的提示词就是你本次需求开发的开发文档。

你不需要写太多的需求描述。只需要补充一下，这样的提示词就是真实需求的开发文档。

我的这个是网上找的截图，如果是真实的项目中，提示词还是会给出符合你当前项目的需求功能描述。

所以后续开发就直接让AI根据你的提示词进行开发就可以了。

真正做到了一句话就可以完成整个需求开发。

案例展示的功能，比较适合二次迭代项目。当然新的需求也是可以的。

创建过程回顾

步骤	做了什么	关键产出
1	回顾历史请求，识别任务类型	8 种类型分类
2	定义触发边界	trigger + trigger_negation
3	设计 Input Contract	8 种类型的必填字段表
4	设计追问机制	追问规则 + 示例
5	设计暂停检查点	3 个暂停场景
6	编写 SKILL.md	完整技能定义
7	编写 test-prompts.json	8 个测试用例
8	建立 Baseline	14/14 passing (100%)
9	设置 skill-issues.jsonl	问题记录机制
10	脚手架验证	PASS

关键要点

1.任务分类是起点：不清楚任务类型，就无法设计 Input Contract

2.必填字段是核心：信息不足就无法生成有效输出

3.追问是交互设计：缺失信息必须追问，不能假设

4.Baseline 是锚点：第一次跑 Eval 的结果，是后续迭代的基线

5.问题池是迭代基础：skill-issues.jsonl 记录发现的问题，后续转化为 Eval

附赠资产

资产	说明	获取方式
完整 SKILL.md	frontend-dev-prompt-craft 完整技能定义	GitHub链接
完整 test-prompts.json	8 个测试用例完整内容	GitHub链接
skill-issues 模板	问题记录 JSONL 格式模板	见下方

skill-issues.jsonl 模板

{"date":"YYYY-MM-DD","skill":"SKILL_NAME","task_type":"TYPE","symptom":"问题描述","expected":"期望行为","severity":"high/medium/low","source":"首次使用/迭代发现/用户反馈","converted_to_eval":false,"eval_id":null,"status":"open/resolved/converted"}

核心结论：从”凭感觉”到”有章法”

这篇文章走完了一个 Skill 从 0 到 1 的完整生命周期。

回头来看，Skill 工程化的核心不在于工具或格式，而在于思维方式的转变：

传统做法	工程化做法
“我觉得 AI 应该懂”	明确定义 8 种任务类型
“写越长越好”	必填字段 = 信息不足就无法生成的字段
“出了问题再说”	Baseline + Eval 提前拦截退化
“凭经验迭代”	skill-issues.jsonl 记录 → 转化为测试用例

五个关键认知：

1.任务分类是起点——不清楚 AI 要处理什么类型的请求，就无法设计有效的 Input Contract

2.必填字段是核心——每个字段背后都应该是”缺失就无法工作”的真实场景，而不是”可能有用”的想象

3.追问是交互设计的灵魂——AI 不应该猜测，缺失信息必须追问，这是 Skill 与用户之间的契约

4.Baseline 是迭代的锚点——第一次跑 Eval 的 100% 不是终点，而是后续所有修改的”退化检测线”

5.问题池是持续进化的基础——skill-issues.jsonl 不是摆设，每个 open 的问题都应该在下一次迭代中转化为 Eval 或修复

最后的话：

这个 frontend-dev-prompt-craft Skill 本质上是我差不多两年时间的 AI 编程经验的”数字化身”。

它不是凭空设计出来的，而是从 100+ 次真实请求中提炼、从反复踩坑中总结、从 Eval 验证中打磨出来的。

Skill 工程化不是”写完就结束”，而是”发布才开始”。

真正的价值在于后续的持续迭代：

每次发现问题 → 记录到 issues → 转化为 Eval → 修改 SKILL.md → 验证不退化。

这个闭环跑起来之后，你的 Skill 才会真正成为团队的”集体智慧沉淀”。

好的 Skill 不是写出来的，是”养”出来的。

文章来自：51CTO

作者yinhua

前言