khazix-skills 详细介绍：开源项目架构、功能与实践指南

项目速览（TL;DR）

khazix-skills 是一组遵循智能体技能（Agent Skills）开放标准的结构化指令集，面向 Claude Code、Codex、Qoder、Kimi Code、iFlow、CodeBuddy、Cursor 等支持该标准的智能体工具。项目重点不是提供一个独立运行的聊天应用，而是把目标定义、磁盘分析、资讯查询、文档审计、研究分析和写作流程封装为可加载的 Skill。

根据仓库元信息，项目默认分支为 main，主要语言标记为 Python，采用 MIT 许可证；当前资料记录的仓库数据为 20,754 Star 和 2,204 Fork。Star 与 Fork 属于时间点数据，发布时应以 GitHub 页面显示值为准。

“这里的每个 Skill 都是 Agent 能直接加载的结构化指令集，遵循 Agent Skills 开放标准。Claude Code、Codex、Qoder、Kimi Code、iFlow、CodeBuddy、Cursor 等 40+ 支持该标准的 Agent 都能装。”

定位与目标用户

这个仓库解决的是“如何把可重复的智能体工作方法封装并复用”，而不是“如何训练或托管一个模型”。使用者需要已经拥有支持 Skill、项目规则文件或长文本指令的智能体环境。

每个 Skill 通过 SKILL.md 表达执行规则、触发方式和预期产物。对于不直接支持 Agent Skills 的工具，README 给出的降级方案是下载相应目录中的 SKILL.md，将其作为项目规则文件，或者把全文粘贴进对话。

• 需要把模糊需求转化为长程智能体目标的开发者，可使用 leader。
• 需要在本机审查磁盘占用并保留人工删除确认的用户，可评估 storage-analyzer。
• 需要按日期获取 AI HOT 日报或动态的用户，可使用 aihot。
• 需要同步项目文档、智能体规则与记忆的团队，可评估 neat-freak。
• 需要研究报告或特定写作风格工作流的内容生产者，可分别评估 hv-analysis 与 khazix-writer。

核心功能与能力矩阵

README 当前列出六项能力，每项 Skill 都围绕一个明确任务组织输入和输出。不同 Skill 的自动化边界不同，其中磁盘分析涉及本地文件操作，目标定义则主要产出 Markdown 任务书。

leader：从模糊需求到可验收目标

leader 的核心不是直接执行开发任务，而是先定义目标。根据 README，它会进入代码库进行实测调研，再向用户提出不超过 5 个必须由用户决定的问题，最终输出可交给目标模式或普通 Agent 执行的 Markdown 任务书。

它使用“目的、完成态、证据、反作弊、地界、取舍、未知”七类问题约束目标，并把未经验证的文档信息视为需要实测的内容。任务书强调可机器判断的完成状态、实际命令输出形式的验收证据、禁止的捷径、范围白名单、停止条件及待裁决清单。

storage-analyzer：带分级决策的本机磁盘分析

storage-analyzer 接收自然语言磁盘检查请求，对整机磁盘执行只读扫描，并在浏览器中打开交互式 HTML 报告。报告包含磁盘总览、占用 Top 5、清理优先级以及绿、黄、红三类处置级别。

绿色项被定义为可自动再生的缓存或临时文件；黄色项包含离线视频、下载或项目代码等用户数据；红色项属于运行中应用的核心数据或系统文件。删除并非扫描阶段的默认动作，README 要求用户在浏览器按钮和浏览器确认框中完成两次显式确认。

aihot：自然语言资讯查询

aihot 用于从 AI HOT 服务获取每日资讯。README 明确说明它无需 API Key，也不要求配置模型上下文协议服务器（Model Context Protocol server，MCP server）。

输入是今日或指定日期的查询意图，输出是对应的 AI HOT 日报及 AI 动态。所给 README 片段在该功能说明处截断，支持的完整筛选条件、返回字段、速率限制和失败响应均未提供，建议以最新 README 和对应 SKILL.md 为准。

neat-freak、hv-analysis 与 khazix-writer

neat-freak 在任务完成后由 /neat 触发，目标是让项目文档、CLAUDE.md 与 Agent 记忆保持一致，并审计既有规则是否真正执行。资料没有给出冲突解决顺序、文件白名单或回滚机制，因此在重要仓库中使用前应先审查其 SKILL.md。

hv-analysis 将产品、公司或概念作为研究对象，README 将其产物描述为万字 PDF 报告；khazix-writer 则将仓库作者的写作口吻和节奏封装为长文写作规则。两者的内部提示模板、检索来源、引用规范和事实校验实现未出现在所给资料中，不能据此推断其报告质量或内容准确率。

系统架构与关键模块

该项目可从资料中确认的组织核心是“独立 Skill 目录加 SKILL.md”，由外部 Agent 负责加载和执行。仓库不是单一常驻服务，各项能力是否启动本地程序取决于具体 Skill。

技能描述层

README 为已公开的 Skill 提供了形如 ./leader/SKILL.md、./storage-analyzer/SKILL.md 的入口。SKILL.md 承担结构化指令集角色，支持 Skill 标准的 Agent 可将其安装到对应目录，不支持该标准的工具则以规则文件或对话上下文方式加载。

智能体执行层

Agent 负责解释自然语言触发词、读取 Skill 规则、调用自身可用工具并生成产物。模型供应商、模型版本、工具权限和上下文容量不由仓库资料统一规定，因此同一 Skill 在不同 Agent 中的执行结果不能视为完全一致。

本地辅助服务层

资料明确提到本地服务的只有 storage-analyzer。该服务绑定 127.0.0.1，端口随机分配，并带 token；浏览器中的处置按钮受到绿色可删除、黄色仅移入废纸篓、红色仅打开目录的分级白名单约束。

根据本文作者的经验判断，这种分层意图是把“分析建议”和“具有副作用的文件操作”分离，但仓库资料没有给出服务进程生命周期、token 长度、请求接口和并发模型。相关细节应以该 Skill 的实际代码与最新文档为准。

依赖与运行环境

仓库元信息将 Python 标记为主要语言，但所给资料没有列出 Python 版本、包管理器或第三方依赖清单。不能仅依据语言标签推导安装命令，也不能假定每个 Skill 都需要本机 Python 运行时。

• Agent 环境：需要支持 Agent Skills，或至少支持加载项目规则文件、粘贴长文本指令。
• 已明确兼容的工具示例：Claude Code、Codex、Qoder、Kimi Code、iFlow、CodeBuddy、Cursor。
• 操作系统：storage-analyzer 已在 macOS 完整实测；README 表示 Windows 代码已就绪并支持多盘符，但首次使用需要谨慎核对。
• 浏览器：storage-analyzer 需要在浏览器打开交互式 HTML 报告，具体浏览器版本未提供。
• 网络：aihot 需要访问 AI HOT 站点；代理、超时、离线模式和网络白名单要求未提供。

requirements.txt、pyproject.toml、锁文件及 Python 最低版本的信息未包含在所给资料中。安装依赖前应直接检查默认分支中的实际文件，不应凭语言元信息执行未经确认的包安装命令。

快速开始：安装、运行与验证

README 推荐直接向支持 Agent Skills 的 Agent 发出安装请求，由 Agent 将目标目录克隆到其对应的技能目录。下面内容是发送给 Agent 的自然语言指令，不是操作系统终端脚本。

第一步：安装一个 Skill

帮我安装这个 skill：https://github.com/KKKKhazix/khazix-skills/tree/main/neat-freak

安装位置由具体 Agent 管理，README 没有提供统一目录。执行前应确认 Agent 展示的来源 URL 指向该仓库的 main/neat-freak 目录，避免加载名称相同但来源不同的规则文件。

第二步：触发运行

/neat

根据 README，/neat 用于在工作完成后触发文档、CLAUDE.md、Agent 记忆对齐以及规则执行审计。该命令会修改哪些文件、是否先输出差异预览，所给资料没有说明；首次执行宜在具备版本控制和可恢复副本的测试仓库中进行。

第三步：验证结果

请列出本次 /neat 检查过的文件、发现的不一致项、实际修改项，以及未执行规则的审计结果。

这条验证请求用于要求 Agent 显式汇报结果，不代表仓库定义了名为“验证”的独立命令。官方仓库未提供统一测试命令、成功退出码或自动验收脚本，验证时应结合版本控制差异逐项复核。

配置说明

所给资料未包含 .env.example、配置文件样例或统一配置章节，因此没有可核实的环境变量名和默认值。下表仅整理 README 明确描述的运行设置与缺失项，不将其虚构成可直接写入配置文件的字段。

进阶用法

进阶使用的重点是把 Skill 串成有边界的工作流，而不是把所有规则同时塞入同一上下文。每一步都应保留明确输入、产物和人工检查点，避免上游误差未经核验地进入下游。

使用 leader 编写长程任务书

可以先向 leader 提供一句模糊需求，例如“帮我给 agent 写个目标”或“让 agent 自己跑这个项目”。它会先调研实际代码库，再围绕必须由人决定的事项提问，最终输出纯 Markdown。

帮我详细拆一下这个目标：修复当前项目的失败测试，并给出可复核的验收证据。

“修复失败测试”只是用户输入示例，具体目标约束仍应由 Skill 调研后生成。README 特别强调反作弊要求，例如不能通过删除测试来实现“测试变绿”，同时每条验收需要附实际命令输出。

在不支持 Skill 的 Agent 中降级使用

如果 Agent 不支持 Agent Skills，README 给出的方案是下载目标目录中的 SKILL.md 全文，将其作为项目规则文件或直接贴入对话。此方式省略了标准化安装过程，但不会自动解决上下文长度、规则优先级和工具授权问题。

资料将两种方式描述为效果一致，但未提供跨 Agent 的一致性测试数据。对需要审计的工作流，应保存使用的 SKILL.md 提交版本、Agent 名称、模型标识及最终产物，以便复现。

使用 storage-analyzer 进行受控清理

帮我看看存储

触发后先阅读报告中的具体路径、文件类型、删除影响和推荐处置方式，再决定是否操作。黄色项目只应在确认用户数据价值后移入废纸篓，红色项目按照 README 的设计不提供删除按钮。

与 README 提及方案的场景选择

README 只对 storage-analyzer 与 CleanMyMac 做了明确比较，因此本节不扩展到其他未在资料中出现的替代产品。选择依据应集中在解释粒度、操作边界和平台验证状态。

• 需要 Agent 根据具体路径解释文件类型、删除影响和处置方式时，可评估 storage-analyzer。
• 需要固定规则、成熟图形界面以及供应商提供的产品支持时，应自行评估 README 提及的 CleanMyMac；仓库资料没有提供功能完整度、价格或支持条款对照。
• 需要在 Windows 环境执行高风险清理时，不应只依据“代码就绪”直接操作，因为 README 只明确写明 macOS 完整实测。
• 需要可追踪的人工确认时，storage-analyzer 的分级按钮和二次确认机制更符合仓库描述的工作方式。

可观测性与运维

项目没有统一的服务级可观测性方案，资料中也没有指标端点、日志格式、追踪系统、健康检查或告警规则。可核实的观察手段主要来自各 Skill 的输出产物和智能体执行记录。

• leader 要求验收项附带实际命令输出，这些输出可作为任务完成证据。
• storage-analyzer 通过 HTML 报告展示磁盘总览、占用 Top 5、优先级和分级处置清单。
• neat-freak 包含规则执行审计，但审计日志格式和保存位置未提供。
• aihot 的请求日志、缓存策略、上游可用性和错误重试策略未提供。

运维时应保留仓库提交号、所安装 Skill 的文件内容、Agent 执行记录和实际文件差异。服务级别协议（Service Level Agreement，SLA）、性能基准、并发容量和故障恢复目标均未在资料中声明，不能将该项目视为带商业可用性承诺的托管服务。

安全与合规边界

主要风险集中在本地文件读取、文件删除、项目代码访问和外部资讯访问。使用者应只在自己拥有或明确获授权的设备、仓库和数据范围内运行，并在授予 Agent 工具权限前审查对应 SKILL.md 与代码。

本地文件与删除操作

storage-analyzer 扫描磁盘时会接触文件路径和占用信息。README 声明扫描阶段只读，并要求删除动作经过浏览器按钮和确认框两次确认；这不等于删除后可恢复，也不替代数据备份。

报告服务仅监听 127.0.0.1 并使用随机端口及 token。token 的强度、过期时间、存储位置和跨站请求防护没有在资料中披露，不应将该本地服务暴露到局域网或公网。

项目代码、记忆与文档

leader 需要进入代码库实测，neat-freak 会处理项目文档、CLAUDE.md 和 Agent 记忆。若仓库包含商业秘密、个人信息或受合同限制的数据，应先核对所用 Agent 的数据处理条款，并限制其读取范围。

官方资料没有说明遥测、数据留存、云端传输或隐私政策。对于有数据驻留、审计留痕或最小权限要求的组织，缺失这些信息本身就是上线前需要解决的审查项。

外部内容与生成内容

aihot 会访问外部资讯服务，hv-analysis 和 khazix-writer 会生成可传播内容。使用者需要自行核验事实、来源、版权、商标、个人信息及发布平台规则，不能把模型生成结果直接视为经过法律或编辑审核的材料。

许可证与商用条款

仓库使用 MIT License，版权声明为“Copyright (c) 2026 数字生命卡兹克”。该许可证允许免费使用、复制、修改、合并、发布、分发、再许可和销售软件副本，因此许可证文本本身允许商业使用。

• 分发软件或其重要部分时，必须保留原版权声明和许可声明。
• 软件按“原样”提供，不附带明示或默示保证，包括适销性、特定用途适用性和不侵权保证。
• 作者或版权持有人不对因软件或其使用产生的索赔、损害及其他责任负责。
• MIT 许可覆盖仓库软件与文档，不自动授予第三方模型、资讯内容、商标、平台账号或外部服务的权利。

如果将 Skill 集成到商业产品，还需分别检查所用 Agent、模型服务、外部数据源和发布平台条款。仓库资料没有提供商业支持、赔偿承诺或单独企业许可证，具体法律判断以仓库 LICENSE 和适用法律为准。

局限性与已知限制

当前资料足以确认项目定位和主要能力，但不足以建立完整的部署、测试和生产保障结论。以下限制均直接来自资料缺失或 README 已明确的验证边界。

• 没有提供 Python 版本、依赖列表、锁文件内容或统一安装脚本，无法从现有资料复现 Python 环境。
• 没有统一测试命令、覆盖率、持续集成状态、性能基准、并发数据和资源消耗记录。
• storage-analyzer 在 macOS 完整实测；Windows 虽声明代码就绪并支持多盘符，但 README 要求首次使用谨慎。
• aihot 的完整能力说明在所给资料中被截断，无法确认全部过滤参数、返回结构和错误处理。
• hv-analysis 的“万字 PDF”是 README 对产物形态的描述，不构成字数、事实准确率或交付时间保证。
• khazix-writer 聚焦特定作者风格，不等同于通用品牌语调系统，也没有提供版权与风格授权说明。
• “40+ Agents 兼容”来自 README 声明，所给资料没有列出完整兼容矩阵、版本范围或自动化验证结果。
• Agent 执行行为依赖模型、工具权限与上下文，同一指令集无法据此保证完全一致的输出。

适合谁

采用该项目的前提是团队已经把 Agent 纳入日常开发或内容流程，并愿意审查结构化指令与执行结果。以下信号可用于判断是否值得试用。

• 团队使用 Claude Code、Codex 或 README 点名的其他兼容 Agent，并允许从指定 GitHub 目录安装 Skill。
• 任务经常从模糊需求开始，需要明确完成态、证据、禁止路径、范围和取舍优先级。
• 项目已经使用 CLAUDE.md、Agent 记忆或类似规则文件，并面临文档与实际执行不一致的问题。
• 本机磁盘清理需要逐路径解释和人工确认，而不是无提示地批量删除。
• 团队能在版本控制仓库或隔离测试环境中先验证 Skill，并能审阅 Agent 产生的文件差异。

不适合谁

如果组织要求完整的生产保障、集中策略控制或经过认证的合规材料，仅凭现有仓库资料不足以满足要求。以下任一信号出现时，应先补齐审计和工程验证，而不是直接接入生产流程。

• 环境禁止 Agent 读取代码库、用户目录、磁盘路径或向外部站点发起请求。
• 采购或合规要求供应商 SLA、数据处理协议、隐私政策、审计报告和商业赔偿，而仓库没有提供这些文件。
• 需要明确的 Python 版本、依赖锁定、离线安装包、长期支持分支和兼容性版本矩阵。
• 希望磁盘清理完全无人值守，无法接受人工确认；这与 storage-analyzer 的安全设计边界冲突。
• 要求生成的研究报告或文章无需人工事实核验即可发布，现有资料没有提供此类准确性保证。

常见问题与排查（FAQ / Troubleshooting）

排查顺序应从 Skill 来源、Agent 兼容性、规则是否加载、工具权限和产物核验开始。由于仓库没有提供统一诊断命令，下列方法以 README 明确的使用模型为边界。

Agent 不支持 Skill，是否还能使用

可以。下载对应目录中的 SKILL.md 全文，将其作为项目规则文件，或者直接粘贴进对话并要求 Agent 按照其中规则执行。

安装后自然语言没有触发对应能力

先确认安装 URL 指向正确目录，再使用 README 给出的触发语。例如 storage-analyzer 可使用“帮我看看存储”“C 盘满了”“清理一下磁盘”“看下电脑空间”或“storage analysis”。

若仍未触发，应检查 Agent 是否实际加载了该 SKILL.md、是否存在同名规则冲突，以及文件和工具权限是否被禁用。Agent 专属的技能搜索路径未在资料中统一说明，应查阅对应 Agent 文档。

storage-analyzer 报告无法打开

确认 Agent 是否成功启动绑定于 127.0.0.1 的本地服务，并检查它返回的随机端口与 token 是否完整。官方仓库未提供固定端口、健康检查 URL 和日志路径，无法给出更具体的接口级诊断命令。

报告中的黄色或红色项目无法直接删除

这是 README 描述的安全策略，不应视为故障。黄色项目仅提供在文件管理器中打开或移入废纸篓的受限处置，红色项目只解释风险并允许打开目录。

leader 生成的目标仍然不可验收

检查任务书是否包含目的、完成态、证据、反作弊、范围、取舍和未知事项七类信息，并确认验收项是否要求实际命令输出。如果关键业务取舍仍未确定，应先补充人工决定，不要让执行 Agent 自行猜测。

能否直接在 Windows 上执行磁盘清理

README 表示 Windows 代码已就绪并支持多盘符，但完整实测状态只明确给到 macOS。Windows 首次运行应使用非关键设备或可恢复测试环境，先执行只读扫描，并逐项核对路径语义后再决定是否移动文件。

是否需要为 aihot 配置密钥

根据 README，不需要 API Key，也不需要配置 MCP server。网络访问失败时所需的代理、证书、重试或超时设置未在所给资料中提供。

是否有 Docker、Web API 或集中部署方式

官方仓库未在所给资料中提供该信息，建议以最新 README 为准。不能依据 storage-analyzer 存在本地服务就推断整个仓库提供通用 Web API 或容器部署方案。

采用建议

更稳妥的接入方式是按单个 Skill 逐项审查，而不是一次安装全部能力。先在测试仓库或可恢复设备中记录基线，再授予满足任务所需的最小工具权限。

1. 固定仓库提交或保存所用 SKILL.md，避免规则更新后无法复现。
2. 审查 Skill 将读取、修改或上传的数据范围，移除不必要的权限。
3. 先运行无副作用的分析流程，检查输出是否符合预期。
4. 对文件修改和删除保留版本控制、废纸篓或独立备份。
5. 将生成内容视为待审稿件，对事实、引用、版权和敏感信息进行人工复核。

根据本文作者的经验判断，leader 适合作为低风险入口，因为其主要产物是可审阅的 Markdown 任务书；涉及磁盘操作的 storage-analyzer 则应在完成代码审查与备份后再启用处置按钮。这一排序属于风险控制建议，不是仓库提供的官方实施承诺。

项目地址与资源

以下链接均来自仓库信息或 README。访问外部服务时应分别核对其最新使用条款、隐私政策和内容授权范围。

• khazix-skills GitHub 仓库
• Agent Skills 开放标准官网
• AI HOT 官方站点
• leader Skill 目录
• storage-analyzer Skill 目录
• aihot Skill 目录
• neat-freak Skill 目录
• hv-analysis Skill 目录
• khazix-writer Skill 目录
• storage-analyzer 公众号讲解
• neat-freak 公众号讲解
• hv-analysis 公众号讲解
• khazix-writer 公众号讲解