文章总结： 本文系统介绍AISkills开发全流程，涵盖核心概念、文件结构、生命周期、安装级别、触发机制及SKILL.md设计要点。以个人月度消费分析为例，强调description写作技巧、触发词分层设计及SOP三步法。提供可操作建议：注重元数据规范、知识层设计及异常路径覆盖，以提升Skill可用性与维护性。 综合评分： 85 文章分类： AI安全,安全开发,安全建设
AI Skills 开发完全指南
原创
黄鹂儿 黄鹂儿
一路狂飚的蜗牛
2026年9月27日 15:05 河北
在小说阅读器读本章
去阅读
在公众号小说中沉浸阅读
从触发机制到性能优化，从测试到安全，覆盖 Skill 开发的完整知识体系。 以个人月度消费为例，CodeBuddy驱动，串起来skill开发流程。 预计阅读时间：约 25 分钟
一、Skill 核心概念
1.1 什么是 Skill
Skill 是一个领域扩展包，为 AI 助手注入特定领域的专业知识、标准化工作流（SOP）和可执行工具。它不是单一脚本，而是一个有结构的软件包：
Skill = 元数据层（SKILL.md） + 引擎层（scripts/） + 资源层（assets/ + references/） + 版本管理
核心设计理念：让 AI 继承你的领域知识。当你编写一个 Skill，本质上是在做一个知识工程——把隐性的领域经验显式化为可被 AI 读取和执行的规范文档。
1.2 文件结构深度解析
skill-name/├── SKILL.md # 入口说明书——AI 每次触发 Skill 时最先读取├── README.md # 给人看的文档（快速开始、FAQ）├── .gitignore│├── scripts/ # 引擎层：可执行脚本│ ├── version.json # 版本元数据（SemVer + 远程更新 URL）│ ├── check_update.py # 自动更新检查模块│ └── *.py / *.sh # 核心业务脚本│├── assets/ # 资源层（机器消费）│ ├── templates/ # Excel 模板、HTML 模板│ ├── fonts/ # 字体文件（避免宿主环境缺失）│ └── data/ # 静态数据（城市码表、节假日表等）│└── references/ # 知识层（人 + AI 共同消费） ├── category_rules.md # 分类规则词典 ├── data_schema.md # 中间格式 JSON Schema ├── platform_notes.md # 各数据源注意事项 └── known_issues.md # 已知问题清单
各目录角色：
| 目录 | 定位 | AI 何时读取 | 内容的性质 |
| — | — | — | — |
| SKILL.md | 入口说明书 | 每次触发 | 元数据 + SOP + 领域规则 |
| scripts/ | 引擎层 | 按 SOP 步骤执行 | 可执行代码 |
| assets/ | 资源层 | 运行时引用 | 二进制/结构化文件 |
| references/ | 知识层 | 按需读取或引述 | 规则文档、字典 |
区分 assets/ 与 references/：
-
assets/放的是「代码运行时需要的文件」——模板被 openpyxl 加载、字体被渲染引擎引用
-
references/放的是「AI 理解领域时查阅的文档」——分类规则让 AI 知道某笔交易归入哪类
1.3 Skill 的生命周期
安装 触发 执行 更新 退役 ───→ ──────────→ ───────────────→ ───────────→ ─────────→ zip/Git description AI→SOP→Scripts version.json 移除目录 部署 文本匹配 逐步执行 SemVer 比较 清理配置
理解生命周期有助于设计每个阶段的关注点：
| 阶段 | 核心关注点 |
| — | — |
| 安装 | 路径规范、依赖声明、.gitignore |
| 触发 | description文本质量、触发词精准度 |
| 执行 | SOP 可操作性、脚本健壮性、输出确定性 |
| 更新 | 版本号策略、向后兼容、静默检测 |
| 退役 | 清理残留、通知用户迁移方案 |
1.4 Skill 安装级别
Skill 支持四种安装级别，从底层到表层构成一个优先级覆盖链：
优先级（高→低）：项目级 > 用户级 > 插件级 > 内置级
| 级别 | 存放位置 | 可见范围 | 典型场景 |
| — | — | — | — |
| 内置级 | 平台内置，不可修改 | 所有用户、所有项目 | 通用能力（如代码分析、多模态生成） |
| 插件级 | 从 Skills 市场安装 | 启用后全局可用 | PPTX 处理、PDF 合并、Excel 生成 |
| 用户级 | ~/.codebuddy/skills/ | 当前用户的所有项目 | 个人工作流（代码审查模板、Git 提交规范） |
| 项目级 | <project>/.codebuddy/skills/ | 仅当前项目 | 项目专属逻辑（spending-analysis、业务规则） |
同名 Skill 覆盖规则：
高优先级级别的同名 Skill 会覆盖低优先级级别。例如：
项目级 spending-analysis v2.0 ← 实际生效（高优先级）用户级 spending-analysis v1.0 ← 被静默覆盖，不生效
这个机制的核心价值：在用户级放默认版本，在特定项目级放定制版本。
选择建议：
| 如果 Skill… | 选择 | | — | — | | 是通用工具，所有人都会用 | 插件级 | | 是个人习惯，跨项目复用 | 用户级 | | 绑定特定项目 / 团队共享 | 项目级（随 git 分发） | | 公司级强制规范（安全审计、代码风格） | 项目级 + git submodule |
注意：内置级和插件级由平台管理，开发者自己编写的 Skill 通常落位在用户级或项目级。本文后续讨论以这两个级别为主。
二、Skill 触发机制
2.1 触发原理
Skill 的触发基于文本匹配：AI 在处理每个用户请求时，会将请求内容与所有已安装 Skill 的 description 字段进行语义匹配。匹配成功时，SKILL.md 的完整内容会注入到 AI 的上下文中。
用户输入 ”帮我分析上个月花了多少钱” │ ▼遍历所有 Skill 的 description 字段 ── 语义匹配 │ ▼匹配到 spending-analysis：description 含”消费分析””月度消费””花了多少钱”等触发词 │ ▼加载 SKILL.md 完整内容到上下文 │ ▼AI 按照 SKILL.md 中定义的工作流（SOP）逐步执行
关键认知：description 字段是 Skill 的唯一入口。如果 description 写不好，Skill 可能永远不会被触发，或者在不该触发的时候被误触发。
2.2 description 写作技巧
description 需要同时回答三个问题：
- 这个 Skill 做什么（功能描述）
- 什么时候触发（触发条件）
- 用户可能怎么提问（自然语言触发词）
优秀示例（spending-analysis）：
description: > 个人月度消费分析。从支付宝/微信/招商银行等多平台交易流水中解析、 标准化、去重、分类打标，生成 Excel + Markdown 消费分析报告。 触发词包括：”消费分析”、”月度消费”、”账单分析”、”交易流水”、 ”记账分析”、”消费报告”、”支出分析”、”看看花了多少钱”等。
拆解这个 description 的设计思路：
| 要素 | 内容 | 作用 | | — | — | — | | 领域定义 | 「个人月度消费分析」 | 告诉 AI 这是一个消费金融领域的 Skill | | 能力声明 | 「多平台交易流水中解析、标准化、去重…」 | 让 AI 知道这个 Skill 能做什么 | | 输出物 | 「生成 Excel + Markdown 消费分析报告」 | 让 AI 知道执行结果是什么 | | 触发词列表 | 「消费分析」「月度消费」「花了多少钱」等 | 覆盖用户的各种自然语言表达 |
description 写作口诀：
一句领域 + 一句能力 + 一句输出 + 一串触发词
常见写作错误：
| 错误 | 问题 | 改正 | | — | — | — | | 「一个很有用的工具」 | 太模糊，AI 无法判断何时触发 | 加具体领域和能力 | | 「处理 CSV 文件」 | 太宽泛，会误触发 | 限定场景「支付宝账单 CSV」 | | 只有功能描述，没有触发词 | 依赖 AI 语义推理，不够可靠 | 显式列出触发词 | | 触发词太少（2-3 个） | 覆盖不全 | 至少列 5-8 个，涵盖口语化表达 |
2.3 Skill 触发域控制
为什么要控制触发域：防止 Skill 被不该触发的请求误触发，也防止一个超大的 SKILL.md 在不需要的时候占用上下文窗口。这里的「触发域」指 Skill 对哪些用户输入作出响应，与 1.4 节讨论的「安装级别」（Skill 对哪些项目可见）是两个正交的概念。
触发域控制策略：
| 策略 | 说明 | 示例 |
| — | — | — |
| 明确边界 | description 中声明适用范围 | 「仅处理支付宝/微信/招行账单」 |
| 排除声明 | 说明不处理什么 | 「不支持银行理财产品分析」 |
| 触发词精确化 | 用组合词而非单个通配词 | 用「月度消费」而非「消费」 |
| 前置判断 | SOP 第一步检查前置条件 | 先确认 bills/{月份}/ 目录存在 |
触发域边界示意（以 spending-analysis 为例）：
┌── 触发域 ────────────────┐ │ ”消费分析”、”月度消费” │ │ ”账单分析”、”花了多少钱” │ │ ”消费报告”、”支出分析” │ │────────────────────────│ │ 能力域 │ │ 支付宝 CSV / 微信 XLSX │ │ 招行 PDF → 标准化 → 报告 │ └────────────────────────┘ ↓ ┌── 非触发域 ─────────────┐ │ ”投资收益分析” │ │ ”股票持仓” │ │ ”贷款计算” │ │ ”汇率换算” │ └────────────────────────┘
2.4 触发词设计进阶
触发词分层模型：
T1 精确触发词（高置信度） → 用户明确要这个 Skill → 例：”消费分析”、”账单分析”、”月度消费报告” T2 场景触发词（中置信度） → 用户描述了典型使用场景 → 例：”花了多少钱”、”帮我记账”、”看月度支出” T3 模糊触发词（低置信度，需 AI 判断） → 不显式列出，靠 AI 语义推理 → 例：”支付宝明细”、”微信账单整理”
实践建议：
- T1 触发词必须显式写在 description 中
- T2 触发词根据实际用户反馈持续补充
- T3 不写入 description，而是通过 SKILL.md 中的「概述」部分让 AI 自行判断
三、SKILL.md 设计
3.1 元数据头规范
SKILL.md 以 YAML front matter 开头，这是 AI 读取的第一个信息块：
---name: skill-name# 唯一标识，建议用英文小写 + 连字符description: ># 多行文本用 > 或 | 功能 + 场景 + 触发词version: 1.0.0# SemVer，与 version.json 保持一致---
name 命名规范：
| 规范 | 正确 | 错误 |
| — | — | — |
| 小写字母 + 连字符 | spending-analysis | SpendingAnalysis |
| 领域-动作 格式 | asset-allocation | asset （太宽泛） |
| 避免品牌名 | pdf-merger | adobe-pdf |
| 2-4 个词为佳 | meal-calorie-tracker | a-comprehensive-meal-and-diet-calorie-tracking-system |
3.2 工作流 SOP 设计
SOP（Standard Operating Procedure）是 SKILL.md 的核心内容，告诉 AI 应该按什么步骤执行。好的 SOP 设计遵循以下原则：
原则 1：步骤数量 3-5 步。太多 AI 容易遗漏，太少指令不够明确。spending-analysis 的 3 步设计是一个好的参照：
Step 1: 准备账单文件 → Step 2: 解析标准化 → Step 3: 生成报告
原则 2：每步配可执行命令。AI 需要具体的、可直接复制执行的命令，不是含糊的自然语言描述。
# ✅ 好的写法python scripts/parse_bills.py --dir bills/2607# ❌ 差的写法使用解析脚本处理账单文件
原则 3：明确输入输出。每步结束后输出什么、下一步需要什么输入，必须在 SOP 中显式声明。
Step 1 输出 → 用户确认账单文件 → Step 2 输入Step 2 输出 → _normalized.json → Step 3 输入Step 3 输出 → 消费报告 exceld + .md
原则 4：覆盖异常路径。SOP不只是「正常情况下怎么做」，还要覆盖「出了问题怎么做」：
| 异常情况 | 处理策略 | | — | — | | 账单目录为空 | 提示用户导出账单的具体路径（支付宝/微信/招行 APP 操作指南） | | 某平台账单缺失 | 只分析已有平台，报告中注明缺失平台 | | 解析失败 | 输出错误文件路径 + 尝试的编码列表，指导修复 | | 报告路径已存在 | 询问是否覆盖，或用时间戳区分 |
3.3 知识层设计
知识层是 SKILL.md 中分类规则、指标体系、已知限制等内容的统称。这些内容不直接可执行，但对 AI 做正确决策至关重要。
三层知识结构：
SKILL.md（内嵌核心规则） ├── 分类体系（主分类 + 子分类 + 关键词映射） ├── 去重策略（匹配规则 + 优先级 + 保留逻辑） └── 指标定义（计算公式 + 合理范围 + 消减建议）
references/（外部参考文档） ├── category_rules.md —— 完整分类词典（超出 SKILL.md 容纳量的部分） ├── data_schema.md —— 中间格式 JSON 的字段定义和类型约束 └── platform_notes.md —— 各数据源的特殊注意事项
何时放入 SKILL.md vs references/：
| 内容特征 | 放在 SKILL.md | 放在 references/ | | — | — | — | | AI 每次执行都需要 | ✅ | – | | 改变频率高 | – | ✅ | | 内容量大（>50 行） | – | ✅ | | 仅特定场景需要 | – | ✅ |
四、脚本引擎设计
4.1 管道式架构
核心设计模式：单向数据流管道。每个阶段只做一件事，通过标准化中间格式解耦。
原始文件（CSV/XLSX/PDF） │ ▼ Stage 1: parse_bills.py标准化 JSON（_normalized.json） │ ▼ Stage 2: classify_report.py ├── 去重（三级匹配） ├── 分类（规则链） ├── 指标计算 └── 报告生成（Excel + Markdown）
为什么用管道而非单体脚本：
| 对比维度 | 单体脚本 | 管道式 | | — | — | — | | 调试 | 全流程重跑 | 只重跑出错阶段 | | 修改分类规则 | 必须重解析 | 直接拿 normalized.json 重分类 | | 复用 | 难以复用 | parse 输出可给其他工具用 | | 测试 | 难以隔离 | 每阶段独立测试 |
中间格式设计要点：
{ ”date”: ”2026-08-01”, // ← 统一日期格式 YYYY-MM-DD ”amount”: -35.80, // ← 正负号统一（支出为负） ”merchant”: ”瑞幸咖啡”, // ← 商户名标准化（去公司后缀） ”platform”: ”支付宝”, // ← 来源平台标记 ”payment_method”: ”花呗”, // ← 支付方式 ”original_category”: ””, // ← 保留原始分类（用于校验） ”remark”: ”” // ← 保留原始备注（用于子分类）}
4.2 错误处理与容错
容错三原则：
- 不要 crash：任何单条数据出错都不应阻塞整个流程
- 记录问题：出错时输出足够多的诊断信息
- 可恢复：用户不需要从头开始
编码自动检测（实际案例）：
ENCODINGS = [”utf-8-sig”, ”utf-8”, ”gbk”, ”gb2312”, ”gb18030”]for enc in ENCODINGS: try: with open(filepath, ”r”, encoding=enc) as f: content = f.read() return content except UnicodeDecodeError: continue# 所有编码都失败 → 输出诊断信息print(f”⚠️ 无法解码 {filepath}，尝试了: {ENCODINGS}”)return None
# 返回 None 而非 crash
容错设计清单：
| 场景 | 策略 | | — | — | | PDF 解析不完整 | 输出「需人工识别」标记，不丢弃整条记录 | | 金额格式异常 | 记录 Warning，跳过该行（不中断） | | 文件不存在 | 跳过该平台，在报告中注明缺失 | | 网络请求超时 | 5 秒超时 → 静默跳过（自动更新场景） | | 编码检测失败 | 输出尝试过的编码列表，指导用户转码 |
4.3 配置管理
多层配置优先级（高 → 低）：
命令行参数 > 环境变量 > version.json > 代码默认值--no-update SKILL_NO_ update_url 硬编码 fallback UPDATE_CHECK
version.json 设计规范：
{ ”skill”: ”spending-analysis”, // 与 SKILL.md name 一致 ”version”: ”1.2.3”, // SemVer ”release_date”: ”2026-08-02”, // ISO 日期 ”update_url”: ”https://...version.json”, // 远程版本文件 raw URL ”changelog”: { ”1.2.0”: ”新增信用卡关联去重”, ”1.1.0”: ”新增消费指标与消减分析”, ”1.0.0”: ”初始版本” }, ”min_python”: ”3.9”, // 可选：最低运行时版本 ”dependencies”: [”openpyxl”, ”pdfplumber”] // 可选：依赖声明}
五、Skill 成本分析与性能优化
5.1 Token 成本分析
每次触发 Skill，SKILL.md 的完整文本会被注入 AI 上下文，这直接消耗 token。理解成本模型是设计高效 Skill 的前提。
成本构成模型：
单次 Skill 触发成本 = SKILL.md token 数 + 脚本输出 token 数 + 中间对话 token 数
| 成本项 | 影响因素 | 优化方向 | | — | — | — | | SKILL.md 大小 | 文档长度、代码块量 | 精简描述、移到 references/ | | 脚本输出 | stdout 长度、错误信息 | 输出摘要而非全量 | | 中间对话 | AI 追问、确认步骤 | SOP 设计得更清晰，减少交互轮次 |
实际测量（以 spending-analysis 为例）：
| 文件/模块 | 字符数 | 估算 Token | 占比 | | — | — | — | — | | SKILL.md | ~4,200 | ~2,100 | 100% | | parse_bills.py 输出（典型） | ~15,000 | ~7,500 | 需读入上下文 | | classify_report.py 输出 | ~3,000 | ~1,500 | 需读入上下文 |
优化策略：
- SKILL.md 瘦身：将长篇幅的分类词典移到
references/category_rules.md，SKILL.md 中只保留摘要表格 - 脚本输出控制：输出 summary 而非 full dump，提供
--verbose开关用于调试 - 关键信息前置：把最重要的指令放在 SKILL.md 前面，因为 LLM 对文档首尾的注意力更高
5.2 性能优化策略
CPU/IO 密集型优化的常见手段：
| 策略 | 适用场景 | 实现方式 | | — | — | — | | 中间结果缓存 | 解析阶段耗时 | 检测源文件 mtime，未变则跳过重解析 | | 增量处理 | 追加数据场景 | 只处理新文件，合并到已有 normalized.json | | 延迟加载 | 报告生成耗时 | 先产出摘要，详情按需生成 | | 并发执行 | 多平台解析互不依赖 | 并行读取三个平台，最后 merge |
实际案例：_normalized.json 作为缓存：
首次执行: CSV → parse → 300 条 ├─→ _normalized.json（写入磁盘） XLSX → parse → 200 条 ┤ PDF → parse → 50 条 ┘ → classify_report 读取 _normalized.json 修改分类规则后重跑: 跳过 parse 阶段（源文件未变） → classify_report 直接读取已有的 _normalized.json → 节省约 60% 总耗时
5.3 宿主资源消耗
需要注意的资源上限：
| 资源 | 典型限制 | 注意事项 | | — | — | — | | 磁盘 IO | 无硬限制 | 避免在循环中反复读写大文件 | | 内存 | ~512MB（视环境） | 大 Excel 用 openpyxl read_only 模式 | | 网络 | 超时 5-10s | 自动更新检查必须设短超时 | | 执行时间 | 默认无硬限制 | 长时间任务提供进度反馈 | | 模型下载 | OCR 模型 ~100MB | 首次运行提示用户 |
六、Skill 测试
6.1 测试策略
Skill 的测试分三层：
L1 单元测试：独立函数测试 → parse_amount(”¥35.80”) == 35.80 → 编码检测返回正确字符串 L2 集成测试：管道阶段测试 → 输入 fixtures/sample_alipay.csv → 输出标准化 JSON → 输入 fixtures/_normalized.json → 输出 Excel 报告 L3 端到端测试：完整流程 → 目录中有 3 个平台文件 → 跑全流程 → 验证报告生成
推荐的测试结构：
skill-name/├── tests/│ ├── fixtures/ # 测试数据│ │ ├── alipay_sample.csv│ │ ├── wechat_sample.xlsx│ │ ├── cmb_sample.pdf│ │ └── expected_output.json│ ├── test_parse.py # L1 + L2│ ├── test_classify.py # L1 + L2│ └── test_e2e.py # L3
6.2 测试数据管理
fixtures 设计原则：
| 原则 | 说明 | | — | — | | 匿名化 | 替换真实姓名、卡号为占位符（如「张**」「6222****」） | | 边界覆盖 | 空文件、超大金额、特殊字符商户名、跨月记录 | | 最小化 | 每个 fixture 只覆盖它需要测的场景，不要一个文件测所有 | | 可版本化 | fixtures 随 git 提交，不依赖外部数据源 |
spending-analysis 测试用例示例：
# tests/test_parse.pydef test_parse_amount(): assert parse_amount(”¥35.80”) == 35.80 assert parse_amount(”1,234.56”) == 1234.56 assert parse_amount(””) == 0.0 assert parse_amount(”-99.00”) == -99.00 def test_parse_alipay_csv(): result = parse_alipay(”fixtures/alipay_sample.csv”) assert len(result) == 15 assert result[0][”platform”] == ”支付宝” assert result[0][”date”].startswith(”2026-”) def test_encoding_detection(): # GBK 编码文件能被正确识别 content = detect_encoding(”fixtures/alipay_gbk.csv”) assert ”交易记录” in content
6.3 自动化测试集成
CI 友好的测试配置：
# 通过环境变量禁用需要网络/交互的功能SKILL_NO_UPDATE_CHECK=1 # 跳过自动更新检查SKILL_TEST_MODE=1 # 跳过耗时操作
# CI 中跑测试SKILL_NO_UPDATE_CHECK=1 pytest tests/ -v
七、版本管理
7.1 SemVer 策略
MAJOR.MINOR.PATCHMAJOR → 不向后兼容的变更（分类体系重构、JSON 格式变化）MINOR → 向后兼容的新功能（新增指标、新增平台支持）PATCH → 向后兼容的 Bug 修复（金额解析修正、编码问题）
实际版本演进示例：
1.0.0 初始版本：三平台解析 + 分类 + 报告1.1.0 新增：消费指标分析 + 可消减建议（向后兼容）1.2.0 新增：信用卡关联去重（向后兼容）1.2.1 修复：招行 PDF 金额符号解析错误2.0.0 重构：分类体系从 10 类变成新的分类标准（Breaking Change）
7.2 自动更新机制
更新检查流程：
用户执行脚本 │ ├── 检查环境变量 SKILL_NO_UPDATE_CHECK │ └──=1 → 跳过更新检查 │ └── 读取 version.json ├── 获取本地版本号 (1.0.0) └── HTTP GET → 远程 version.json (超时 5s) ├── 网络不通 → 静默跳过（不阻塞用户操作） ├── 版本相同 → 静默跳过 └── 远程更新 (1.1.0) → 打印更新提示: 🔔 spending-analysis 有新版本可用！ 当前版本: v1.0.0 → 最新版本: v1.1.0 更新方式: git pull
设计要点：
- 绝对静默：网络失败、超时不应打扰用户
- 非阻塞：更新检查不能拖慢核心功能
- 可关闭：提供环境变量
SKILL_NO_UPDATE_CHECK=1 - 版本比较可靠：MAJOR → MINOR → PATCH 逐级比较，而非字符串比较
7.3 Changelog 管理
两种 Changelog：
| 类型 | 存放位置 | 读者 | 写法 | | — | — | — | — | | SKILL.md Changelog | SKILL.md 底部或 references/changelog.md | 用户 | 简洁、只说新增能力和改进 | | version.json Changelog | version.json 的 changelog 字段 | 脚本（自动更新展示） | 结构化、每条一行 |
Changelog 规范：
## v1.2.0 (2026-08-15)
### 新增- 信用卡还款自动关联：检测招行信用卡还款记录，关联到当月消费- 新增「周末vs工作日」消费节奏对比 ### 改进- 微信 XLSX 表头行检测更鲁棒，兼容更多导出格式- PDF 解析从 pdfplumber 迁移到 PyMuPDF，速度提升 3x ### 修复- 金额为 0 的记录不再被错误分类为「支出」
八、安全与权限控制
8.1 文件系统安全
常见风险和防御：
| 风险 | 防御措施 |
| — | — |
| 路径遍历（../../etc/passwd） | 限制工作目录为 bills/{月份}/，拒绝 .. |
| 覆盖系统文件 | 输出目录固定为 report/{月份}/，不写入项目外 |
| 读取敏感配置 | .gitignore 排除 ~/.ssh/、.env 等 |
| 大量文件 IO | 限制单次处理文件数、总大小上限 |
工作目录边界控制：
# ✅ 安全：限定在项目子目录bills_dir = Path(”bills”) / monthreport_dir = Path(”report”) / month # ❌ 不安全：接受任意绝对路径bills_dir = Path(user_input) # 可能指向 /etc/
8.2 网络与外部依赖安全
HTTP 请求安全清单：
| 检查项 | 实现 |
| — | — |
| 超时控制 | timeout=5 （防止无限挂起） |
| URL 验证 | 只允许 HTTPS、白名单域名 |
| 重定向控制 | 不跟随重定向到非白名单域名 |
| 证书验证 | 默认开启 SSL 验证 |
| 用户代理 | 设置明确的 User-Agent |
# ✅ 安全的 HTTP 请求req = Request(update_url, headers={”User-Agent”: ”skill-updater/1.0”})with urlopen(req, timeout=5) as resp: data = json.loads(resp.read())
8.3 敏感数据处理
# ❌ 不要硬编码 API Key 或 TokenAPI_KEY = ”sk-1234567890abcdef” # ✅ 从环境变量读取import osAPI_KEY = os.environ.get(”SKILL_API_KEY”) # ✅ 输出前脱敏print(f”使用 API Key: {API_KEY[:4]}****”)
敏感数据保护原则：
| 原则 | 说明 | | — | — | | 不落地 | 中间 JSON 不写入真实姓名、完整卡号 | | 可配置 | 敏感值通过环境变量传入，不写入代码 | | 日志脱敏 | 打印信息时脱敏处理 | | 测试隔离 | 测试 fixtures 使用匿名化数据 |
8.4 SSH 与 Git 安全
密钥管理最佳实践：
# 为 Skill 创建专用密钥（不要复用个人 GitHub 密钥）ssh-keygen -t ed25519 -C ”skill-sync” -f ~/.ssh/id_ed25519_skill # 配置专用 HostHost skill-repo HostName gitee.com User git IdentityFile ~/.ssh/id_ed25519_skill IdentitiesOnly yes
安全清单：
-
使用 ed25519 而非 RSA（更短更安全）
-
一个 Skill 一个密钥（最小权限原则）
-
仓库设为私有（如不需要公开）
-
.gitignore排除密钥文件
九、分发与生态
9.1 分发方式对比
| 方式 | 适用场景 | 优点 | 缺点 | | — | — | — | — | | Git 私有仓库 | 个人使用、小团队 | 版本控制、自动更新 | 需配置 SSH | | Zip 打包 | 单次分享、跨设备迁移 | 不需要 Git | 无自动更新 | | 公开市场 | 社区贡献 | 被搜索和安装 | 需要审核 | | 项目内嵌 | 团队协作 | 随项目拉取 | 更新需手动同步 |
9.2 Zip 打包规范
# 打包（排除不必要的文件）cd skill-name/zip -r ../skill-name-v1.0.0.zip . \ -x ”.git/*” ”__pycache__/*” ”*.pyc” ”.DS_Store” \ ”tests/*” ”bills/*” ”report/*”# 验证unzip -l ../skill-name-v1.0.0.zip
9.3 README.md 写作建议
README 面向人类用户，回答：
- 一句话简介——这是什么？
- 快速开始——我最快怎么用上？
- 常见问题——可能会遇到什么问题？
- 依赖安装——需要什么环境？
十、参考链接
官方资源
| 资源 | 链接 | | — | — | | Anthropic Skills 官方仓库 | https://github.com/anthropics/skills | | Anthropic Skills 文档 | https://docs.anthropic.com/en/docs/agents-and-tools/agent-skills | | Claude Code 文档 | https://docs.anthropic.com/en/docs/claude-code |
社区与生态
| 资源 | 链接 | | — | — | | MCP (Model Context Protocol) | https://modelcontextprotocol.io | | Awesome Claude Skills 合集 | https://github.com/topics/claude-skills |
相关技术栈
| 技术 | 用途 | 链接 | | — | — | — | | openpyxl | Excel 读写 | https://openpyxl.readthedocs.io | | PyMuPDF | PDF 文本提取 | https://pymupdf.readthedocs.io | | SemVer | 语义化版本规范 | https://semver.org | | python-dotenv | 环境变量管理 | https://github.com/theskumar/python-dotenv |
免责声明：
本文所载程序、技术方法仅面向合法合规的安全研究与教学场景，旨在提升网络安全防护能力，具有明确的技术研究属性。
任何单位或个人未经授权，将本文内容用于攻击、破坏等非法用途的，由此引发的全部法律责任、民事赔偿及连带责任，均由行为人独立承担，本站不承担任何连带责任。
本站内容均为技术交流与知识分享目的发布，若存在版权侵权或其他异议，请通过邮件联系处理，具体联系方式可点击页面上方的联系我。
本文转载自：一路狂飚的蜗牛 黄鹂儿 黄鹂儿《AI Skills 开发完全指南》
版权声明
本站仅做备份收录，仅供研究与教学参考之用。
读者将信息用于其他用途的，全部法律及连带责任由读者自行承担，本站不承担任何责任。
评论