Skills 仓库实战：用 article-prompts-to-skills 将文章提示词包转换为可复用的 Agent Skill-平芜编程栈

【免费下载链接】Skills

Agent skills for designers and builders using Codex, Claude, Cursor, and other AI coding agents

项目地址：https://gitcode.com/gh_mirrors/skills48/Skills

本指南围绕 Skills 仓库中的article-prompts-to-skills技能展开，它解决一类典型问题：把一篇文章、教程或提示词包中散落的交互灵感，系统性转化为一个个独立、可演示、可验证的 Agent Skill 包，而不是停留在散文式描述。读完本文，你将掌握从"源证据盘点 → 提取台账 → 可移植契约 → 打包 → 三层示例提示词 → 演示与验证 → 窄提交"的完整转换工作流，并能区分什么是值得做成技能的可复用能力、什么是应当丢弃的页面包装。

一、技能定位：保留行为，剥离品牌

article-prompts-to-skills是 Skills 仓库 agent-skills/codex/article-prompts-to-skills 目录下的一项 Codex 技能。其frontmatter中的 description 给出明确定位：

Convert an article, tutorial, or prompt pack into focused reusable AgentSkills, one independent capability per skill, with portable instructions, example prompts, working demos, preview screenshots, validation, gallery updates, and a narrow commit.

核心原则一句话概括：保留源材料的可用行为（mechanism），不保留源页面的品牌与布局（brand/layout）。它的适用场景是用户希望"把文章中的提示词、教程章节、设计模式、交互或工作流想法做成完整技能"，而不是继续以文字形式搁置。

配套的 agents/openai.yaml 定义了该技能在 Agent 侧的最小接入契约：

interface: display_name: "Article Prompts to Skills" short_description: "Package article prompts as validated skills" default_prompt: "Use $article-prompts-to-skills to turn this article prompt pack into complete reusable skills with examples, demos, previews, validation, and a narrow commit."

注意short_description控制在 25～64 字符之间，且默认提示词显式调用$article-prompts-to-skills，这是所有打包技能统一的 Agent 触发约定。

二、第一步：提取前的源证据盘点

在动手创建任何技能文件夹之前，SKILL.md 要求先完成五项检查：

通读仓库指令与完整源文章，掌握全部上下文；
运行git status --short，区分已有改动与本次任务，避免后续污染提交；
清点源材料中的每一条显式提示词、标题、示例、资产和验收标准，形成证据清单；
搜索现有SKILL.md，检查是否存在能力重叠的既有技能，重叠时优先更新而非新建；
如果源材料是原始 HTML 且尚未提炼出提示词，先调用上游技能$html-to-interaction-prompts（见 agent-skills/codex/html-to-interaction-prompts/SKILL.md），完成 HTML → 交互提示词文章的转换后，再回到本技能继续。

最后一条明确了两项技能的上下游关系：html-to-interaction-prompts负责"从 HTML 参考页提炼带截图证据的提示词文章"，article-prompts-to-skills负责"把提示词文章进一步拆解成可复用技能包"。禁止仅凭文章标题就臆造一整套技能家族——每个候选技能都必须能追溯到源证据。

三、第二步：建立提取台账（Extraction Ledger）

编辑任何文件之前，先建立一张工作表格，这是整个转换过程的事实基线：

Source prompt	Reusable capability	Keep	Remove	Skill name	Demo proof

配套 demo 给出了一个完整实例。源材料是 demo/input.md 中的虚构文章《Three small interactions that make an editorial archive feel alive》，含三条提示词：

Prompt 1 — Pointer lens：圆形镜头跟随指针在封面图上移动，揭示下方的另一版本；镜头需限制在媒体边界内、支持触摸按下拖拽手势、并为减少动效用户直接暴露替代图；
Prompt 2 — Reading rail：固定进度轨展示五章阅读进度，点击标记滚动到对应章节，活动标记须反映最接近视口中心的章节并保持键盘可访问；
Prompt 3 — Archive filters：为故事网格创建带动效的主题过滤器，过滤时保持文档焦点、播报可见故事数量，减少动效启用时避免重排动画。

对应的提取结果记录在 demo/expected-output.md 中：

Source prompt	Reusable capability	Proposed skill	Portable proof
Pointer lens	Bound-aware alternate-image reveal	`pointer-lens-reveal`	Pointer, touch, clamping, and reduced-motion states work in a standalone media panel
Reading rail	Chapter-aware page navigation	`chapter-progress-rail`	Active chapter, click navigation, keyboard focus, and responsive collapse are demonstrated
Archive filters	Accessible animated collection filtering	`accessible-collection-filters`	Focus preservation, live result count, filtering, and reduced-motion behavior are exercised

同时应用以下边界规则（Boundaries）：

一个技能只对应一个独立可复用行为，独立状态模型、输入方式和验收检查的技能不得合并；
只有强行拆分会使任一步骤不可用时才合并步骤；
既有技能的契约已覆盖该能力时，更新既有技能；
跳过装饰性、编辑性片段——它们不构成可复现的方法；
技能命名取"结果或机制"，绝不取自源文章名（因此是pointer-lens-reveal，而不是editorial-archive之类）。

上述例子的边界决策是：创建三个技能，而不是一个笼统的 "editorial interactions" 技能，同时绝不复制源页面本身。

四、第三步：提取可移植契约（Portable Contract）

可移植契约决定了"什么活下来、什么被删掉"，是技能能否跨主题复用的关键。

保留源材料的成功机制：

行为与状态迁移（behavior and state transitions）；
数据模型与参数默认值（data model and parameter defaults）；
时序、缓动、间距与响应式规则（timing, easing, spacing, responsive rules）；
可访问性、减少动效与键盘行为（accessibility, reduced-motion, keyboard behavior）；
性能约束与失败模式（performance constraints, failure modes）；
可证明结果的验收检查（acceptance checks）。

移除源材料专属的包装：

品牌名、营销文案与专有内容；
与能力无关的页面布局；
硬编码的调色板、资产与选择器；
不影响结果的偶发实现选择。

完成这一步后，结果必须能在不重写核心指令的前提下迁移到不同的主题、布局与视觉系统。以pointer-lens-reveal为例，需要保留的是：指针与触摸的输入对等（input parity）、媒体边界钳制、键盘对比控件、静态减少动效回退；需要删除的是源归档页的排版与美术方向。

五、第四步：打包每个技能（Package Every Skill）

每个新技能文件夹用已安装的skill-creator初始化器创建，然后补齐如下目录契约：

agent-skills/<category>/<skill-name>/ SKILL.md agents/openai.yaml references/ # 仅当需要详细可复用指南时 assets/ or scripts/ # 仅当工作流确实会复用它们时 demo/ index.html PROMPT.md preview.jpg input.md # 工作流类技能必需 expected-output.md # 工作流类技能必需

SKILL.md 的写作规范：

使用祈使句（imperative form）书写；
frontmatter 只保留name和description两个字段；
所有触发短语都放进 description（Agent 靠它决定何时调用该技能）；
操作步骤、约束、坑点与验证命令放在正文。

agents/openai.yaml 的写作规范（依据最终技能）：

使用人类可读的显示名（如display_name: "Article Prompts to Skills"）；
短描述保持在 25～64 字符之间；
默认提示词显式调用$skill-name。

六、第五步：编写三层示例提示词

每个技能的 demo/PROMPT.md 必须包含三个固定标题层级，让任何调用者都能快速上手：

Minimal prompt（最小提示词）

调用技能并提出一个明确结果：

Use $skill-name to add <capability> to <target>.

以pointer-lens-reveal为例：

Use $pointer-lens-reveal to reveal an alternate product finish inside a pointer-following lens.

Recreate the demo（复现演示）

描述参考体验、实现契约、交付物与验收检查，并明确要求保持本地化、自包含：

Use $pointer-lens-reveal to build a self-contained product-media panel with a circular pointer lens, boundary clamping, press-and-drag touch behavior, keyboard-accessible comparison controls, and a static reduced-motion fallback. Use original assets and art direction.

Remix prompt（混搭重写）

改变主题、内容、调色板与构图，同时保留机制、可访问性行为、响应式规则与性能契约：

Use $pointer-lens-reveal to adapt the mechanism to an architectural before-and-after. Change the content, lens scale, palette, and composition while preserving input parity, clamping, focus behavior, and performance constraints.

参考资料 references/example-packages.md 提供了三类校准示例：视觉类（如scroll-progress-timeline的三层提示词）、混合类（磁吸按钮 + WebGL hero + 定价网格 + 创始人引言 + 品牌页脚，其中正确结果可能是"五个提示词只产出两个技能"）、以及工作流类（截图、证据映射、提示词写作、文章插入构成一次完整交接时打包为一个工作流技能）。

七、第六步：构建证据，而非装饰（Build Proof, Not Decoration）

每个 demo 必须是原创、自包含、可检查的实现：

首屏即演示核心机制；
使用真实感内容，而不是 "demo card" 之类的占位标签；
控件只用于暴露有意义的状态；
支持 390px～1440px 的布局；
使用语义化 HTML 与可见焦点状态；
动效类作品提供减少动效行为；
依赖保持本地化，除非技能必需否则避免构建步骤；
非可视化工作流使用input.md与expected-output.md作为证据。

绝不把截图当作实现本身——HTML 演示必须真实可运行。以配套 demo 的 index.html 为例，它是一个 "Prompt Foundry" 证据优先工作台：左侧源文章面板列出三条提示词按钮（aria-pressed标记选中态），中间是转换箭头，右侧输出面板是三个技能卡片（role="tablist"的可访问页签），详情区展示选中技能的核心描述、示例提示词与 "Complete package" 验收清单。其实现要点包括：ArrowLeft/ArrowRight键在技能卡片间循环切换、tabindex随选中态在 0/-1 间切换以维护页签焦点、@media (prefers-reduced-motion: reduce)下将过渡时长压至 0.001ms、以及 760px 断点下单列重排——这些细节本身就是"可访问性契约"的活教材。

八、第七步：验证完整包（Validate the Complete Package）

验证强度与工件规模成正比，完整流程共八步：

对每个新增/变更技能运行 skill creator 的quick_validate.py；
运行仓库级 demo 验证与定向语法检查；
在允许的浏览器中以桌面与移动尺寸打开每个 demo；
演练主要交互、键盘焦点与减少动效路径；
确认控制台无报错；
以仓库统一尺寸捕获真实浏览器预览图；
重建 demo 与截图画廊，再次验证；
扫描变更文件中的密钥、令牌、私有路径与私有客户数据。

明确的红线是：禁止仅凭静态文件检查就声称完成了视觉或交互验证——必须真实地运行并操作过 demo。

九、第八步：只提交任务本身（Commit Only the Task）

提交阶段保持窄提交纪律：

只暂存新技能文件夹及其所需的画廊文件；
提交前审阅git diff --cached --stat与git diff --cached；
预先存在的脏文件保持不动；
最终报告必须包含：源到技能的映射、示例提示词与 demo 路径、验证与浏览器证据、提交哈希、以及留在提交之外的无关联脏文件清单。

十、失败模式自查清单

SKILL.md 在结尾列出七类典型失败模式，可作为交付前的自查表：

Page clone（页面克隆）：复制源布局而非提取机制；
Mega-skill（巨型技能）：把多条独立提示词合并成一个含糊的技能；
Micro-fragments（碎片化）：把每句话都做成技能，却无可复用行为；
Theme lock-in（主题锁定）：硬编码源材料的调色板、资产或文案；
Prompt-only package（只有提示词）：缺少可运行 demo 与预览图；
Fake proof（假证据）：未实际操作交互就声称已验证；
Dirty-tree spillover（脏树溢出）：误暂存无关修改或生成文件。

十一、可移植性质量测试

一个技能包何时才算"可移植"？references/example-packages.md给出了五条验收标准，另一名 Agent 应当能够：

从 description 中识别触发条件；
在完全看不到源文章的情况下把方法应用到新主题；
仅凭指令与示例复现关键行为；
依据明确的验收检查验证结果；
区分机制与 demo 的美术方向。

结语：一条可复制的方法链

从 demo/input.md 的虚构编辑归档文章，到 demo/expected-output.md 中三个边界清晰的技能包，article-prompts-to-skills展示了将设计文章"能力化"的完整路径：证据盘点 → 提取台账 → 可移植契约 → 标准打包 → 三层提示词 → 真实演示 → 分级验证 → 窄提交。这套方法论既不依赖具体文章，也不依赖具体视觉风格，因此可以反复应用于数据看板、支持工作流、动效研究等任何提示词来源——这正是 Skills 仓库中"技能是可复用能力包"这一设计哲学的落地示范。