Agent Skills实战指南：从安装到编写，解锁AI编程超级能力

最近圈子里聊AI编程三句话不离skills。我刚开始以为又是营销号在造概念直到自己动手把GitHub上的skills装进Claude Code又照着社区规范写了一个用于数学建模论文排版的技能包之后才明白为什么大家都说这是AI编程的“超级能力”。这篇不打算写成翻译腔的文档而是把自己从“听到这个词”到“能自己装、能自己写、能帮同事排查”的过程完整复盘一遍。内容包括手动安装的完整步骤、SKILL.md的写法、几个真实能用的技能库以及我踩过的那些坑。适合正在用Claude Code、Codex这类AI编程工具又觉得每次都要重复描述需求很烦的人。1. Skills到底是什么从提示词到“可复用技能包”的进化1.1 从一个让我头痛的场景说起没接触skills之前我的工作流是这样的每次让AI帮我生成数学建模论文的LaTeX代码都要先唠叨一遍“用中文、字号按赛事要求来、公式要带编号、图表标题居中”如果换一个工具还得重新讲一遍。更烦的是AI生成的模板每次风格都不一样有时给我ModernCV风格有时给我IEEE风格根本没法直接用。后来我在GitHub上翻到一个东西叫“skill”看到别人的仓库里放着一个文件夹里面有SKILL.md、几个脚本、一堆参考资料。我把它手动装进Claude Code的skills目录再让AI写论文模板它居然直接调用了正确的字号、公式宏包和参考文献格式完全不用我重复描述需求。那一瞬间我意识到这玩意儿跟普通提示词完全不是一个物种。1.2 Skills的构成SKILL.md 脚本 资源一个标准的Agent Skill本质上是一个目录核心是三个部分SKILL.md用Markdown写的“技能说明书”包含frontmatter元信息和正文指令scripts/可执行的脚本Python、Shell、Node.js都行references/参考资料PDF、Markdown、JSON模板等当AI判断当前任务适用某个技能时它会先去读SKILL.md按里面的指令执行必要时跑脚本、查资料。这个设计很像给新员工一份“岗位手册”而不是在上司每次布置任务时重新解释一遍公司制度。math-model-latex/ ├── SKILL.md ├── scripts/ │ └── make_template.py └── references/ └── format.md1.3 为什么说它是“超级能力”说它是superpower是因为它把“上下文”从一次性对话里抽出来变成了可保存、可分享、可跨工具迁移的资产。以前我积累的是“自己的记忆”现在积累的是“团队的技能库”。而且这个标准正在被多家工具接纳Claude Code有skills目录Codex也在往这个方向走OpenCode这类开源工具同样支持类似结构。你写好一个技能今天在Claude Code里能用明天换工具只要目录结构兼容稍微改改路径就能接着用。这种影响范围已经不只是“少打几行提示词”的级别了。2. 从GitHub手动装Skills完整实操流程2.1 先摸清你的工具把技能放在哪里不同工具的skills目录位置不完全一样装之前一定要先搞清楚否则你clone半天工具压根不扫描那个目录。工具用户级技能目录项目级技能目录备注Claude Code~/.claude/skills.claude/skills官方原生支持Codex~/.codex/skills.codex/skills配置里可开关OpenCode~/.config/opencode/skills.opencode/skills社区实现结构兼容用户级目录对所有项目生效项目级目录只对当前仓库生效。我一般把通用技能放用户级把和具体业务强绑定的技能放进项目里方便跟着仓库走。2.2 手动安装的完整五步第一步去GitHub上找到你需要的技能仓库确认里面确实有SKILL.md。有些仓库虽然名字带skills实际上是个教程合集没有统一结构装了也没法直接用。第二步clone或下载zip。第三步把技能文件夹放进目标目录。第四步完全退出工具重新打开或者执行重载命令。第五步验证。git clone https://github.com/你的用户名/你的技能仓库.git ~/.claude/skills/技能名 ls ~/.claude/skills如果网络不稳定导致clone中断多试几次或者直接下载zip压缩包再解压到目录里。注意解压后如果多出一层同名文件夹要把内层文件夹内容挪到skills目录下否则工具扫描不到。验证方法很简单随便写一句和技能相关的需求比如装了论文排版技能就写“帮我生成一份数学建模论文模板”然后观察AI是否主动说它使用了某个技能或者去看工具日志里的skill加载记录。2.3 安装失败的三个常见原因我自己和同事遇到过的问题基本都是这三类目录层级不对。压缩包解压出来是skill-master/skill-master直接扔进去就废了工具只扫描一级目录下的SKILL.md。frontmatter漏写。SKILL.md最上面必须有name和descriptionname还得是短横线命名法的英文description不能为空否则技能在注册阶段就被跳过。名字冲突。两个技能都叫superpower后装的把先装的覆盖了表现出来就是“技能消失了”。我建议装之前先看一下目标目录里有没有同名文件夹。还有一种情况你用的工具版本比较老当时还不支持skills功能。这种只能升级工具别在目录层面折腾。3. 手把手写一个自己的Skills以数学建模LaTeX排版为例3.1 先定“最小可用技能”很多人一上来就想写一个“全栈开发助手”巨型技能我不建议这样。第一次写选一个输入输出明确、规则几乎不变、你能立刻判断对错的任务。我选的是“数学建模LaTeX论文模板生成”因为赛事要求相对固定又是纯文本输出验证成本低。写之前先想清楚三个问题什么时候触发用户要求生成论文模板、排版、公式格式调整时输入是什么赛题类型、模板风格、是否要目录输出是什么一个完整的main.tex以及必要的使用说明想清楚这三点你才知道SKILL.md的description该怎么写。3.2 SKILL.md的正确写法SKILL.md是技能的大脑我建议控制在100行以内把大段的背景知识放到references里。frontmatter格外关键因为工具会根据description决定何时加载这个技能写得太宽泛会频繁误触发写得太窄又会漏触发。这是我实际用过的简化版--- name: math-model-latex description: 生成数学建模竞赛LaTeX论文模板支持国赛、研究生数学建模等场景。当用户提到论文排版、LaTeX模板、公式编号、图表标题时使用。 --- # 数学建模LaTeX排版技能 ## 任务 根据用户需求生成一份可直接编译的main.tex。 ## 步骤 1. 读取 references/国赛模板规范.md 中的格式要求 2. 用 scripts/make_template.py 生成模板骨架 3. 在模板中写清注释标出需要用户替换的正文区域 ## 注意事项 - 正文字号为小四行距1.5公式必须带编号 - 图表标题居中图题在下表题在上 - 禁用任何会导致中文乱码的宏包description里我特意用了“国赛”“研究生数学建模”这种具体词实测下来AI在遇到相关需求时几乎都能命中。负向描述也很重要我通常在注意事项里写“不适用于商业论文排版不处理参考文献格式细节”免得啥活都往这个技能上揽。3.3 脚本与资源的组织方式脚本的作用是把重复劳动自动化。比如make_template.py读取一个JSON配置直接吐出带基础章节的main.texAI只需要在生成后填充正文。#!/usr/bin/env python3 import json, sys config json.load(open(sys.argv[1])) if len(sys.argv) 1 else {} sections config.get(sections, [摘要, 问题重述, 模型假设, 模型建立]) print(r\documentclass[12pt]{ctexart} \usepackage{amsmath, graphicx} \title{数学建模论文} \begin{document} \maketitle ) for i, sec in enumerate(sections, 1): print(f\\section{{{sec}}}\n) print(r\end{document})这个脚本不复杂但它保证了每次生成的模板风格统一不会出现这次用article下次用report的混乱。references目录我放的是赛事官方格式要求的精简版用Markdown整理成AI方便读取的要点。注意不要直接丢一个几十页的PDF进去AI读起来慢而且容易漏关键信息。3.4 调试迭代我改了三版才顺手第一版description写的是“处理论文相关任务”结果用户让它写摘要它也调用这个技能路径和内容都不匹配。第二版把脚本路径写成了绝对路径换到另一台电脑直接报废。第三版我做了三件事把description改成触发词明确的短句脚本里所有路径改成相对SKILL.md目录的写法加入“不适用场景”。这才算是能拿出去给人用的技能。这个迭代过程很能说明问题技能不是写出来就完事而是要在真实对话里反复验证。我建议每个新手技能都从“最小可用”开始先跑通再慢慢往里加规则。4. 优秀技能库与场景实战推荐4.1 值得关注的开源技能库盘点GitHub上可以直接搜“awesome-claude-skills”这类汇总仓库比较有代表性的包括技能库侧重方向适合人群anthropics/skills官方示例质量高想学规范写法的人superpower-skills综合技能包覆盖前端、文档、自动化Claude Code用户typesafe-ai skillsTypeScript类型安全、zod schema生成全栈/后端开发codex-nature数据科学、统计分析、绘图数学建模、科研向cola skills社区实验性技能集合喜欢尝鲜的人安装这些库之前我强烈建议先打开SKILL.md看一眼确认里面的脚本是做什么的。技能包本质上是能在你机器上执行代码的不能因为是“开源”就无脑信任。4.2 前端开发场景组件生成与代码审查前端是目前skills应用最成熟的方向。superpower-skills里就有不少前端相关技能比如“React组件生成”你只需要描述组件功能它会自动生成TSXTailwind代码并且严格按照你这个项目的目录结构放置。代码审查类技能也很有用能把团队规范写进SKILL.md让AI帮你检查命名、hook依赖、样式类名是否规范。我个人的体会是前端技能最好结合项目级目录放在仓库里这样团队成员clone下来就能一致工作不会出现“你的AI和我的AI审美不一样”的问题。4.3 数学建模场景华为杯赛事限时提效数学建模是典型“限时、高密度、规则多”的场景。华为杯这类比赛只有几天时间光调格式就能耗掉半天。把论文排版、图表绘制、灵敏度分析这些重复性工作做成skills配合Codex或Claude Code能把更多时间留给模型推导本身。比如图表绘制技能输入CSV数据输出风格统一的matplotlib代码图注、坐标轴标签、字体大小全部按赛事要求预设好。敲命令的时间省下来至少能多跑两版模型。4.4 AI漫剧场景分镜脚本与提示词生成漫剧这个方向很多人不知道skills能怎么用。实际上分镜脚本、角色一致性提示词、画风参考这些都是高度模板化的内容。把常用画风、角色描述模板、分镜格式做一个技能包生成一集漫剧的提示词时间能从半小时压缩到几分钟。这类技能的核心是把“审美经验”沉淀成规则描述比如“主角发色固定为#7EB6FF光影用柔光背景要强调透视”。文本技能没有脚本也能成立但加上参考图目录效果更好。5. 常见问题与排查技巧实录5.1 技能加载了却不生效最让人迷惑的是“技能列表里能看到但AI就是不调用”。我的排查顺序是先看SKILL.md的description是否覆盖了你的问法再看工具是否已经重载有些工具需要重启进程最后把触发词原样放进对话再试。很多时候不是技能坏了而是AI判断当前对话“没必要用技能”这是正常现象不是故障。5.2 技能之间互相打架同名或描述高度重叠的技能会互相干扰。表现出来就是你让它做A它调用了B技能的脚本。解决办法是命名空间化把所有技能都放在“作者名-技能名”的目录结构里同时在SKILL.md的description里声明“本技能不处理某类请求”。清理时优先删除那些描述含糊的旧技能它们往往是冲突源头。5.3 权限与安全安装前先看脚本这是最容易被新人忽略的坑。skills可以调用脚本等于给了AI执行本机代码的权限。我见过有人在技能里塞curl命令把环境变量往外传。虽然目前主流技能库整体安全但“手动装GitHub上的skills”这件事天然要求你自己当安全员。安装前打开脚本看一遍确认没有网络请求、没有读取敏感路径的操作再放进技能目录。企业环境里最好用一个单独的隔离目录跑未知技能。5.4 清理技能的思路像维护工具箱一样维护技能库技能装多了之后你会发现大多数其实用不上。像我之前一口气装了二十来个最后真正高频使用的只有四五个。清理思路参考了tibo这类技能库维护者的做法先把所有技能按“周使用次数”排序三个月没用过的直接归档到archive目录而不是删除以防哪天要翻出来。同时技能库里只保留description差异明显的技能减少误触发。最后分享一个我自己的习惯每次新建技能我都会在SKILL.md最开头写清楚“这个技能不做什么”。听起来很反直觉但正是这句话让我后来排查问题时少掉了无数根头发。技能不是越复杂越好而是“触发越精准越好”。你写的每个字都是给另一个AI看的与其写一百条规则让它每条都记住不如写十条清晰的边界让它别乱动。这条经验也适用于你整个技能库的长期维护。