القائمة
Generate and validate repo docs, READMEs
يُحدَّد Prompt الذي يراجع المصدر أولًا بشكل افتراضي. يمكنك التبديل إلى أمر مباشر أو تنزيل نسخة محلية.
اقرأ SKILL.md وأي ملفات مرافقة يعرضها SkillsMP قبل أن تقرر التثبيت.
التثبيت باستخدام Codex أو Claude انسخ هذا Prompt والصقه في Codex أو Claude أو مساعد آخر ليراجع صفحة Skill ويثبّتها لك.
يتجاوز الأمر المباشر Prompt المخصّص للمراجعة. افحص المصدر قبل تشغيله.
npx skills add https://github.com/boshu2/agentops --skill docيبقى الأمر في سطر واحد. مرّر أفقيًا لمراجعته كاملًا قبل النسخ.
تفضّل نسخة محلية؟ نزّل الملفات المتاحة حاليًا لدى SkillsMP.
Use Agent Mail as an optional messaging and file-reservation adapter for explicitly coordinated writers. Triggers: "coordinate writers", "reserve files".
Operate explicit orchestrator, implementer, validator, and scribe roles through a caller-selected agent runtime. Triggers: "agent-native factory", "role-shaped agent panes", "persistent workers".
Initialize minimal AgentOps documentation and verdict storage without taking over repository workflow. Triggers: "bootstrap AgentOps", "initialize AgentOps docs".
عرض SKILL.md
| name | doc |
| description | Generate and validate repo docs, READMEs |
YOU MUST EXECUTE THIS WORKFLOW. Do not just describe it.
Generate and validate documentation for any project. --mode selects the artifact family — the default mode handles code/API docs and code-maps; --mode=readme generates a gold-standard README; --mode=oss scaffolds and audits the open-source doc pack.
docs/contracts/ubiquitous-language.md: the operations layer for agentic engineering) and preserves the ownership boundary; never describe AgentOps as an execution orchestrator, factory, corpus, or loop.refresh as a separate opt-in path and confirm its target writes with the user before proceeding.--mode | Artifact | Read first |
|---|---|---|
| (default) | API docs, code-maps, doc coverage/validate | this file |
readme |
| Gold-standard README (interview → generate → de-slop → deterministic checks) |
| references/readme-craft.md |
oss | OSS doc pack (CONTRIBUTING/CHANGELOG/AGENTS.md, audit + scaffold) | references/oss-pack.md |
Same skill, different shapes. Prefer modes and references over a pile of one-off doc skills. README generate/rewrite always runs the de-slopify docs-prose pass before checks.
Mode routing (absorbed skills):
| You typed | Runs |
|---|---|
| "readme", "rewrite the README", "validate the README" | Doc in readme mode |
| "oss docs", "scaffold contributing", "audit OSS docs" | Doc in oss mode |
When invoked with --mode=readme or --mode=oss, read the corresponding reference above and follow its workflow verbatim. The default-mode steps below apply only when no mode (or the implied code-docs mode) is selected.
Default mode is deliberately thin. Given a Doc command and target:
ls package.json pyproject.toml go.mod Cargo.toml + existing docs/; classify CODING / INFORMATIONAL / OPS.discover (grep undocumented funcs), coverage (documented vs total), gen [feature] (read code → stamp function/class markdown), all, or validate..agents/scratch/doc/YYYY-MM-DD-<target>.md (coverage %, generated, gaps, validation issues), then report coverage + gaps to the user.Full step-by-step detail — grep recipes, function/class + code-map templates, the report skeleton, key rules, worked examples, and the troubleshooting table — lives in references/default-mode.md (moved there in the generic-craft trim). Read it when you need the exact shapes; otherwise just do the three steps.
Bounded-chunk research with a coverage ledger. Before writing about a
surface larger than a handful of files, enumerate the chunks to read (modules,
commands, config surfaces) as a ledger in the report, then research one
bounded chunk at a time, marking each read, skimmed, or skipped with a
reason. The document may only make claims about read chunks; skimmed and
skipped chunks appear in the report as disclosed gaps. Writing from an
unledgered wander through the codebase is the ambient research failure
mode: coverage becomes whatever the walk happened to touch, and nobody —
including you — can say what the doc silently omits. Stop condition: the
ledger has no unmarked chunks before the doc is reported complete.
Conceptual-surprise floor. A doc that surprises no one taught nothing. Before reporting completion, name at least one thing in the document that a reader who already skimmed the code would not have known — a non-obvious invariant, an ordering constraint, a why behind a structure, a trap. If no such item exists, the doc is restating the code's surface; either dig for the missing concept or report the doc as reference-only coverage, not teaching material. Prose that renarrates signatures and file names is the mirror doc failure mode — accurate, complete, and useless.
.agents/scratch/doc/; README mode updates the repository README.md; OSS scaffold mode creates missing root documentation only by default. The separate OSS refresh path may update an existing doc only after explicit user confirmation.YYYY-MM-DD-<target>.md; README and OSS filenames follow their mode references.bash skills/doc/scripts/validate.sh, then run the mode-specific validation required by its reference before reporting completion.references/default-mode.md — default mode (code/API docs): the full Steps 1-7 detail — grep recipes, function/class + code-map templates, report skeleton, worked examples, troubleshooting (moved out of SKILL.md in the generic-craft trim)
references/doc.feature — Executable spec: detect project type, generate type-appropriate docs from the repo, validate existing docs against source (soc-qk4b)
references/readme.feature — Executable spec (--mode=readme): mode detection, problem-first lead, trust block near install, collapse-don't-delete depth, evidence reporting, and anti-pattern detection
references/oss-docs.feature — Executable spec (--mode=oss): audit existing/missing OSS docs, scaffold missing without overwrite, project-type-tailored (soc-qk4b)
references/readme-craft.md — --mode=readme: the 8 gold-standard README patterns, interview, generation structure, deterministic checks, and anti-pattern table
references/oss-pack.md — --mode=oss: audit + scaffold the OSS doc pack (CONTRIBUTING/CHANGELOG/AGENTS.md), project-type templates
references/oss-documentation-tiers.md — OSS doc tier definitions (core/standard/enhanced)
references/oss-project-types.md — Per-type OSS scaffolding templates (cli/operator/service/library/helm)
references/de-slopify.md — Docs prose pass (required in README mode)
references/architecture-report.md — Generate technical architecture documents
references/default-mode.md.readme mode creates or revises the repository README.oss mode creates the explicitly requested open-source documentation pack.| Problem | Fix |
|---|---|
| Default mode feels heavyweight | Read references/default-mode.md — or just ask the model directly for simple docs |
| README evidence has gaps | Report the concrete gaps; the caller decides whether to start a revision |