1. 项目概述从“一次性生成”到“可复用模板”的思维跃迁如果你和我一样在过去一年里深度体验过各种AI代码生成工具那你一定对那种“瞬间生成一个漂亮网页”的兴奋感不陌生。输入一段描述几秒钟后一个看起来相当不错的页面就摆在你面前。这种被称为“Vibe Coding”或“氛围编程”的方式确实让人着迷。但兴奋过后现实问题接踵而至生成的代码结构混乱想微调一个按钮样式却无从下手下次想做个类似页面又得从头描述一遍风格还无法统一最要命的是这些“一次性”的产出物根本无法沉淀为你的资产更别提团队协作了。这正是我开发agent-skill-lecture-builder这个项目的初衷。它不是一个简单的页面生成器而是一套完整的“模板化工作流”解决方案。核心思想是将AI从“随机创作者”转变为“结构化执行者”。我们不再依赖AI去凭空创造整个页面而是让它基于我们预先定义好的、高质量的模板和规则去填充内容、执行构建。这样一来生成的结果是可控的、风格一致的、并且完全可维护的。这个项目本质上是一个课程讲义网页的静态站点生成器但它被深度集成到了AI工作流中。你只需要提供课程主题或原始的Markdown讲稿通过一个封装好的“Agent Skill”智能体技能AI就能自动帮你完成从内容结构化、配置生成、页面构建到预览部署的全过程。最终产出的不是一个黑盒而是一个标准的、由Markdown和YAML配置文件驱动的静态网站目录你可以用Git管理可以手动调整可以无限次复用。2. 核心设计思路为何选择“模板Agent”的双引擎架构在构思这个项目时我评估过几种主流方案。最简单的是直接用AI生成完整的HTML/CSS/JS但正如开头所说这不可维护。另一种是使用现成的静态站点生成器如Hugo、Jekyll但它们的学习曲线和配置复杂度又让快速生成变得不那么“AI友好”。因此我设计了一个折中但更强大的“双引擎”架构模板引擎 Agent执行引擎。2.1 模板引擎定义输出的“骨”与“肉”模板引擎负责将结构化的内容Markdown和配置YAML渲染成最终的HTML页面。它的核心是一个高度语义化的Markdown扩展语法和一套对应的HTML/CSS模板。为什么选择扩展Markdown而不是纯HTML内容与样式分离讲师或内容创作者可以专注于撰写讲义内容无需关心复杂的HTML标签和CSS类名。#代表章节代表引言[bonus]代表弹窗直观易懂。AI友好Markdown是AI最擅长理解和生成的格式之一。让AI根据规则生成或转换Markdown比让它直接生成正确且美观的HTML要可靠得多。可维护性纯文本的Markdown文件可以用任何编辑器打开易于版本控制Git也方便进行批量查找替换等操作。项目中的reference/base.html文件就是整个页面的骨架模板。它使用了Nunjucks这类模板引擎语法定义了页面的整体结构Header, Hero, Content, Footer并预留了插槽来注入从Markdown解析出的组件和从YAML读取的配置数据。这种设计确保了无论内容如何变化页面的基础样式和布局始终保持一致。2.2 Agent执行引擎串联工作流的“大脑”与“双手”模板定义了“做什么”而Agent执行引擎定义了“怎么做”以及“谁来做”。在这个项目中它特指与AI助手如ChatGPT Codex模式集成的自动化脚本和工作流。Agent Skill 是什么你可以把它理解为一个封装好的、可被AI调用的“宏”或“插件”。当你在AI对话中输入“帮我生成课程页面”时AI识别到这个意图就会自动触发course-page-generator这个Skill。这个Skill背后是一系列定义好的步骤内容处理如果用户只给了主题AI会先扮演专家角色生成结构化的content.md。如果给了原始讲稿AI会将其清理、格式化转换成符合项目语法的content.md。配置生成AI会根据内容智能地生成或补充config.yaml文件例如提取核心关键词作为页面标题和副标题。执行构建AI自动在后台调用build.mjs脚本将上两步的产出物结合模板生成index.html。生成预览图调用generate-og.mjs利用Puppeteer无头浏览器打开生成的页面并截图生成用于社交媒体分享的OG Image。启动服务最后调用dev.mjs启动本地开发服务器并自动在浏览器中打开预览。这个设计的精妙之处在于它将复杂的、多步骤的构建过程简化成了一个自然语言指令。用户无需记忆任何命令无需手动操作文件AI成为了整个工作流的协调者和执行者。这极大地降低了技术门槛让内容创作者能专注于创作本身。2.3 双层配置系统兼顾统一与灵活任何需要批量生产的内容系统都会面临“统一品牌”和“个性定制”的矛盾。为此我设计了一个两层的配置合并系统。全局配置 (config/global.yaml)存放“不变”的信息。比如讲者的姓名、头像、个人简介、社交媒体链接、页脚的版权信息等。这些信息通常在所有课程页面中都是一致的。把它放在全局就避免了在每个课程目录里重复填写。课程配置 (course-dir/config.yaml)存放“变化”的信息。比如本门课程的标题、Hero区域的副标题、特定的开场/结束金句等。这里只需要填写需要覆盖或新增的字段其余全部从全局配置继承。技术实现上采用的是“深度合并(deep merge)”。对于普通对象课程配置的字段会覆盖全局配置的同名字段。但对于数组如socials社交链接策略是“替换”而非“合并”即课程的socials会完全取代全局的socials。这是因为社交链接通常要么全用全局的要么为某门课程指定一套全新的很少需要混合。此外配置文件的查找机制也很智能。build.mjs脚本会从当前课程目录开始向上递归查找最多4层父目录寻找config/global.yaml。这意味着你可以把全局配置放在项目根目录也可以根据课程分类在不同层级的子目录里放置不同的全局配置实现了配置的“作用域”管理非常适合管理多系列课程。3. 从零开始手把手创建你的第一门课程理论说得再多不如动手做一遍。让我们抛开AI先纯手动走一遍流程这能帮你彻底理解整个系统是如何运作的。假设我们要创建一门名为my-first-ai-course的课程。3.1 环境准备与项目初始化首先你需要一个基础环境。确保你的系统已经安装了Node.js (版本16或以上)和npm。# 1. 克隆或下载项目 git clone 项目仓库地址 cd agent-skill-lecture-builder # 2. 安装项目依赖 # 注意因为OG图片生成依赖puppeteer它可能会下载Chromium网络环境不好时可能需要耐心等待或配置镜像。 npm install安装完成后你的项目结构应该和文档中描述的一致。重点关注两个目录config/用于放全局配置example/是一个现成的课程示例。3.2 创建课程目录与核心文件我们不修改示例而是新建自己的课程。# 在项目根目录下创建课程文件夹和资源子目录 mkdir -p my-first-ai-course/assets接下来创建两个核心文件content.md和config.yaml。第一步编写课程内容 (my-first-ai-course/content.md)你可以从最简单的开始复制下面的示例。注意我们使用了项目约定的扩展语法比如# LABELTITLE的章节格式以及[bonus]区块。# 核心概念什么是Agent Skill 将复杂操作封装成一个“技能”让AI像调用函数一样执行它。 在这一章我们将拆解Agent Skill的核心思想。它不仅仅是自动化脚本更是一种与AI协同工作的范式转变。 ## 传统脚本 vs. Agent Skill ### 传统脚本 你需要记住命令、参数和正确的执行顺序。 bash node ./some-script.js --input file.md --output dir/ Agent Skill你只需要用自然语言描述你的目标。帮我为这份讲稿生成一个课程页面。AI理解你的意图自动选择并执行正确的技能。关键优势[flow]降低认知负荷无需记忆复杂命令。提升交互自然度用说话的方式指挥电脑。实现复杂工作流单个指令可触发一连串动作。 [/flow][summary] Agent Skill的本质是“意图到执行”的桥梁。它通过预定义的能力描述让AI能够可靠地完成特定领域的复杂任务将人类从繁琐的操作细节中解放出来。 [/summary][bonus title 设计心得] 在设计course-page-generator这个Skill时我刻意将“内容生成”和“页面构建”分开。内容生成可以依赖AI的创造力根据主题自由发挥。页面构建必须严格遵循模板和规则确保输出稳定。这种“松耦合”设计使得Skill更加健壮。即使未来更换AI模型或者完全手动编写Markdown构建部分依然可以完美工作。 [/bonus]**第二步创建课程配置 (my-first-ai-course/config.yaml)** 这个文件用于覆盖全局设置定义本课程特有的信息。 yaml page: title: AI智能体技能开发入门 badge: 实战教程 hero_title: 告别一次性代码br构建可复用的AI工作流 subtitle: 掌握模板思维将你的AI创作转化为可持续资产 quotes: opening: text: 最好的工具是那些用完后让你变得更强大的工具。 closing: text: 现在你不仅拥有了一个页面更拥有了一套生产页面的方法。注意这里没有写instructor或footer信息因为它们会从config/global.yaml继承。你需要先确保全局配置已正确设置。如果还没有可以在项目根目录创建config/global.yaml参考项目文档中的示例填写你的个人信息。3.3 执行构建与预览有了内容和配置现在可以手动触发构建过程看看效果。# 在项目根目录执行构建命令指向你的课程文件夹 node .agents/skills/course-page-generator/scripts/build.mjs my-first-ai-course如果一切顺利你会在my-first-ai-course/目录下看到新生成的index.html文件。用浏览器直接打开它就能看到初步的静态页面了。不过更推荐使用开发服务器模式它支持热重载# 启动开发服务器默认端口3000 node .agents/skills/course-page-generator/scripts/dev.mjs my-first-ai-course # 或者指定端口 node .agents/skills/course-page-generator/scripts/dev.mjs my-first-ai-course --port 8080执行此命令后脚本会自动先运行一次构建然后启动一个本地服务器并自动在浏览器中打开页面。接下来如果你修改了content.md、config.yaml甚至全局的global.yaml或模板文件保存后页面会自动刷新。这个功能对于内容创作和样式调试来说极其高效。3.4 生成社交媒体预览图在分享课程链接到社交媒体时一张精美的预览图能极大提升点击率。项目内置了OG图生成脚本。node .agents/skills/course-page-generator/scripts/generate-og.mjs my-first-ai-course这个脚本会在后台启动一个无头浏览器。访问你刚生成的课程页面通常是http://localhost:3000如果dev服务器在运行的话。对页面进行截图并裁剪成1200x630像素的标准OG图像尺寸。将图片保存为my-first-ai-course/assets/og-{timestamp}.jpg。你需要确保在运行此命令前课程页面可以通过一个URL访问无论是dev服务器还是已经部署到线上的地址。你可以在课程的config.yaml中通过seo.image字段指定这张图的永久链接这样社交媒体爬虫就能正确抓取。4. 深度解析Markdown扩展语法的实战应用与原理项目的易用性很大程度上得益于一套设计精巧的Markdown扩展语法。它们不是简单的标记而是对应着一个个具有特定样式和交互的UI组件。理解它们你就能写出既美观又结构清晰的讲义。4.1 章节与卡片构建内容的清晰骨架基础Markdown的标题###在这里被赋予了更强的语义。# LABELTITLE这是顶级章节。LABEL部分如 核心概念会以徽章的形式展示在标题左侧非常适合用于标识章节类型如概念、实操、案例。这个语法是整个内容目录导航栏生成的依据。 lead text如果一段引用块紧跟在#章节标题行之后它不会被渲染成普通的引用块而是会成为该章节的“引言”或“摘要”使用特殊的样式突出显示给读者一个章节概览。### Title三级标题有一个特殊用途。当你在标题前加入一个Emoji如 、、⚠️ 等它会被渲染成一个“卡片”组件。卡片具有独立的背景、边框和内边距视觉上从正文中剥离出来非常适合用于封装一个完整的小知识点、一个工具介绍或一个注意事项。在背后构建脚本会解析这些标题不仅用于渲染还会自动提取#级标题的ID和文字生成页面右侧或移动端顶部的导航栏Nav。这意味着你几乎不需要手动维护导航菜单内容结构就是导航结构极大减少了维护成本。4.2 特色内容区块让表达形式更丰富除了标准Markdown项目定义了几种自定义区块用[tag]...[/tag]的形式包裹。[flow]...[/flow]流程步骤区块。内部的列表项会被渲染成带有编号和连接线的垂直时间轴样式直观地展示操作步骤或事件顺序。[summary]...[/summary]总结卡片。通常放在章节末尾内容会被放在一个视觉上醒目的总结框内帮助读者回顾重点。[tags]...[/tags]标签组。内部用空格分隔的词汇会被渲染成不同颜色green, orange, purple, blue的小标签常用于标注技术栈、关键词、状态等。[image-text]...[/image-text]图文并排版。这是非常实用的一个功能。你可以在里面放一张图片和一段文字通过position和width属性控制左右布局和图片宽度。在移动端会自动堆叠响应式体验很好。[bonus title...]...[/bonus]扩展内容弹窗。这是实现渐进式披露的好方法。将一些扩展阅读、深度分析、幕后花絮放在这里页面上只会显示一个按钮点击后以模态框形式弹出内容保持主内容的简洁。4.3 代码与提示块针对技术内容的优化对于技术教程代码展示和操作提示至关重要。标准代码块使用language语法支持语法高亮。提示块使用prompt [label...]语法。这会被渲染成一个模拟终端样式的区块label属性会显示为终端的标签头如userhost ~ $非常适合展示命令行操作或AI对话中的Prompt示例增强场景感。洞察框使用 **Bold Title**后跟内容的格式。这会被渲染成一个带有图标和边框的提示框用于强调重点、警告或技巧。4.4 媒体嵌入无缝集成视频与图片图片标准Markdown语法![alt](src)被增强。图片会自适应居中并且alt文字会自动成为图片下方的说明文字figcaption。结合[image-text]区块可以轻松实现图文混排。YouTube视频通过[youtube id...]语法嵌入。脚本会自动生成响应式的16:9视频iframe。考虑到可访问性和打印友好性在打印样式下iframe会被替换为视频的直接链接。一个综合示例# ️ 实战配置你的第一个Skill 让我们通过一个具体例子将理论付诸实践。 ### 步骤一定义Skill清单 首先在 .agents/skills/ 目录下为你的Skill创建一个文件夹例如 deploy-to-server。 [flow] 1. 创建 skill.yaml 文件描述技能的名称、能力和触发词。 2. 编写核心执行脚本 main.mjs。 3. 添加说明文档 README.md。 [/flow] ### 步骤二编写执行脚本 你的脚本需要能够处理AI传递的参数。 javascript // main.mjs 示例片段 export async function run({ input, context }) { const { projectPath } input; console.log(开始部署项目: ${projectPath}); // ... 你的部署逻辑 }关键点脚本必须导出run函数AI会将用户输入解析为参数传入。 步骤三测试与集成使用CLI工具本地测试你的Skill。node .agents/skills/deploy-to-server/main.mjs --input {projectPath: ./my-course}[image-text positionright width45]一个完整的Skill通常包含三部分元数据YAML、执行逻辑JS、文档MD。清晰的分离有助于长期维护。 [/image-text][summary] 构建一个可靠的Agent Skill关键在于清晰的接口设计和完善的错误处理。让AI知道它能做什么以及在出错时如何向用户反馈。 [/summary][bonus title 项目结构建议] 对于复杂的Skill我建议采用如下结构deploy-to-server/ ├── skill.yaml # 技能定义 ├── main.mjs # 主入口 ├── utils/ # 工具函数 │ └── ssh-helper.mjs ├── configs/ # 配置模板 │ └── nginx-template.conf └── README.md # 开发文档[/bonus]通过组合使用这些语法元素你可以创造出信息密度高、层次分明、阅读体验极佳的技术讲义。 ## 5. 与AI协同将Skill集成到你的智能体工作流 手动操作展示了项目的全部能力但真正的威力在于与AI的集成。这里以兼容OpenAI ChatGPT Code Interpreter或类似代码执行环境的AI助手为例。 ### 5.1 配置AI环境以识别Skill 要让AI能调用你的Skill你需要确保AI能够访问到这些技能定义。通常有两种模式 **模式一本地编辑器模式** 你可以在本地IDE如VSCode中打开项目并安装能连接AI助手的插件。这些插件通常允许你将整个工作区或特定目录“暴露”给AI。AI在分析项目结构后就能发现 .agents/skills/ 目录下的技能并在对话中提供相应的建议或自动触发。 **模式二终端CLI模式** 有些AI工具允许你运行一个本地代理服务器AI通过这个服务器执行命令和访问文件。你需要确保代理服务器的工作目录是你的项目根目录。这样当你说“生成课程页面”时AI就能直接找到并执行 course-page-generator 技能背后的脚本。 **实操心得**无论哪种模式第一次使用时最好主动告诉AI你的项目结构。你可以发送一条消息如“在这个项目中我定义了一个名为 course-page-generator 的Agent Skill用于从Markdown生成课程网页。它的入口脚本位于 .agents/skills/course-page-generator/scripts/build.mjs。” 这能帮助AI更快地建立上下文准确调用。 ### 5.2 两种核心使用场景详解 项目文档提到了两种主要场景我们深入看一下AI在其中扮演的角色。 **场景一从主题到完整页面AI作为内容创作者** 你输入“扮演一位资深前端工程师设计一门‘现代CSS布局实战’的课程讲义并生成网页。” 1. **AI理解与规划**AI首先理解你要扮演的角色和课程主题。它会规划课程大纲可能包含Flexbox、Grid、容器查询等章节。 2. **调用Skill**AI识别出“生成网页”这个任务匹配到 course-page-generator 技能。它知道这个技能需要 content.md 和 config.yaml。 3. **生成内容**AI开始撰写结构化的 content.md它会自觉运用 # LABELTITLE, [flow], [summary] 等扩展语法。同时它会根据内容提炼出课程标题、副标题生成 config.yaml。 4. **执行构建**AI在后台运行 build.mjs 脚本传入它刚刚创建的课程目录。 5. **反馈结果**AI将生成的HTML页面内容或本地预览链接提供给你并告知你文件已生成在哪个目录。 **场景二从讲稿到美化页面AI作为内容格式化助手** 你输入“帮我把这段混乱的会议笔记转换成结构化的课程页面。” 然后粘贴一大段文本。 1. **AI分析与结构化**AI读取你的原始笔记识别其中的核心观点、步骤、代码片段。它会进行重写、分段并套用项目约定的Markdown语法。 2. **查漏补缺**AI可能会发现缺少开场总结或章节标签它会主动补充。例如为一系列操作步骤加上 [flow] 区块。 3. **生成配置**AI从内容中提取关键信息生成或补充 config.yaml。 4. **调用Skill构建**后续步骤与场景一相同。 **在这个过程中你的角色从“写代码的人”变成了“提需求的产品经理”和“内容质量的审核者”**。你关注的是课程的核心逻辑、知识点的准确性以及最终呈现的效果而将格式转换、文件创建、命令执行等重复性工作交给了AI。 ### 5.3 调试与优化AI输出 AI并非总是完美的尤其是在初期它可能不熟悉你自定义的语法。 * **问题1AI不使用扩展语法**。它可能生成标准的 ### 标题而不是 ### Title 卡片格式。 * **解决**在指令中明确要求。例如“请使用 ### 工具名 的格式来介绍每个工具使其渲染为卡片。” 或者你可以把 reference/components.md 的内容发给AI让它学习这套规范。 * **问题2生成的导航不理想**。AI可能把一些不该作为导航的标题用了 #。 * **解决**手动调整 content.md。导航只由 # 级标题生成确保每个 # 都是一个主要的课程模块。 * **问题3配置项不全或错误**。 * **解决**AI生成的 config.yaml 是一个很好的起点但你通常需要手动检查和微调特别是 hero_title、subtitle 和 quotes这些对页面氛围影响很大。 一个高效的协作模式是**让AI完成初稿然后你进行精细化的手动调整**。由于所有产出都是纯文本文件你可以在喜欢的编辑器里轻松修改。调整后运行 dev.mjs 即可实时看到效果。 ## 6. 部署与分享让你的课程上线 生成静态HTML只是第一步你还需要把它放到网上才能分享给他人。这里推荐使用 **GitHub Pages**因为它免费、简单且与代码仓库天然集成。 ### 6.1 部署到GitHub Pages 假设你的项目已经是一个GitHub仓库。 1. **构建产物**确保你的课程目录下已经生成了 index.html 和相关的 assets如图片、OG图。 2. **配置GitHub Pages源**在仓库的 Settings - Pages 页面将 Source 设置为 **GitHub Actions**。 3. **创建工作流文件**在项目根目录创建 .github/workflows/deploy.yml 文件。这个工作流会在你推送代码时自动构建并部署。 yaml name: Deploy to GitHub Pages on: push: branches: [ main, master ] # 在推送到主分支时触发 workflow_dispatch: # 允许手动触发 permissions: contents: read pages: write id-token: write jobs: build-and-deploy: runs-on: ubuntu-latest steps: - name: Checkout uses: actions/checkoutv4 - name: Setup Node.js uses: actions/setup-nodev4 with: node-version: 18 - name: Install dependencies run: npm ci # 使用ci确保依赖锁一致 - name: Build all courses run: | # 假设你的所有课程目录都在根目录下且不以点开头 for dir in */; do if [[ -f $dir/content.md ]]; then echo Building course: $dir node .agents/skills/course-page-generator/scripts/build.mjs ${dir%/} fi done # 注意这个简单循环假设每个课程目录都直接包含content.md。 # 更复杂的项目结构需要调整查找逻辑。 - name: Setup Pages uses: actions/configure-pagesv4 - name: Upload artifact uses: actions/upload-pages-artifactv3 with: path: . # 上传整个项目根目录因为生成的index.html在各个课程子目录里 - name: Deploy to GitHub Pages uses: actions/deploy-pagesv4这个工作流做了几件事安装依赖、遍历所有包含content.md的子目录并构建课程、将整个构建后的项目上传为制品最后部署到GitHub Pages。访问页面部署成功后你的页面地址通常是https://你的用户名.github.io/仓库名/课程目录名/。例如my-first-ai-course课程的访问地址就是https://yourname.github.io/agent-skill-lecture-builder/my-first-ai-course/。6.2 自定义域名与SEO优化如果你有自己的域名可以将其指向GitHub Pages并在仓库设置中配置自定义域名提升专业度。此外为了获得更好的搜索引擎收录和社交分享效果请务必完善课程config.yaml中的seo部分seo: title: AI智能体技能开发入门 - 你的品牌 description: 本课程教你如何利用模板思维和Agent Skill将AI生成的内容转化为可维护、可复用的资产告别一次性代码。 image: https://yourdomain.com/path/to/og-image.jpg # 使用绝对路径 url: https://yourdomain.com/path/to/course/确保image指向的OG图片链接是公开可访问的。运行generate-og.mjs脚本后你需要将生成的图片也一并提交到仓库并使用正确的URL。6.3 版本管理与协作由于所有课程内容都是Markdown和YAML文件你可以轻松地使用Git进行版本管理。内容迭代每次对讲义的修改都是一个commit你可以清晰地看到课程的演变历史。团队协作团队成员可以克隆仓库在各自分支上撰写或修改课程通过Pull Request进行合并审核内容变更。多版本并存你可以通过Git分支来管理课程的不同版本如入门版、进阶版。7. 常见问题排查与进阶技巧在实际使用中你可能会遇到一些问题。这里记录了一些常见坑点及其解决方案。7.1 构建与开发阶段问题问题运行npm install时puppeteer下载Chromium失败或极慢。原因puppeteer默认会下载一个Chromium浏览器用于OG截图网络环境可能导致下载失败。解决使用镜像源设置环境变量PUPPETEER_DOWNLOAD_HOSThttps://npmmirror.com/mirrors。如果你确定不需要OG截图功能可以跳过puppeteer安装。但更推荐安装因为它是生成分享预览图的关键。在CI/CD环境中如GitHub Actions通常自带Chromium可以通过环境变量PUPPETEER_SKIP_CHROMIUM_DOWNLOADtrue跳过下载然后通过apt-get等系统包管理器安装。问题运行dev.mjs或build.mjs时出现模板语法错误。原因最可能是content.md中自定义语法标签没有正确闭合例如[flow]没有对应的[/flow]或者Markdown格式有误如列表缩进不正确。解决仔细检查报错位置附近的Markdown语法。构建脚本会给出相对准确的行号提示。确保所有自定义区块标签都是成对出现且正确嵌套。问题页面样式错乱或自定义组件没有正确渲染。原因可能是构建过程中模板文件 (base.html) 或全局CSS/JS资源路径引用错误。解决检查构建命令指定的课程路径是否正确。检查config/global.yaml中引用的资源路径如头像图片是否存在。在浏览器中按F12打开开发者工具查看Console和Network标签页确认是否有404错误找不到CSS/JS文件。7.2 与AI协作问题问题AI无法识别或触发我定义的Skill。解决确认暴露路径确保你的AI工具如ChatGPT Code Interpreter或本地AI助手插件有权限访问到.agents/skills/目录。清晰描述直接告诉AI“在这个工作区中我有一个预定义的Skill路径是.agents/skills/course-page-generator请你查看它的skill.yaml文件来了解如何使用它。”手动触发如果AI无法自动触发你可以手动指示它执行命令“请运行node .agents/skills/course-page-generator/scripts/build.mjs my-course来构建我的课程页面。”问题AI生成的Markdown不符合我的扩展语法规范。解决这是预期之中的。你需要“训练”AI。最有效的方法是提供范例。将reference/components.md文件的内容和一份写好的content.md示例发给AI并说明“请严格按照这种格式和语法来生成课程内容。” 在后续的指令中你也可以反复强调“请使用[flow]区块来列举步骤”“请用### 开头表示工具卡片”。7.3 样式与功能定制项目提供的模板和样式是开箱即用的但你可能想进行个性化定制。修改全局样式主要的样式定义在reference/base.html模板文件内的style标签中。你可以修改这里的CSS来改变字体、颜色、间距等全局样式。添加自定义组件如果你想增加新的Markdown扩展语法例如一个[warning]警告框你需要在构建脚本build.mjs中修改Markdown解析逻辑将新语法转换为对应的HTML结构。在base.html的CSS中添加新组件对应的样式。更新components.md文档说明新语法的用法。集成分析工具在base.html的head部分你可以添加Google Analytics或Umami等统计代码的脚本标签这样所有生成的页面都会自动包含它。7.4 性能与规模化建议当课程数量非常多时一些简单的优化可以提升体验。增量构建目前的脚本是每次构建全部课程。你可以修改构建脚本只构建发生变化的课程目录这需要结合Git来判断文件变更。资源优化确保assets目录下的图片经过压缩可以使用工具如Sharp进行自动化。如果课程中有大量高清图片考虑使用懒加载。CI/CD优化在GitHub Actions工作流中可以利用缓存来加速npm install和puppeteer的安装过程。这个项目的魅力在于它始于一个解决个人痛点的工具但因其清晰的架构和文本驱动的本质最终演变成了一套可扩展、可协作、并能与AI深度协同的内容生产系统。它教会我们的不仅是技术更是一种思维模式在AI时代我们的目标不应是成为更快的打字员而是成为更高效的设计师和指挥家让AI去执行那些可重复的、结构化的任务而我们则专注于创造、设计和决策。