npx skills add https://github.com/boshu2/agentops --skill readme目的: 生成一份能将浏览者转化为用户、并满足深度阅读者需求的 README — 然后通过评审委员会进行验证。
你必须执行此工作流。不要仅仅描述它。
/readme # 访谈 + 生成 + 验证(新建 README)
/readme --rewrite # 使用相同模式重写现有 README
/readme --validate # 仅通过委员会验证现有 README,不重写
这些是必须遵守的。本技能生成的每个 README 都遵循这些模式。
反面示例: "一个为智能体工作流实现'三种方式'的 DevOps 层。"
正面示例: "编码智能体在会话间会忘记一切。这个工具解决了这个问题。"
读者应该能用一句话理解你解决了什么痛点。不要用术语、框架名称或理论。问题本身才是钩子。(注意:像'三种方式'和'梅多斯'这样的框架引用可以作为设计原理放在正文中 — 只是不要以它们开头。)
如果你的方法类似于成熟实践(敏捷、SCRUM、规范驱动开发、CI/CD),请明确说明:
"如果你做过 X,你已经知道解决方法。新颖之处在于 Y。"
这能消除经验丰富的从业者的戒心,否则他们可能会认为你在重复造轮子。只声明真正新颖的部分。
反面示例: "这就是 X 的不同之处。系统具有复合效应。"
正面示例: 一段展示系统工作的终端会话记录。
没有证据的断言会引发敌意。具体示例 > 形容词。如果你不能在代码块中展示它,那它就不应该出现在 README 中。
一次清晰的解释。一次演示。这就是上限。在每个部分重复你的核心价值主张,会从强调变成营销文案。相信读者第一次就能理解。
广告位招租
在这里展示您的产品或服务
触达数万 AI 开发者,精准高效
在用户安装任何运行代码、挂钩或修改配置的东西之前,他们需要看到:
| 顾虑 | 解答 |
|---|---|
| 它会触及什么? | 创建/修改的文件,注册的挂钩 |
| 它会外传数据吗? | 遥测、网络调用、离开机器的数据 |
| 权限范围 | Shell 命令、配置更改、git 行为修改 |
| 可逆性 | 如何立即禁用,如何完全卸载 |
这应该放在安装命令附近,而不是隐藏在 FAQ 中。
详细的工作流步骤、架构深度解析、理论和参考资料应放在 <details> 块中。浏览者获得快速路径。深度阅读者点击展开。永远不要为了简洁而删除深度内容 — 折叠它。
不要用"我 N 个月学到了什么。" 不要用"我来自 X,所以我应用了 Y。" 不要用"这就是我们的不同之处。" 让工具自己说话。谦逊使人信服。居高临下令人反感。
问题 → 安装 → 看它工作 → 入门路径 → 工作原理(折叠) → 参考
理论和架构应在用户看过示例并知道如何开始之后出现。永远不要把"为什么这很重要"放在"如何尝试"之前。
给定 /readme [--rewrite] [--validate]:
ls README.md 2>/dev/null
模式检测:
--validate + README 存在 → 跳转到步骤 5(仅委员会验证)--rewrite + README 存在 → 读取现有内容,用作重写的上下文静默读取可用的项目文件(不向用户输出):
ls README.md PRODUCT.md package.json pyproject.toml go.mod Cargo.toml Makefile 2>/dev/null
ls -d src/ lib/ cmd/ app/ 2>/dev/null
ls -d docs/ 2>/dev/null
ls LICENSE CHANGELOG.md 2>/dev/null
提取:
为每个部分使用 AskUserQuestion。尽可能从步骤 2 预填充建议。保持问题简短。
询问:"这解决了什么问题?一句话 — 你的用户有什么痛点?"
选项(如果现有 README/PRODUCT.md 可用,则从中派生):
询问:"它如何解决那个问题?一句话 — 你的工具实际上做了什么?"
询问:"这是给谁用的?指明运行时、框架或角色。"
示例:"使用 FastAPI 的 Python 开发者" 或 "任何运行 Claude Code 或 Cursor 的人"
询问:"安装命令是什么?(我们会把它放在显眼位置)"
选项:
npm install <pkg>、pip install <pkg>)询问:"用户在安装后可以做的最简单的事情是什么,以看到它工作?(一个命令、一个代码片段或一个终端会话)"
询问:"你的工具会做以下任何事吗?选择所有适用的。"
询问:"有类似的工具吗?如果有,你的工具有何不同?(诚实点 — 了解这个领域的读者会去查)"
选项:
使用访谈回答和上述 8 个模式,生成具有以下结构的 README:
<div align="center">
# {项目名称}
### {问题陈述 — 一行}
{徽章}
{导航链接}
</div>
---
> [!IMPORTANT]
> {信任声明块 — 仅限本地、触及内容、如何禁用、如何卸载}
> (如果 3f 没有信任顾虑,则跳过)
{安装命令}
---
## 问题
{2-3 句话扩展问题。如果适用,承认现有成果。
陈述你的方法真正新颖之处 — 仅一次。}
---
## 看它工作
{来自 3e 的终端会话记录或代码示例。展示,不要描述。}
---
## 安装
{完整的安装细节,替代方法放在 <details> 块中。
如果存在信任顾虑,包含"触及内容"表格。}
---
## 入门指南
{采用路径 — 第 1 天,第 1 周等。或者只是"运行 X,然后 Y。"}
---
## 工作原理
{一段总结 + 如果适用,包含图表。}
<details>
<summary><b>详情</b> — {阶段、架构等}</summary>
{深度内容放在这里}
</details>
---
## {根据需要添加参考章节}
{技能、API、CLI 等 — 在适当处折叠}
---
## 常见问题
{前 3 个问题内联,如果存在完整 FAQ 则链接}
---
## 贡献指南
## 许可证
生成规则:
<details> 块必须在 <summary> 后有一个空行(启用 markdown 渲染)<code>、<a href>、<br>)</details> 前有尾随空行将生成的 README 写入 README.md。
运行委员会来验证 README:
Skill(skill="council", args="--quick validate README.md — is it clear, non-repetitive, and does it serve both skimmers and deep readers?")
如果是 --rewrite 或从头生成: 使用 --quick(内联,快速)。
如果是对现有 README 使用 --validate: 使用默认委员会(2 名评审员)进行彻底审查。
向用户展示委员会发现的问题。如果发现重大问题,提供选项:
应用委员会建议的修复。使用 --quick 重新验证以确认。
## README 完成
**文件:** README.md
**章节数:** {数量}
**应用的模式:** {列出相关的 8 个模式}
**委员会裁决:** {通过/警告/失败}
{如果是警告/失败:列出主要发现以及是否已修复}
在重写或验证时,标记这些:
| 反模式 | 检测方法 | 修复方法 |
|---|---|---|
| 飞轮回声 | 核心价值主张陈述 3 次以上 | 陈述一次,演示一次 |
| 框架先行 | 以方法论名称开头,而非问题 | 将开头重写为问题陈述 |
| 导师口吻 | "我学到了什么"、"这就是 X 的不同之处" | 剔除,让工具自己说话 |
| 定义前使用术语 | 在解释之前使用领域术语 | 首次使用时定义或使用通俗语言 |
| 隐藏的信任信息 | 安全/权限信息在首屏以下 | 移到安装步骤附近 |
| 无可见卸载说明 | 10 秒内找不到卸载方法 | 在安装块附近添加 |
| 安装说明分散 | 相同的安装命令出现在 3 个以上位置 | 一个主要的安装命令,一个规范的参考位置 |
| 理论先于尝试 | 在示例之前介绍架构/哲学 | 重新排序:示例优先,理论放在详情中 |
| 无证据的宣称 | "最好"、"不同"、"独特"但没有演示 | 替换为具体示例或删除 |
用户说: /readme
会发生什么:
结果: 一个完整的 README.md 写入磁盘,能将浏览者转化为用户并服务于深度阅读者,并有委员会裁决确认质量。
用户说: /readme --validate
会发生什么:
结果: 一份详细的委员会报告,指出现有 README 中具体的反模式和结构性问题,并提供可操作的修复建议。
| 问题 | 原因 | 解决方案 |
|---|---|---|
| 委员会验证步骤失败或挂起 | /council 技能依赖未安装或损坏 | 运行 /update 重新安装所有技能,然后重试。验证 /council 能独立工作 |
| 生成的 README 没有信任声明块 | 访谈期间没有选择信任顾虑(步骤 3f 回答了"以上都不是") | 如果你的工具确实运行挂钩、修改配置或进行网络调用,请重新运行 /readme --rewrite 并选择适用的信任顾虑 |
<details> 块在 GitHub 上渲染为原始 HTML | <summary> 标签后或 </details> 前缺少空行 | 该技能强制执行此格式规则,但手动编辑可能会破坏它。确保每个 <summary>...</summary> 行后和每个 </details> 前都有一个空行 |
| 访谈不断询问项目清单已经回答的问题 | 上下文收集步骤无法识别清单文件格式 | 确保你的项目在仓库根目录有一个标准清单(package.json、go.mod、pyproject.toml、Cargo.toml) |
| 反模式检测在重写时误报 | 某些内容模式即使是有意为之也会触发启发式检测 | 在委员会步骤中审查每个发现,对于有意选择的内容选择"发布"。检测是启发式的,并非绝对 |
skills/product/SKILL.md — PRODUCT.md 生成(为 README 上下文提供信息)skills/doc/SKILL.md — 代码文档(范围不同 — API 文档,非 README)skills/council/SKILL.md — 步骤 5 中使用的验证引擎每周安装量
175
代码仓库
GitHub 星标数
198
首次出现
2026年2月17日
安全审计
安装于
opencode173
github-copilot169
codex169
kimi-cli169
gemini-cli169
amp169
Purpose: Generate a README that converts skimmers into users and satisfies deep readers — then validate it with a council.
YOU MUST EXECUTE THIS WORKFLOW. Do not just describe it.
/readme # Interview + generate + validate (new README)
/readme --rewrite # Rewrite existing README with same patterns
/readme --validate # Council-validate an existing README without rewriting
These are non-negotiable. Every README this skill produces follows them.
Bad: "A DevOps layer implementing the Three Ways for agent workflows." Good: "Coding agents forget everything between sessions. This fixes that."
The reader should understand what pain you solve in one sentence. No jargon, no framework names, no theory. The problem is the hook. (Note: framework references like Three Ways and Meadows belong in the body as design rationale — just don't lead with them.)
If your approach resembles established practices (agile, SCRUM, spec-driven development, CI/CD), say so explicitly:
"If you've done X, you already know the fix. What's new is Y."
This disarms experienced practitioners who would otherwise dismiss you as reinventing the wheel. Claim only what's genuinely novel.
Bad: "This is what makes X different. The system compounds." Good: A terminal transcript showing the system working.
Assertions without evidence trigger hostility. Concrete examples > adjectives. If you can't show it in a code block, it's not ready for the README.
One clear explanation. One demonstration. That's the max. Repeating your core value proposition in every section crosses from reinforcement into marketing copy. Trust the reader to absorb it the first time.
Before a user installs anything that runs code, hooks, or modifies config, they need to see:
| Concern | Answer it |
|---|---|
| What does it touch? | Files created/modified, hooks registered |
| Does it exfiltrate? | Telemetry, network calls, data leaving the machine |
| Permission surface | Shell commands, config changes, git behavior modifications |
| Reversibility | How to disable instantly, how to uninstall completely |
This goes near the install command, not buried in an FAQ.
Detailed workflow steps, architecture deep-dives, theory, and reference material belong in <details> blocks. Skimmers get the fast path. Deep readers click to expand. Never delete depth to achieve brevity — collapse it.
No "What N months taught me." No "I come from X, so I applied Y." No "This is what makes us different." Let the tool speak for itself. Humility disarms. Condescension repels.
Problem → Install → See It Work → Getting Started Path → How It Works (collapsed) → Reference
Theory and architecture come AFTER the user has seen examples and knows how to start. Never put "why this is important" before "how to try it."
Given /readme [--rewrite] [--validate]:
ls README.md 2>/dev/null
Mode detection:
--validate + README exists → skip to Step 5 (council validation only)--rewrite + README exists → read existing, use as context for rewriteRead available project files silently (no output to user):
ls README.md PRODUCT.md package.json pyproject.toml go.mod Cargo.toml Makefile 2>/dev/null
ls -d src/ lib/ cmd/ app/ 2>/dev/null
ls -d docs/ 2>/dev/null
ls LICENSE CHANGELOG.md 2>/dev/null
Extract:
Use AskUserQuestion for each section. Pre-populate suggestions from Step 2 where possible. Keep questions short.
Ask: "What problem does this solve? One sentence — what pain does your user have?"
Options (derived from existing README/PRODUCT.md if available):
Ask: "How does it fix that problem? One sentence — what does your tool actually do?"
Ask: "Who is this for? Name the runtime, framework, or role."
Example: "Python developers using FastAPI" or "Anyone running Claude Code or Cursor"
Ask: "What's the install command? (We'll put this front and center)"
Options:
npm install <pkg>, pip install <pkg>)Ask: "What's the simplest thing a user can do after installing to see it work? (A command, a code snippet, or a terminal session)"
Ask: "Does your tool do any of these? Check all that apply."
Ask: "Are there similar tools? If so, how is yours different? (Be honest — readers who know the space will check)"
Options:
Using the interview responses and the 8 patterns above, generate the README with this structure:
<div align="center">
# {Project Name}
### {Problem statement — one line}
{Badges}
{Nav links}
</div>
---
> [!IMPORTANT]
> {Trust block — local-only, what it touches, how to disable, how to uninstall}
> (Skip if no trust concerns from 3f)
{Install command}
---
## The Problem
{2-3 sentences expanding the problem. Acknowledge prior art if applicable.
State what's genuinely new about your approach — once.}
---
## See It Work
{Terminal transcript or code example from 3e. Show, don't describe.}
---
## Install
{Full install details, alternative methods in <details> blocks.
"What it touches" table if trust concerns exist.}
---
## Getting Started
{Adoption path — Day 1, Week 1, etc. Or just "Run X, then Y."}
---
## How It Works
{One paragraph summary + diagram if applicable.}
<details>
<summary><b>Details</b> — {phases, architecture, etc.}</summary>
{Deep content here}
</details>
---
## {Reference sections as needed}
{Skills, API, CLI, etc. — collapsed where appropriate}
---
## FAQ
{Top 3 questions inline, link to full FAQ if it exists}
---
## Contributing
## License
Generation rules:
<details> block must have a blank line after <summary> (enables markdown rendering)<code>, <a href>, <br>)</details>Write the generated README to README.md.
Run a council to validate the README:
Skill(skill="council", args="--quick validate README.md — is it clear, non-repetitive, and does it serve both skimmers and deep readers?")
If--rewrite or generating from scratch: Use --quick (inline, fast).
If--validate on existing README: Use default council (2 judges) for thorough review.
Present the council findings to the user. If significant issues found, offer:
Apply council-recommended fixes. Re-validate with --quick to confirm.
## README Complete
**File:** README.md
**Sections:** {count}
**Patterns applied:** {list which of the 8 patterns were relevant}
**Council verdict:** {PASS/WARN/FAIL}
{If WARN/FAIL: list the top findings and whether they were fixed}
When rewriting or validating, flag these:
| Anti-Pattern | Detection | Fix |
|---|---|---|
| Flywheel echo | Core value prop stated 3+ times | State once, demonstrate once |
| Framework-first | Opens with methodology name, not problem | Rewrite lead as problem statement |
| Guru tone | "What I learned", "This is what makes X different" | Strip, let the tool speak |
| Jargon before definition | Domain terms used before they're explained | Define on first use or use plain language |
| Buried trust info | Security/permissions info below the fold | Move near install |
| No visible uninstall | Uninstall not findable within 10 seconds | Add near install block |
| Install scatter | Same install command in 3+ locations | One hero install, one canonical reference |
User says: /readme
What happens:
Result: A complete README.md written to disk that converts skimmers into users and serves deep readers, with a council verdict confirming quality.
User says: /readme --validate
What happens:
Result: A detailed council report identifying specific anti-patterns and structural issues in the existing README, with actionable fix suggestions.
| Problem | Cause | Solution |
|---|---|---|
| Council validation step fails or hangs | The /council skill dependency is not installed or is broken | Run /update to reinstall all skills, then retry. Verify /council works independently |
| Generated README has no trust block | No trust concerns were selected during the interview (step 3f answered "None of the above") | If your tool does run hooks, modify config, or make network calls, re-run /readme --rewrite and select the applicable trust concerns |
<details> blocks render as raw HTML on GitHub | Missing blank line after <summary> tag or before |
skills/product/SKILL.md — PRODUCT.md generation (feeds into README context)skills/doc/SKILL.md — Code documentation (different scope — API docs, not README)skills/council/SKILL.md — Validation engine used in Step 5Weekly Installs
175
Repository
GitHub Stars
198
First Seen
Feb 17, 2026
Security Audits
Gen Agent Trust HubPassSocketPassSnykPass
Installed on
opencode173
github-copilot169
codex169
kimi-cli169
gemini-cli169
amp169
通过 LiteLLM 代理让 Claude Code 对接 GitHub Copilot 运行 | 高级变通方案指南
22,200 周安装
OKX DEX 战壕技能:7个命令实现迷因代币发现、开发者分析与同车追踪
1,500 周安装
OKX DEX 信号与排行榜 - 追踪聪明钱、KOL、巨鲸交易信号
1,500 周安装
OKX CEX 市场数据 CLI - 免费获取实时价格、K线、订单簿、技术指标
1,500 周安装
安全审查员 | 代码安全审计、漏洞扫描与渗透测试工具 | DevSecOps 自动化
1,400 周安装
Home Assistant 最佳实践指南:原生自动化配置与反模式规避
1,400 周安装
TikTok自动化工具:通过Rube MCP与Composio实现视频上传、发布与账号管理
254 周安装
| Theory before try | Architecture/philosophy before examples | Reorder: examples first, theory in details |
| Claim without evidence | "Best", "different", "unique" without demo | Replace with concrete example or remove |
</details>The skill enforces this formatting rule, but manual edits may break it. Ensure there is a blank line after every <summary>...</summary> line and before every </details> |
| Interview keeps asking questions the project manifest already answers | The manifest file format is not recognized by the context-gathering step | Ensure your project has a standard manifest (package.json, go.mod, pyproject.toml, Cargo.toml) in the repo root |
| Anti-pattern detection flags false positives on rewrite | Some content patterns trigger heuristic detection even when intentional | Review each finding during the council step and select "Ship it" for intentional choices. The detection is heuristic, not absolute |