readme

仓库: boshu2/agentops
安装量: 220
排名: #3960

安装

npx skills add https://github.com/boshu2/agentops --skill readme

/readme — Gold-Standard README Generation 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. Quick Start /readme

Interview + generate + validate (new README)

/readme --rewrite

Rewrite existing README with same patterns

/readme --validate

Council-validate an existing README without rewriting

The Patterns These are non-negotiable. Every README this skill produces follows them. 1. Lead with the problem, not the framework 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.) 2. Acknowledge prior art 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. 3. Show, don't claim 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. 4. State your differentiator once 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. 5. Trust block near install 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. 6. Collapse depth, don't delete it Detailed workflow steps, architecture deep-dives, theory, and reference material belong in

blocks. Skimmers get the fast path. Deep readers click to expand. Never delete depth to achieve brevity — collapse it. 7. Strip guru tone 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. 8. Section order serves adoption 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." Execution Steps Given /readme [--rewrite] [--validate] : Step 1: Pre-flight 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 rewrite README exists, no flags → ask: "Rewrite — regenerate with gold-standard patterns" "Validate — council-check the existing README" "Cancel" No README exists → proceed to Step 2 (generate from scratch) Step 2: Gather Context Read 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: Project name from manifest files Language/runtime from build files Existing description from README or PRODUCT.md License from LICENSE file Install method from manifest (npm, pip, brew, go install, cargo, etc.) Step 3: Interview Use AskUserQuestion for each section. Pre-populate suggestions from Step 2 where possible. Keep questions short. 3a: The Problem Ask: "What problem does this solve? One sentence — what pain does your user have?" Options (derived from existing README/PRODUCT.md if available): Suggested problem statement A punchier variant "Let me type my own" 3b: The Fix Ask: "How does it fix that problem? One sentence — what does your tool actually do?" 3c: Who Is It For Ask: "Who is this for? Name the runtime, framework, or role." Example: "Python developers using FastAPI" or "Anyone running Claude Code or Cursor" 3d: Install Ask: "What's the install command? (We'll put this front and center)" Options: Detected from manifest (e.g., npm install , pip install ) "Let me type my own" 3e: Quick Demo 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)" 3f: Trust Concerns Ask: "Does your tool do any of these? Check all that apply." Runs shell commands or hooks Modifies config files outside the project Makes network calls Creates files in the user's repo None of the above 3g: Prior Art (optional) Ask: "Are there similar tools? If so, how is yours different? (Be honest — readers who know the space will check)" Options: "Yes, let me describe" → follow up "Not really / I'll skip this" Step 4: Generate README 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} --- > [!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 — {phases, architecture, etc.} {Deep content here}

{Reference sections as needed}

FAQ

Contributing

License Generation rules: Every

block must have a blank line after (enables markdown rendering) Use markdown inside details blocks, not inline HTML ( , ,
) Trailing blank line before

No emoji unless the user's existing content uses them Flywheel/differentiator concept: state ONCE in "The Problem", demonstrate ONCE in "See It Work" Never use phrases: "What N months taught me", "This is what makes X different", "I come from X so I applied Y" Write the generated README to README.md . Step 5: Council Validation 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: "Fix — apply council recommendations automatically" "Show me — display findings, I'll decide" "Ship it — good enough" Step 6: Apply Fixes (if requested) Apply council-recommended fixes. Re-validate with --quick to confirm. Step 7: Report

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} Anti-Patterns to Detect 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 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 Examples Generating a README from scratch for a new project User says: /readme What happens: Pre-flight detects no existing README.md and proceeds to generate from scratch. The skill reads project context (manifest files, source directories, license) and runs a short interview asking about the problem, the fix, the audience, install command, quick demo, and trust concerns. A README is generated following all 8 gold-standard patterns (problem-first lead, trust block near install, collapsed depth, etc.) and validated by a quick council review. Result: A complete README.md written to disk that converts skimmers into users and serves deep readers, with a council verdict confirming quality. Validating an existing README without changes User says: /readme --validate What happens: Pre-flight confirms README.md exists and enters validate-only mode, skipping the interview and generation steps. A full council review (2 judges) evaluates the README against the 8 patterns and the anti-pattern detection table (flywheel echo, guru tone, buried trust info, etc.). Findings are presented with options to auto-fix, review manually, or ship as-is. Result: A detailed council report identifying specific anti-patterns and structural issues in the existing README, with actionable fix suggestions. Troubleshooting 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

blocks render as raw HTML on GitHub Missing blank line after tag or before

The skill enforces this formatting rule, but manual edits may break it. Ensure there is a blank line after every

...

line and before every

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 See Also 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 5

← 返回排行榜