agent-skills

EASBot Agent 技能库 —— EASBot agent-skills 管理项目（无应用代码，保留根级维护脚本）。

English version: README.en.md

项目简介

agent-skills 是 EASBot 的 agent-skills 管理项目，聚合了 EASBot 内置（builtin）与工具（tools）类技能，供各类 Agent 加载、组合与复用。仓库本体不包含应用代码、无构建产物、无应用级测试套件；package.json 是元信息包（声明对 @easbot/agent 的依赖与 files 字段），已配 biome + lint-staged 仅供根维护脚本与各技能脚本本地开发使用，非 CI 强门禁（CI 只跑 quick-validate.ts，详见 AGENTS.md §2）。根 scripts/ 目录仅放项目级维护脚本（changelog 生成、版本号升级、docs 同步等），与各技能内部的 scripts/ 同根同源。每个技能遵循统一的 SKILL.md 规范，提供描述、触发场景、参考资料与脚本。

安装与使用

# 通过 EASBot CLI 安装全部技能
easbot skills add houjallen/agent-skills

# 或作为 npm 元包安装
npm install @easbot/agent-skills

easbot-agent-skills CLI（本仓库内置命令）

@easbot/agent-skills 包自带 easbot-agent-skills 可执行命令，是对 @easbot/skills 包的轻量宿主封装（host process wrapper）。所有技能管理（add / remove / list / find / update / store / doctor / use / init 等）都通过它调度，等价于 easbot-skills 与 easbot skills ...。

安装与启用

# 全局安装（推荐）
npm install -g @easbot/agent-skills

# 或在项目内局部安装
npm install @easbot/agent-skills

安装后 easbot-agent-skills 即可用；构建产物在 dist/cli.mjs（由 pnpm build 生成，package.json 的 bin 字段已注册）。

全局参数

| 参数 | 说明 | | --- | --- | | --help / -h | 打印完整帮助（顶层 / 子命令级别均识别） | | --version / -v | 打印当前包版本号 | | --log-level <DEBUG\|INFO\|WARN\|ERROR> | 日志级别（默认 INFO） | | --print-logs | 把日志同步输出到 stdout | | --debug | 启用调试模式（dev 模式日志） |

常用命令

# 添加技能
easbot-agent-skills add houjallen/agent-skills
easbot-agent-skills add https://github.com/houjallen/agent-skills -g

# 列出已安装
easbot-agent-skills list -p          # 仅项目级
easbot-agent-skills list -g          # 仅全局
easbot-agent-skills list --json      # JSON 输出

# 搜索（交互式）
easbot-agent-skills find typescript --owner houjallen

# 移除
easbot-agent-skills remove my-skill -y
easbot-agent-skills rm --agent claude-code my-skill

# 更新
easbot-agent-skills update -g
easbot-agent-skills update my-skill --all

# 一次性使用（不写锁定文件）
easbot-agent-skills use houjallen/agent-skills@eas-skill-creator

# store 视角运维
easbot-agent-skills store list [keyword]
easbot-agent-skills store clean --force
easbot-agent-skills store remove <sourceKey>

# 健康检查
easbot-agent-skills doctor
easbot-agent-skills dr -g -y

# 初始化新技能骨架
easbot-agent-skills init my-skill

与其他入口的关系

| 入口 | 用途 | | --- | --- | | easbot-agent-skills ... | 本仓库内置命令（host wrapper，运行时直接 import @easbot/skills） | | easbot-skills ... | @easbot/skills 包自带命令（独立 CLI，同样调 handleSkillsCli） | | easbot skills ... | @easbot/agent 主 CLI 通过 Commander.js 委派，等价于上面两个 |

三种入口等价；区别在于宿主（agent / agent-skills 包 / 本仓库 wrapper）不同，底层实现完全一致。

故障排查

• easbot-agent-skills: 未知命令: ... → 拼写错误或当前版本不支持该子命令；跑 easbot-agent-skills --help 看完整命令清单
• 命令卡在交互式多选 → 加 -y / --yes 跳过确认
• 需要看底层调用日志 → 加 --log-level DEBUG --print-logs

完整命令 / 参数见 easbot-agent-skills --help 输出。

目录结构

agent-skills/
├── README.md            # 中文说明
├── README.en.md         # English README
├── LICENSE              # MIT License
├── AGENTS.md            # Agent / 协作者约定
├── package.json         # 元信息包（依赖 @easbot/agent，声明 files）
├── scripts/             # 项目级维护脚本（见下表）
└── skills/
    ├── builtin/         # 内置核心技能
    │   ├── eas-agent-creation/      # 技能生命周期管理（创建/演化/废弃）
    │   ├── eas-agent-evolution/     # Agent 自我初始化与身份认知
    │   ├── eas-planning-writer/     # 计划与决策文档撰写
    │   ├── eas-prompt-creator/      # 各类 Prompt 模板的设计与生成
    │   ├── eas-research/             # 通用调研 / 分析 / 对比（v3.0.0 升级；原 eas-dev-research）
    │   ├── eas-skill-creator/       # 技能创建、构建与打包
    │   ├── eas-skill-find/          # 技能搜索与发现
    │   └── eas-skill-using/         # 技能生态中央导航
    ├── tools/           # 通用工具类技能
    │   ├── eas-chinese-writer/      # 中文写作与本地化辅助
    │   ├── eas-docx/                # Word 文档（CREATE / EDIT / ACCEPT-CHANGES）
    │   ├── eas-knowledge-using/     # 三大知识库（codebase / note / memory）CLI 引导
    │   ├── eas-pdf/                 # 设计驱动 PDF（CREATE / FILL / REFORMAT）
    │   ├── eas-pptx/                # PPT 演示（CREATE / EDIT / READ）
    │   └── eas-xlsx/                # Excel/电子表格（READ / CREATE / EDIT / FIX / VALIDATE）
    └── dev/             # 开发流程技能（独立分类，不进 eas-skill-using 索引）
        ├── eas-dev-align/           # 对齐 / 头脑风暴（Inversion）
        ├── eas-dev-spec/            # 规格化（Generator）
        ├── eas-dev-design/          # 架构设计（Pattern）
        ├── eas-dev-plan/            # 任务拆解（Generator）
        ├── eas-dev-tdd/             # TDD 实现（Technique）
        ├── eas-dev-implement/       # 实现驱动（Pipeline）
        ├── eas-dev-review/          # 代码评审（Reviewer）
        ├── eas-dev-diagnose/        # 诊断调试（Technique）
        ├── eas-dev-finish/          # 收尾发布（Technique）
        └── eas-dev-loop/            # 全流程编排（Pipeline；默认不加载）

项目维护脚本（根 scripts/）

仓库维护者本地或 CI 调用的工程级脚本，详见 AGENTS.md §5.1。

| 脚本 | 用途 | | --- | --- | | docs_add_frontmatter.ts | 为 docs/*.md 补 frontmatter | | docs_sync_automation.ts | 同步 docs 目录（生成索引、修正 name/category） | | generate-changelog.ts | 根据 git commits 生成 CHANGELOG | | bump-version.ts | 手动升级版本号并打 tag | | pre-commit-version.ts | pre-commit hook 用，默认禁用 | | generate-plugin.ts | 生成 .claude-plugin/marketplace.json | | generate-well-known.ts | 生成 .well-known/agent-skills/index.json（v1 协议，默认清空 + 重建），用于外部 Agent 按 well-known URL 发现 / 加载技能；可加 --validate 自动跑 schema 校验 | | docs/schemas/agent-skills/validate-v1.cjs | 校验 .well-known/agent-skills/index.json 是否符合 v1 schema（按需手动跑：npm run well-known:validate） | | publish.sh / publish.ps1 | 发布到 npm 前对全部技能跑一次 quick-validate 校验 |

内置技能一览（builtin）

| 技能 | 说明 | | --- | --- | | eas-agent-creation | EASBot 技能生命周期管理入口，覆盖技能从需求捕获、模式选择、创建、演化和废弃的全链路 | | eas-agent-evolution | Agent 自我初始化、身份认知建立、配置文件生成与持续进化 | | eas-planning-writer | 计划与决策文档的撰写（task_plan / progress / decisions / findings） | | eas-prompt-creator | Agent / Command / Context / Task / Feature / Mode 等 Prompt 的设计与生成 | | eas-research | 通用调研 / 分析 / 对比（商业 / 技术 / 学术 / 政策 / 趋势 / 竞品 / 根因）；调度 2 个子 reference（research-report / comparison-analysis） | | eas-skill-creator | 官方技能创建与构建工具，提供创建、结构化、验证、打包技能的完整指导 | | eas-skill-find | 在 EASBot 技能生态系统中查找、搜索与探索可用技能 | | eas-skill-using | 技能生态中央导航，给出"我应该用哪个技能"的判断与典型场景下的推荐组合 |

工具类技能（tools）

| 技能 | 说明 | | --- | --- | | eas-chinese-writer | 中文写作与本地化辅助，含 i18n / JSDoc / 术语指南 | | eas-docx | Word 文档（.docx）处理：CREATE（用 docx-js 从零生成）/ EDIT（XML unpack/edit/pack）/ ACCEPT-CHANGES（接受所有修订） | | eas-knowledge-using | 三大知识库（codebase / note / memory）的 CLI 操作引导；覆盖 init / doctor / status / sync / index / consolidate / reset 等 CLI-only op | | eas-pdf | 设计驱动的 PDF 处理：CREATE（从零生成成品）/ FILL（向既有 PDF 填表）/ REFORMAT（既有文档套设计） | | eas-pptx | PowerPoint 演示处理：CREATE（用 PptxGenJS 生成）/ EDIT（基于模板的 XML 编辑）/ READ（markitdown 抽取） | | eas-xlsx | Excel/电子表格处理：READ（分析）/ CREATE（XML 模板从零生成）/ EDIT（XML 直编）/ FIX（修公式）/ VALIDATE（公式校验） |

开发流程技能（dev）

独立分类：与 builtin / tools 并列，不进 eas-skill-using 索引；开发者按 description 自行匹配。 每个技能可独立执行，也可连贯组合跑完整开发闭环（align → spec → design → plan → tdd → implement → review → finish）。

| 技能 | 模式 | 用途 | | --- | --- | --- | | eas-dev-align | Inversion | 写代码 / spec 之前的 3 阶段访谈对齐（背景 / 范围 / 验收） | | eas-dev-spec | Generator | 把对齐笔记转为可执行 spec.md（5 章节 + 5 条校验规则） | | eas-dev-design | Pattern | 基于 spec 设计模块架构（Deep Modules 哲学 + 4 核心问题） | | eas-dev-plan | Generator | 把 spec/design 拆为 2-5 分钟颗粒度任务（7 字段模板） | | eas-dev-tdd | Technique | 强制红-绿-重构循环 + 测试反模式库 | | eas-dev-implement | Pipeline | 调度 plan → tdd → review 单任务级闭环 | | eas-dev-review | Reviewer | 两轴评审（标准 + spec）+ P0/P1/P2 分级 | | eas-dev-diagnose | Technique | 4 阶段根因分析（复现 / 定位 / 修复 / 回归） | | eas-dev-finish | Technique | 7 步收尾发布（test → review → docs → PR → merge → deploy → notify） | | eas-dev-loop | Pipeline（编排） | 一站式全流程编排；默认不加载（避免反 mattpocock "全流程托管" 警告） |

快速开始

每个技能都是独立可加载的单元。最简单的使用方式是让 Agent 在对话上下文中加载目标技能的 SKILL.md，并按照其中的"何时使用"和"快速参考"部分进行调用。

以中央导航为例：

1. 当你不确定该加载哪个技能时，加载 eas-skill-using/SKILL.md
2. 它会给出当前生态的能力索引与场景 → 技能映射
3. 按指引进一步加载具体技能（如 eas-skill-creator）执行任务

如果已经知道要用哪个技能（例如 eas-skill-creator），直接让 Agent 加载对应 SKILL.md 即可——不必走中央导航。

全仓技能结构校验

修改 / 新增技能后，跑一遍全量校验：

for s in skills/builtin/*/ skills/tools/*/ skills/dev/*/; do
  [ -f "$s/SKILL.md" ] && npx tsx skills/builtin/eas-skill-creator/scripts/quick-validate.ts "$s"
done

详见 AGENTS.md §5.2。

设计原则

• 职责单一：每个技能聚焦一类问题或一类能力
• 结构统一：所有技能遵循一致的 SKILL.md 规范
• 可组合：技能之间可串联、嵌套组合完成复杂任务
• 可演化：技能支持版本迭代与废弃流程

许可

本项目基于 MIT License 开源。

变更与贡献

• 版本变更与发布流程详见 CHANGELOG.md
• 仓库维护、提交约定、协作流程详见 AGENTS.md
• 新增 / 演化技能时务必先加载 eas-skill-using/SKILL.md 确认分类，再加载 eas-skill-creator/SKILL.md 按规约创建