这次我们看的是一个 AI Agent 技能仓库mvanhorn/last30days-skill。它算不上那种“模型 WebUI 一键启动”的重量级项目而是一个典型的 Skill 项目——把某类任务的经验、规则、脚本和提示词打包成一个可复用的能力模块让 Claude Code、Codex、OpenCode 这类 Agent 在需要时自动加载。从仓库命名看last30days大概率与“最近 30 天”的时间窗口有关典型用途是让 Agent 基于最近 30 天的提交记录、Issue、讨论、日志或业务数据生成周报或月报、做趋势分析、梳理变更清单。这篇文章我会按 CSDN 技术博客的结构来写先给你一个可以快速判断价值的速览表再说明适用场景和环境准备然后给出从 GitHub 拉取、安装、验证到自定义 Skill 的完整流程。整个过程中我会把“Skill 是什么、Skill 和 Agent 的区别、Codex/Claude Code 怎么装 Skill、怎么自己写一个 Skill”这几个高频问题一起讲清楚。如果你正在研究 AI Agent 的可复用技能封装或者想给自己的编程助手加一个“30 天回顾”工作流这篇可以直接收藏。需要强调一点因为mvanhorn/last30days-skill的具体仓库说明文本不在手边文中涉及目录结构和命令的地方我会按当前 Agent Skill 生态的通用实践来写同时标注“以仓库 README 为准”。这样你在实际操作时不会被我带偏也能快速定位问题。1. 核心能力速览能力项说明项目类型Agent Skill 技能包面向 Claude Code / Codex / OpenCode 等 Agent 生态核心功能让 Agent 自动加载“最近 30 天”相关的工作流、数据处理逻辑和输出规范项目来源GitHub 仓库 mvanhorn/last30days-skill作者 mvanhorn硬件要求本身不直接消耗 GPU 显存实际占用由承载 Agent 的模型决定显存占用与项目本身无关需按底层模型推理情况测试支持平台取决于 Agent 运行时常见的有 macOS、Linux、Windows 配合 WSL启动方式不是独立 Web 服务而是作为 Skill 被 Agent 动态加载是否支持 API一般通过 Agent CLI、MCP 或插件协议调用具体看仓库清单是否支持批量任务可以写批处理脚本逐条调用也可以依赖 Agent 自身循环执行适合场景月度回顾、30 天记录汇总、周期报告、变更梳理、数据整理把这个表看完你应该有一个基本判断这个项目不是“下载就能双击运行的软件”而是要放进一个 Agent 生态里使用的“技能包”。它的价值不在于界面而在于把一套任务流程固化下来让每次执行都更稳定。熟悉 Skill 生态的人拿到手会比较顺利第一次接触 Skill 的人也不用担心后面会逐步拆开讲。2. 适用场景与使用边界先说适合谁。如果你已经在用 Claude Code、Codex CLI、OpenCode 这类工具那你一定遇到过一个问题同样一类任务每次都要重新把规则、背景、格式要求讲一遍Agent 输出还不稳定。Skill 的作用就是把这套规则固化下来下次只要告诉 Agent“用 last30days-skill 处理一下”它就会按预设流程执行。last30days-skill更具体的场景取决于仓库里 SKILL.md 怎么定义。按命名推断常见的使用方向包括对最近 30 天的 Git 提交、PR、Issue 做汇总生成团队周报或个人月报。基于最近 30 天的日志、告警或监控数据做异常趋势分析。整理最近 30 天产生的文档、会议纪要、任务记录输出结构化清单。针对某个目录下的历史文件做周期归档或变更审查。再说使用边界。Skill 不是万能的它只是给 Agent 提供了工作流和约束实际效果仍然依赖底层模型的推理能力。如果输入数据特别庞大比如几十万行日志把全部内容塞进上下文会直接导致 token 消耗上升、响应变慢好的做法是先在脚本里做采样、聚合和筛选只把摘要交给模型。合规方面要特别注意。这个 Skill 很可能要处理一段时间窗口内的业务数据、代码提交、用户记录等。如果数据来源包含他人隐私、公司内部信息或未授权内容使用前必须确认授权范围。不要把带敏感信息的日志、聊天记录、客户数据直接丢给云上的模型服务如果必须处理建议优先选择本地部署模型或经过脱敏的数据集。涉及人脸、声音、版权素材的规则同样适用先授权再处理。3. 环境准备与前置条件last30days-skill本身不是一个完整的应用所以环境准备分两层一层是让它跑起来所依赖的 Agent 运行时另一层是你准备喂给它的数据源。系统层面先确认你的操作系统是否支持目标 Agent 工具。Claude Code、Codex CLI、OpenCode 这些工具在 macOS 和 Linux 上通常开箱即用Windows 上建议用 WSL 或 PowerShell 配合 Node.js/Python 环境。基础依赖一般包括Git用于克隆仓库、查看版本。Node.js 18 或 Python 3.10取决于 Skill 内是否包含辅助脚本具体版本要求以仓库 requirements.txt 或 package.json 为准。Agent CLIClaude Code、Codex、OpenCode 中的一个或多个。模型访问权限如果使用云模型需要对应账号的 API Key 或订阅如果使用本地模型需要提前部署 Ollama、LM Studio 或 vLLM 等推理服务。选择本地模型还是云模型会影响整个使用链路。如果你只是想在开源项目上做实验云模型接入最快开箱即用但如果你要处理的 30 天数据包含内部代码或敏感日志本地模型更稳妥。本地模型的代价是推理速度和显存规划需要自己解决通常建议先跑通 Skill 流程再根据隐私要求决定是否切换到本地推理。磁盘空间方面只有一个 Skill 包通常占不了多少空间几 MB 到几十 MB 而已。但如果你准备在本地处理 30 天的大文件要给输入目录和输出目录留出足够空间顺便确认是否有读写权限。端口占用不是这个项目的重点但如果你在 Agent 环境里同时启动了 MCP 服务或本地 API仍然要注意端口冲突。可以先执行下面的命令检查环境# 查看基础工具版本 git --version node --version 2/dev/null || echo Node.js 未安装 python3 --version 2/dev/null || echo Python 3 未安装 # 查看目标 Agent 是否已安装 codex --version 2/dev/null || echo Codex 未安装 claude --version 2/dev/null || echo Claude Code 未安装 opencode --version 2/dev/null || echo OpenCode 未安装这些命令不需要全部通过只要确认你计划使用的 Agent 可用就行。检查完环境后下一步就是从 GitHub 拉取项目。4. 安装部署与启动方式Skill 项目的“部署”和传统 Web 项目不一样。没有main.py启动入口也没有npm run dev你要做的是把 Skill 目录放到 Agent 能找到的位置然后让 Agent 加载它。很多第一次接触 Skill 的朋友会问“我拉下来了然后怎么运行”答案是不能直接运行。你要先理解 Agent 的工作方式Agent 启动后会根据用户任务决定是否需要加载某个 Skill而 Agent 加载 Skill 的方式通常是扫描指定目录读取 SKILL.md 或元数据文件。所以你的任务是让 Skill 出现在 Agent 能扫描到的地方。第一步从 GitHub 拉取仓库git clone https://github.com/mvanhorn/last30days-skill.git cd last30days-skill拉取之后先看目录里有什么。Skill 项目的典型结构大致是这样的last30days-skill/ ├── SKILL.md # 技能说明Agent 首先读取的文件 ├── skill.yaml # 元数据有的项目叫 skill.json ├── scripts/ # 辅助脚本比如数据拉取、聚合、清洗 ├── examples/ # 输入输出示例 ├── prompts/ # 提示词模板 └── README.md # 仓库说明不同 Agent 对 Skill 的格式要求不一样。有的要求 SKILL.md 放在固定目录有的要求使用特定清单文件。安装前先打开 README 或 SKILL.md 看一遍确认它适配的是 Claude Code、Codex 还是 OpenCode。以 Codex 为例常见做法是把 Skill 目录放入 Codex 的 skills 目录或者在配置文件里注册# 示例实际路径以 Codex 官方文档为准 mkdir -p ~/.codex/skills cp -r last30days-skill ~/.codex/skills/如果你用的是 Claude Code可能需要把 Skill 放到项目的.claude/skills目录或者通过插件系统注册。OpenCode 也有自己的 skill 安装命令一般是opencode skill install 目录或仓库。这里要重复一遍具体命令和目录名请以官方文档和仓库 README 为准不要直接照抄上面的路径。装好之后怎么验证“启动”成功Skill 没有进程它是在 Agent 对话或任务中被动态加载的。你可以直接给 Agent 发一条指令比如请加载 last30days-skill并基于当前目录最近 30 天的 git 提交记录生成一份变更摘要。如果 Agent 回复中出现了 Skill 定义的输出格式或者它开始调用 scripts 目录下的脚本说明加载成功。如果它完全没反应大概率是目录没放对或元数据格式不匹配。5. 功能测试与效果验证功能测试的核心是验证两件事Skill 能否被正确加载以及它定义的流程能否产出预期结果。我建议按下面 4 步走。5.1 基础加载测试先跑一个最小指令不看输出质量只看 Agent 能不能识别 Skill列出 last30days-skill 的能力并说明它适合处理哪些输入。预期结果是 Agent 能复述 SKILL.md 里定义的能力范围。如果它说“我没有找到这个 skill”先检查目录位置和注册配置。如果它复述的内容和 SKILL.md 不一致可能是缓存或版本问题重启 Agent 再试一次。5.2 输入数据准备准备一份测试数据。假如 Skill 面向 Git 提交记录你可以在一个测试仓库里构造最近 30 天的提交# 进入测试仓库如果是空仓库先初始化 git init echo test test.txt git add test.txt git commit -m initial commit git log --since30 days ago --oneline如果 Skill 面向的是日志或文档就准备一个 input 目录放入几个不同格式的样本文件。注意不要把生产数据直接拿来测试先用伪造或脱敏的小样本。这样既能验证流程又不会因为数据问题引发隐私风险。5.3 核心任务测试给 Agent 下达正式任务要求它按 Skill 流程处理刚才的数据按照 last30days-skill 的工作流程分析当前仓库最近 30 天的提交记录。 输出内容包括提交数量、主要变更方向、异常或风险点。判断成功的标准是输出结构符合 SKILL.md 定义的格式数据来源能追溯到你的测试样本整个流程没有中途停止。失败时先看有没有报错信息再检查脚本依赖是否完整。如果脚本报错优先看堆栈信息里的 Python 或 Node 路径确认依赖是否安装。5.4 边界条件测试边界测试建议覆盖三种情况数据不足如果某天没有任何提交或日志Skill 是否能正常输出“无变化”而不是报错。数据异常文件编码错误、空文件、超大文件是否会导致脚本崩溃。参数调整如果 Skill 支持配置时间窗口、输出语言等参数改掉之后表现是否稳定。这类测试不需要很复杂但能帮你提前发现大部分坑。遇到问题不要急着改 SKILL.md先定位是脚本逻辑、模型理解还是数据质量问题。通常脚本问题错误信息明确模型理解问题则是输出格式不对数据质量问题表现为结果和实际严重不符。6. Skill 与 Agent 的关系及自定义 Skill 编写方法很多人在搜索“skill 是不是就是高级版的 prompt”。从效果上看Skill 确实会包含提示词但它远不止提示词。一个完整的 Skill 通常包含任务定义、执行步骤、输入输出约束、辅助脚本和示例。Prompt 是文字Skill 是可执行的模块。再对比一下 Skill 和 Agent 的区别。Agent 是一个能够感知环境、规划步骤、调用工具并完成任务的运行实体Skill 是 Agent 可以加载的能力包。同一个 Agent 可以安装几十个 Skill处理不同类型任务时按需加载。也可以简单理解成Agent 是“大脑 执行器”Skill 是“岗位说明书 工具包”。Agent 负责决策Skill 负责提供特定场景下的标准做法。如果你了解这个关系后想自己写一个 Skill起点很低。新建一个目录写一个 SKILL.md再把需要的数据处理逻辑放进 scripts 目录。一个最小可用的 SKILL.md 模板大概是# 技能名称Last 30 Days Report ## 能力描述 基于指定目录或代码仓库最近 30 天的记录生成结构化汇总报告。 ## 触发方式 当用户提到“最近30天”“monthly review”“last 30 days”时自动考虑加载。 ## 输入参数 - input_path要扫描的目录或仓库路径默认当前目录 - date_from起始日期默认 30 天前 ## 执行步骤 1. 扫描输入路径收集最近 30 天的相关记录。 2. 对记录做去重、排序和基础统计。 3. 将统计结果整理为表格或摘要。 4. 输出 Markdown 报告包含变更数量、主要方向和风险点。 ## 输出格式 Markdown 报告包含 - 统计总览 - 变更明细 - 异常与建议写完 SKILL.md 后把脚本和示例放进去再按目标 Agent 的规范安装一遍一个属于自己的 Skill 就完成了。注意编写规范要参考目标平台文档例如 Codex Skill 的元数据字段、Claude Code 的 frontmatter 要求不同平台略有差异。不要只写一个 Markdown 文件就以为完事还要验证 Agent 能不能真正解析它。7. 接口 API、批量任务与可观测性这里先澄清一个概念Skill 本身一般不暴露独立 HTTP API。它是被 Agent 进程内加载的能力模块。但如果仓库里带有 MCP Server 或本地脚本则可能通过标准接口对外提供服务。实际接入方式要看last30days-skill是否包含 server 目录或 mcp 配置。如果要验证“接口”能力你可以观察 Agent 调用 Skill 时是否启动了本地子进程或监听端口。可以这样检查# 在 Agent 执行任务时另一个终端查看监听端口 netstat -an | grep -E LISTEN|LISTENING # 或查看进程 ps aux | grep -E last30days|node|python如果你是想做批量任务重点就不在 HTTP 接口而在怎么循环调用 Agent。常见的做法是写一个批处理脚本逐个读取输入文件调用 Agent CLI然后把输出写入独立目录。下面是一个 Python 调用示例模板具体命令要按你的 Agent CLI 调整import subprocess import pathlib input_dir pathlib.Path(./inputs) output_dir pathlib.Path(./outputs) output_dir.mkdir(exist_okTrue) for i, file in enumerate(sorted(input_dir.glob(*.md)), 1): prompt f使用 last30days-skill 处理 {file.name}输出 Markdown 报告。 result subprocess.run( [codex, exec, --prompt, prompt], # 以 Codex 为例实际命令按官方文档改 capture_outputTrue, textTrue, timeout300, ) out_file output_dir / f{i:03d}_{file.stem}_report.md out_file.write_text(result.stdout, encodingutf-8) print(f已完成: {file.name} - {out_file})批量任务必须考虑三点断点续跑、失败重试和输出隔离。可以把已完成文件名记录到一个清单里下次跳过对超时或非零退出码的样本单独放到 failed 目录之后统一重试。不要把所有输出都写到一个文件里否则后面很难定位问题。实际项目中单个样本失败往往是因为输入格式异常不是 Skill 本身的问题重试策略建议先检查失败原因再决定是否重跑。可观测性方面你至少要记录每次调用的输入、输出、耗时和退出码。简单做法是输出日志文件codex exec --prompt ... logs/run_$(date %Y%m%d_%H%M%S).log 21有了日志批量任务卡住时才能定位到具体是哪个样本、哪一步出了问题。如果日志量很大可以按日期分目录定期清理历史日志。8. 资源占用与性能观察Skill 本身不直接消耗 GPU 显存真正的资源消耗来自承载它的模型推理进程。你观察资源占用的重点应该是模型服务进程的 CPU 和内存占用。如果使用本地模型显存占用。Agent 的 token 消耗和上下文长度。如果你用的是 Codex、Claude 这类云端模型最需要关注的是 token 成本。last30days-skill如果一次性把 30 天的原始数据全塞给模型token 消耗会很高。更稳妥的做法是在脚本里先做聚合和采样把十万行日志压缩成几百行摘要再传给模型。这不是 Skill 自身能解决的问题而是使用方法的优化。如果是本地模型比如通过 Ollama 跑 Llama 3 或 Qwen显存占用会随上下文长度增加。30 天数据的汇总任务很容易触发长上下文你可以观察 8K、16K、32K 上下文下的响应时间和内存变化。这里不给你具体数字因为不同模型、不同量化版本的差异非常大以本机测试为准。实际生产中如果你发现响应速度明显下降最直接的调整方式是减小输入窗口或换用更快的量化版本。降低资源占用的常用手段用脚本预过滤输入只保留关键字段。把大文件拆成小块分批处理后再合并。关闭不必要的 MCP Server 和后台服务。批量任务加timeout避免单个样本卡死整个队列。改用本地轻量模型做初步过滤再用强模型做最终输出。进程残留也要留意。Agent 在调用 Skill 的子进程时偶尔会出现僵尸进程特别是脚本里开了网络请求或文件监听。批量跑完后可以用ps aux | grep last30days检查必要时手动清理。9. 常见问题与排查方法问题现象可能原因排查方式解决方案Agent 提示找不到 last30days-skill目录未放到正确位置或元数据格式不匹配检查 skills 目录和注册配置按平台文档放置或重新安装Skill 被加载但行为不符合预期SKILL.md 里的指令不清晰或模型理解偏差检查 SKILL.md 的执行步骤细化步骤增加示例脚本执行报错Python 或 Node 依赖缺失查看脚本报错和依赖声明安装 requirements.txt / package.json 依赖输出内容有幻觉数据输入源混乱或上下文不足核对输出与输入样本加强脚本预过滤输出注明数据来源批量任务中途卡住单条任务超时或网络阻塞查看日志和超时时间增加 timeout、断点续跑和失败目录本地模型推理很慢上下文过长或模型量化等级低观察显存和 token 统计压缩输入、缩短上下文、换更强设备端口被占用其他服务占用 Agent 或 MCP 端口netstat 查看端口修改端口配置或停掉冲突服务Git 提交扫描结果不对仓库没有 fetch 或时间参数写错先手动执行 git log 验证检查日期参数和仓库状态这里特别提醒一点当你遇到“输出不准确”时不要马上怀疑模型能力。先确认输入数据是否干净、时间范围是否正确、SKILL.md 里的执行步骤是否足够具体。很多问题出在流程定义而不是模型本身。如果问题反复出现可以把 SKILL.md 中的步骤拆得更细或者把脚本输出加入最终回复帮助定位是哪一步出现偏差。10. 最佳实践与使用建议第一先做最小验证再上批量。拿到last30days-skill后不要一上来就用生产数据跑完整流程。先用一个小仓库、两个样本文件跑通加载、执行、输出的闭环确认没问题再放大输入。这个步骤看起来简单但能省下后面排障的大量时间。第二保留一套最小可运行配置。把 Agent 版本、Skill 版本、目录结构、测试样例记录在项目的 README 里。以后环境变了你能快速恢复不用靠记忆。建议把这些信息维护在一个 docs/ 目录里包括安装命令、测试命令和常见问题。第三数据、脚本、输出严格分目录。建议这样组织project/ ├── skills/last30days-skill/ ├── inputs/ # 只放待处理数据 ├── outputs/ # 每次运行的结果按日期建子目录 └── logs/ # 运行日志和错误记录第四批量任务一定要加日志和失败重试。没有日志的批量任务是没法排障的。每次运行至少记录输入文件名、启动时间、退出码和输出路径。失败重试要设置最大次数避免死循环。第五涉及隐私和版权材料时先确认授权。这个 Skill 如果用来处理最近 30 天的聊天记录、日志、人工数据或未公开代码请先确认数据来源是否允许被模型处理。不要图省事把敏感信息直接发给云端 API。如果需要长期处理敏感数据建议部署私有化模型或者使用数据脱敏工具先做匿名化。第六发布或商用前要做效果复核。Skill 输出可能有偏差尤其是汇总类和趋势分析类任务。关键结论必须人工复核不能直接作为正式报告发布。可以建立一个人工抽查机制定期对比 Agent 输出和真实情况。11. 总结与下一步mvanhorn/last30days-skill这类项目最值得尝试的点是把“最近 30 天”这一类周期任务固化成 Agent 可加载的技能减少重复写提示词的负担。如果你已经在用 Agent 工具我建议先验证三件事Skill 能不能被正确加载、小样本下能不能稳定输出、批量跑 20 个文件后日志是否清晰。最容易踩的坑不是模型不够强而是目录放错、依赖缺失、输入数据没有预处理。下一步你可以沿着两条线深入一是把这个 Skill 改造得更贴合自己的数据源加入自己的统计口径和输出模板二是按照同样的方法编写第二个、第三个 Skill逐步积累自己的技能库。等你有一组可靠的 Skill 之后Agent 在不同项目之间的迁移成本会低很多。也可以把自定义 Skill 提交回开源社区让更多人在同样任务上少踩坑。建议先打开仓库把 README 和 SKILL.md 完整读一遍确认它的输入参数和输出格式。然后用一个 5 分钟的小测试跑通闭环再决定要不要集成到日常流程里。收藏这篇文章用不了一分钟下次遇到 Skill 加载不上时回来看第 9 节排查表会很快。