如果你已经用通用 Prompt 让 AI 写过 FastAdmin 插件大概率经历过这种场面AI 生成了非常完整的文件列表看起来每个文件都有内容但装进 FastAdmin 后不是菜单不显示就是控制器 404或者 SQL 里带了一堆你用不到的表。问题不在 AI 能力而在于你给它的“上下文”太薄了。FastAdmin 不是一个“装了 ThinkPHP 就能猜出来”的项目它的目录约定、插件机制、权限规则、后台脚本加载方式都需要足够精确的知识输入。通用 Prompt 能写 PHP 代码但写不出一个真正能被 FastAdmin 识别、安装、使用的插件。我采用的方案不是反复写更长的 Prompt而是开发一个 FastAdmin 专属的 AI Skill。把插件开发规范、目录模板、安装约束、易错点全部沉淀在 Skill 里。之后我给 AI 下达“开发一个插件”的任务它会先按 Skill 里的规则检查约束再生成代码。整个过程基本靠“聊天”完成从提出需求到拿到一份可以安装验证的插件大约 5 分钟。本文就把这个思路、完整落地过程和踩坑清单整理出来。1. 为什么要给 FastAdmin 单独做一个 Skill1.1 通用 AI 不懂 FastAdmin 的“隐性规则”FastAdmin 是一个基于 ThinkPHP 的后台快速开发框架它最大的优点是“快”通过命令行生成 CRUD、自动创建控制器/模型/JS、自动挂菜单、自动写权限节点。但它的快建立在大量约定之上。你让 AI 写一个“广告管理插件”如果不告诉它 FastAdmin 的插件结构它会按照普通 ThinkPHP 控制器的思路写最后得到一份“能跑但不是 FastAdmin 插件”的代码。典型的问题包括插件目录该放在addons/{插件名}下而不是app/admin/controller下。安装/卸载脚本需要处理数据表和菜单规则而不是只建表。后台需要 Token 验证、权限节点、日志记录AI 很容易漏掉。前端 JS 不是普通 jQuery 文件需要按 FastAdmin 方式加载。数据库字段类型、软删除、时间字段等要符合 FastAdmin 习惯。这些规则官网文档有但 AI 训练数据里的 FastAdmin 知识并不够精确。它遇到拿不准的内容时会“自信地编”这是最危险的地方。1.2 Skill 和普通 Prompt 的本质区别如果把 Prompt 比作给 AI 的“口头任务”Skill 更像是给 AI 的“岗位手册 操作流程 质检清单”。普通 Prompt 的问题是信息量有限写不了太多约束。写在聊天里每次都要重新复述。AI 遇到冲突时没有规则可依。无法沉淀和复用。Skill 把这些变成结构化文件AI 看到任务后会先加载技能文件按照里面的步骤、规则、示例去执行。它不会每次都“重新发明轮子”而是会重复使用你已经验证过的模式。一句话普通 Prompt 是告诉 AI“做什么”Skill 是告诉 AI“用什么标准、按什么流程、避开哪些坑来做”。1.3 本文能帮你解决什么读完这篇文章你可以自己画出这样一条实践路径理解 AI Agent Skill 的目录结构和写法。给 AI 定义一个 FastAdmin 插件开发专家角色。用自然语言提出插件需求让 AI 生成文件层次清晰、可安装的插件。知道怎么验证 AI 生成的结果而不是盲信输出。避开我在实际开发中遇到的 6 类常见坑。2. AI Agent Skill 是什么它是怎么工作的2.1 一个 Skill 的本质Skill 本质上是一个“场景化知识包”通常由描述文件、规则说明、示例代码、检查清单组成。它被放在 AI Agent 能够读取的目录里当 Agent 发现当前任务匹配某个 Skill 的说明时就会自动把这个技能文件读入上下文并按文件里的流程工作。这种设计对开发任务特别有价值。因为开发不是“一句话生成全部代码”而是“理解需求 - 查规范 - 设计结构 - 写代码 - 自检 - 交付”。Skill 正好可以覆盖后面几个环节。2.2 通用 Skill 目录组织方式不同的 Agent 工具对 Skill 的目录命名不太一样。Claude Code 通常使用.claude/skillsCodex 使用.codex/skills或用户级目录Cursor 也可以读取项目级规则文件。目录名可以是{skill-name}/SKILL.md。核心形式大同小异。用一个比较通用的结构说明.claude/ └── skills/ └── fastadmin-dev/ ├── SKILL.md └── references/ ├── plugin-structure.md ├── crud-rules.md ├── sql-template.md └── checklist.mdSKILL.md是技能入口。AI 会先读它了解这个技能什么时候使用、整体流程是什么。references/下面的文档是更详细的参考AI 可以按需打开。2.3 SKILL.md 基本写法下面是一个简化但可用的SKILL.md示例--- name: fastadmin-plugin-dev description: 当用户要求开发、修改或排查 FastAdmin 插件时使用。包含插件目录结构、数据库脚本、权限节点、后台菜单、前端加载方式等规则。 --- # FastAdmin 插件开发技能 ## 使用场景 - 生成新插件 - 为已有插件增加功能 - 排查插件安装失败、菜单不显示、控制器 404 等问题 ## 执行流程 1. 先确认 FastAdmin 版本与 PHP 版本。 2. 分析需求输出插件目录结构和数据表设计。 3. 生成代码时严格遵循 references/plugin-structure.md。 4. 自检通过后输出安装说明。 ## 硬性规则 - 插件必须放在 addons/{name} 目录下。 - 安装脚本必须能重复执行或具备幂等性。 - 后台控制器必须做权限判断。 - 不允许删除用户数据表。 - 不要假设数据库前缀是 fa_统一使用 FastAdmin 的变量写法。这样的SKILL.md不需要写太长它要做的是“给 AI 一个工作流程和边界”让 AI 不要自行发挥。3. 环境准备与 Skill 接入3.1 建议环境如果要实践下面这条路径比较稳妥的环境是一个干净的 FastAdmin 本地项目可以随时重置数据库。PHP 版本以你项目当前使用的版本为准本文不限定具体版本。MySQL 或兼容数据库。一个支持 Skill 机制的 AI Agent例如 Claude Code、Codex 或同类型命令行工具。Git用于回滚生成结果。不建议直接在正式环境上让 AI 生成插件并自动安装。因为 Skill 生成代码虽然比普通 Prompt 稳定但仍然是“机器生成”需要人做最后确认。3.2 建立 FastAdmin Skill 目录假设项目根目录是/work/fastadmin我要给项目增加一个 FastAdmin 技能目录cd /work/fastadmin mkdir -p .claude/skills/fastadmin-dev/references touch .claude/skills/fastadmin-dev/SKILL.md如果你的 Agent 是 Codex可以放在对应的 skills 目录下。规则是让 Skill 文件能被 Agent 自动发现。3.3 把 FastAdmin 规范拆进 Skill建立目录后最重要的一步不是写代码而是把 FastAdmin 插件开发中的“规律性知识”结构化。你可以把下面这些问题写进references/plugin-structure.md一个标准插件包含哪些文件每个文件的职责是什么安装时如何注册菜单和权限卸载时如何清理后台控制器中哪些行为不建议做下面是我整理后的一个最小规范示例你可以直接借鉴# FastAdmin 插件目录结构规范 一个标准插件通常包含以下部分 - info.ini插件基础信息包括名称、标题、介绍、版本。 - config.php插件扩展配置。 - install.sql安装时执行的 SQL。 - uninstall.sql卸载时执行的 SQL。 - controller/控制器文件。 - model/模型文件。 - view/模板文件。 - assets/前端静态资源包括 JS 和 CSS。 ## 注意 - install.sql 中的表名要使用 FastAdmin 的占位符不要硬编码成 fa_。 - uninstall.sql 中删除表前要判断插件是否真的需要删除数据。 - 菜单和权限节点应尽可能由安装脚本维护而不是手动在后台添加。把类似信息拆成独立文档的好处是每次和 AI 对话时不用把内容粘贴到聊天框里AI 自己会去查阅。4. 5 分钟“聊”出一个插件完整演示4.1 需求描述我这次要开发的插件叫adverts作用是在后台维护首页横幅广告。要求可以新增、编辑、删除广告。广告字段包括标题、图片、跳转链接、排序、状态。后台菜单能自动出现。安装插件时自动创建数据表。我直接在 Agent 会话里输入请使用 fastadmin-dev Skill开发一个名为 adverts 的 FastAdmin 插件。 功能是后台管理首页横幅广告。字段包括 title、image、url、weigh、status。 要支持 install.sql 自动建表安装后后台菜单能正常出现。 请先输出插件目录结构和数据表设计确认后再生成代码。注意最后一句“先输出设计确认后再生成代码”很重要。它能让 AI 先出方案而不是直接生成一大坨文件。你在聊天里的控制顺序往往比模型本身的能力更重要。4.2 AI 给出的目录结构AI 调用 Skill 后第一轮输出不是完整代码而是结构规划addons/adverts/ ├── Bootstrap.php ├── config.php ├── info.ini ├── install.sql ├── uninstall.sql ├── assets/ │ └── js/ │ └── adverts.js ├── controller/ │ └── Banner.php ├── model/ │ └── Banner.php ├── lang/ │ └── zh-cn.php └── view/ └── banner/ └── index.html这个结构符合 FastAdmin 插件的基本形态。controller/Banner.php是后台逻辑install.sql负责建表和菜单数据assets/js是前端逻辑。4.3 生成的基础文件下面看几个关键文件的生成结果。首先是info.ininame adverts title 广告管理 intro 后台管理首页横幅广告 author yourname version 1.0.0 state 1然后是install.sql。这里的重点是表名和字段设计要能被 FastAdmin 识别。我要求 AI 统一使用 FastAdmin 的替换前缀写法避免在用户修改过表前缀的网站上安装失败CREATE TABLE IF NOT EXISTS __PREFIX__adverts ( id int(10) unsigned NOT NULL AUTO_INCREMENT, title varchar(255) NOT NULL DEFAULT COMMENT 广告标题, image varchar(255) NOT NULL DEFAULT COMMENT 广告图片, url varchar(255) NOT NULL DEFAULT COMMENT 跳转链接, weigh int(10) NOT NULL DEFAULT 0 COMMENT 权重, status tinyint(1) NOT NULL DEFAULT 1 COMMENT 状态:0隐藏,1显示, createtime int(10) NOT NULL DEFAULT 0 COMMENT 创建时间, updatetime int(10) NOT NULL DEFAULT 0 COMMENT 更新时间, PRIMARY KEY (id) ) ENGINEInnoDB DEFAULT CHARSETutf8mb4 COMMENT广告表;AI 还生成了对应的config.php。FastAdmin 的配置主要用来读取后台设置项这里我让 AI 生成了最简单的版本?php return [ page_size [ title 每页显示数量, type number, value 10, ], ];4.4 控制器逻辑的关键约束AI 生成的controller/Banner.php核心方法包括index、add、edit、del。这些方法在 FastAdmin 后台里并不是“随便写个函数”就行而是要对应菜单权限。所以 Skill 里需要加入这样的规则不要在插件控制器里直接输出 HTML 片段。列表接口统一返回 JSON 数据。每个操作要使用后台登录态。删除操作要考虑软删除或物理删除的区别。下面是演示用控制器片段展示 FastAdmin 后台控制器的大概结构。不同 FastAdmin 版本之间可能有差异生产环境建议以项目内已有控制器为准?php namespace addons\adverts\controller; use app\common\controller\Backend; class Banner extends Backend { protected $model null; public function initialize() { parent::initialize(); $this-model new \addons\adverts\model\Banner(); } public function index() { if (false $this-request-isAjax()) { return $this-view-fetch(); } return $this-table($this-model); } }这个片段不是让你直接复制到项目里而是说明AI 在 Skill 约束下会继承项目已有的后台基类而不是凭记忆写一套自己发明的控制器结构。这是 Skill 和普通 Prompt 差异最明显的地方。4.5 一轮聊天迭代到稳定第一版生成后我不会直接安装而是继续和 AI 对话请检查 install.sql 是否符合 FastAdmin 的安装脚本要求。 菜单和权限节点是否已经包含请再次确认后台控制器继承了正确的基类。 如果安装后菜单不存在可能是什么原因这相当于逼着 AI 做一轮“代码评审”。AI 会自己发现一些问题比如install.sql里只创建了表没有插入菜单和权限节点。控制器中可能需要补充权限节点名称。卸载脚本要处理菜单清理否则会残留数据。这些问题不是模型笨而是第一次生成时没有足够明确的检查项。Skill 的价值之一就是把“代码评审”也变成可重复执行的步骤。5. 验证生成结果不能只靠“看起来对”5.1 本地安装测试FastAdmin 的插件支持在后台直接安装。我把adverts目录放入addons/后进入后台插件管理页点击安装。安装结果分三种安装成功菜单出现数据表创建成功。安装成功但菜单没有出现。安装失败SQL 报错或文件权限问题。后两种最常见。如果失败第一步不是重新安装而是去查看 FastAdmin 的日志目录以及数据库里有没有残留表。5.2 手动验证点我给自己定了一个快速验收清单验证点检查方式通过标准插件列表后台插件管理页能看到 adverts数据表数据库表列表新建表存在菜单后台左侧菜单出现“广告管理”新增功能点击新增按钮能正确保存编辑功能点击编辑按钮数据能回显和更新删除功能点击删除按钮数据删除且权限判断正常卸载重装先卸载再安装不再出现重复菜单或残留数据5.3 如果结果不满足要求只要发现任何一点异常我会让 AI 查看日志并修复而不是自己动手改完就结束。因为 Skill 的目的是“持续复现稳定结果”如果第一次结果有 bug应该把 bug 现象喂回给 Skill 里的 references 文档作为下次生成的约束。比如这次遇到“安装后菜单没有出现”我会在references/checklist.md里增加一条## 安装后菜单不显示的排查项 - 检查 install.sql 是否正确插入 auth_rule 数据。 - 检查菜单的 pid 是否指向真实存在的父菜单。 - 检查插件名和控制器名是否大小写不一致。 - 检查安装完成后是否刷新了权限缓存。下次再开发新插件AI 会主动执行这个检查项。这就是“经验沉淀”的意义。6. 常见问题与排查方法我用 Skill 生成插件后整理出了 6 个高频问题全部来自真实落地场景问题现象可能原因排查方式解决方案插件安装失败SQL 中存在不兼容语法查看安装 SQL 报错信息去掉特殊字符改为标准 SQL安装后数据表名不是预期表前缀被硬编码搜索fa_字符串换成 FastAdmin 的替换前缀写法控制器访问 404命名空间写错对比已有插件的命名空间按 FastAdmin 插件规范修正后台菜单不显示install.sql 未插入菜单查看auth_rule表补充菜单和权限节点删除操作未生效控制器方法权限未配置检查日志和请求地址为控制器方法添加权限节点AI 生成代码无法直接运行框架版本不匹配查看已有项目的控制器模板让 AI 参考项目内真实文件每条都可以继续展开但核心思路是先让 AI 根据错误日志自查再把错误知识写入 Skill。7. 最佳实践与工程建议7.1 Skill 里不应该只有“正向规则”还要有“禁止项”只告诉 AI 做什么它可能踩坑告诉它不能做什么它能少走很多弯路。我在 Skill 里专门加了一段“禁止项”禁止自动执行DROP TABLE除非用户明确要求删除并清理数据。禁止在未征得用户确认时生成覆盖数据库的脚本。禁止把项目内敏感配置写入代码注释。禁止用普通 ThinkPHP 控制器逻辑代替 FastAdmin 后台控制器逻辑。禁止静默修改config.php而不提示用户。加入“禁止项”后AI 会变得更加保守。虽然效率上好像慢了一点但稳定性明显提升。7.2 使用 Git 管理“Skill”和“生成结果”将 Skill 文件提交到仓库中。这个 Skill 是你项目的技术资产团队成员都能复用。每次 AI 生成插件后在合并进主分支前把它放到独立目录或分支进行测试git add .claude/skills git commit -m feat: fastadmin plugin skill git checkout -b feature/adverts-plugin这样既能回滚产品代码也能回滚 Skill 本身的修改。7.3 迭代 Skill 比维护“完美 Skill”更重要Skill 不用第一次就写完美。哪怕你的SKILL.md一开始只有两页也可以开始用。关键是每做一次插件开发就把新发现的规则补充进去。Skill 的成长路径是第一版只有目录结构和基本流程。 第二版加入 install.sql 菜单和权限规则。 第三版加入常见报错和排查步骤。 第四版加入 FastAdmin 不同版本间的差异提醒。每次补充都不要贪多只增加当前遇到过的真问题。8. 在什么情况下 Skill 并不适合我不建议把 Skill 当成“万能生成器”。它更适合解决“重复性高、边界明确”的开发任务例如快速生成一个标准 CRUD 插件。给已有插件增加一个数据表。统一处理 FastAdmin 的权限和菜单配置。但它不适合直接从零承担一套复杂业务系统的架构设计。如果插件里涉及到多个服务、长事务、复杂状态机AI 生成的代码只能作为初始版本仍然需要人工架构师参与设计。另外Skill 生成速度很快这会带来一个项目管理上的新风险批量生成大量功能却没有经过质量验证。正确的做法是严格限制“一次会话只做一件事”每完成一个小功能马上进行本地验证。9. 留给你的下一组行动项如果你也想把 FastAdmin 插件的开发效率提上来可以按下面的顺序去做第一步先建 Skill 目录不要写代码先写一份快速清单。 第二步选择你项目中最简单的一个插件试着用 Skill 重新生成。 第三步等结果稳定后把发现的问题补充进 references。 第四步再把你项目中曾经踩过的 3 个坑写进禁止项。Skill 真正解决的不是“让 AI 多聪明”而是让 AI 在动手前就知道你的项目默认了什么、约束了什么、踩过什么坑。这才是 FastAdmin 开发进入 AI 时代后最值得每个人先建立起来的基础设施。