repo-docs-boundary
Audit or maintain README, contributor setup, and durable repository docs placement while preserving the active repository policy.
- License 许可
- MIT
- 最近更新
- 2026-08-29
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- repo-docs-boundary
- description
- Audit or maintain README, contributor setup, and durable repository docs placement while preserving the active repository policy.
03 SKILL.md 正文
Repository Docs Boundary
Contract
Prereqs:
- Resolve the target git repository from the current working directory or an explicit path.
- Before writing, inspect the active repository policy and documentation
entrypoints:
AGENTS.md,CLAUDE.md,AGENT_DOCS.toml,README.md,DEVELOPMENT.md,CONTRIBUTING.md,docs/, package manifests, CI config, and project-owned validation scripts when present. - Activate and follow the repository's required docs intent before editing. A closer repository rule overrides this general placement guide.
Inputs:
- Mode:
auditinspects and recommends changes without writing.applymakes a narrow requested documentation change after inspection.new-repoproposes or creates minimal first-pass entrypoints.
- Optional repository path; default is the current working directory.
- User constraints such as audience, package type, install surface, maturity, validation command, or preferred language.
Outputs:
- In
auditmode, a concise section inventory withkeep,move,summarize+link,split,delete, orcreaterecommendations. - In
applyornew-repomode, narrowly edited root docs and only the supportingdocs/**files that need a durable owner, plus validation results. - Focused open questions when repository purpose, audience, install path, or contributor validation cannot be verified.
Failure modes:
- Repository purpose or workflow is too unclear to document concretely.
- Existing prose conflicts with live manifests, scripts, CI, or tests.
- A proposed edit would duplicate an authoritative rule in multiple places.
- Repository policy requires a different placement or validation path.
Entrypoint
Choose one mode before acting:
repo-docs-boundary audit [repo-path]
repo-docs-boundary apply [repo-path]
repo-docs-boundary new-repo [repo-path]
Default ambiguous or broad requests to audit. Treat a narrow explicit edit
as apply. Resolve the repository root, run its declared preflight, and inspect
the relevant definitions and call sites before changing documentation.
Source Priority
Use the strongest available source for each claim:
- User requirements for audience, positioning, and requested scope.
- Local manifests, package metadata, scripts, CI, hooks, docs catalogs, and tests.
- Existing documentation after checking it against live project files.
- Inference, labeled when it affects placement or wording.
For external, unstable, or version-sensitive facts, activate the repository's
task-tools intent and run agent-docs preflight --intent task-tools, then
follow core/policies/external-facts.md before asserting them.
Placement Rules
README.md
Keep README.md user-facing. It should quickly establish repository identity,
audience, value, install or run path, shortest useful example, major
capabilities, and links to contributor or detailed documentation.
Avoid full development setup, exhaustive validation matrices, agent or PR policy, long troubleshooting trees, internal design rationale, generated-file rules, and release ceremony unless ordinary users truly need them.
DEVELOPMENT.md
Keep DEVELOPMENT.md contributor-focused and short enough to read before a
normal edit. Retain the setup prerequisites, required preflight, exact build or
generation commands, finish-line validation, source-of-truth boundaries,
high-risk gotchas, and release or delivery boundaries needed for routine work.
Move rare runbooks, long rationale, complete troubleshooting trees, historical
background, and tool reference detail outward. Do not reduce
DEVELOPMENT.md to a link catalog: mandatory rules and exact everyday commands
remain inline.
docs/
Use the repository's existing docs area for durable architecture, operations, advanced configuration, troubleshooting, API or protocol reference, historical decisions that remain useful, and feature-specific guides. When no closer rule exists, prefer lowercase kebab-case filenames and avoid new root-level Markdown files.
Workflow
- Classify the request as
audit,apply, ornew-repo. - Resolve the repository root and inspect policy, root docs, docs indexes, manifests, build scripts, CI, and validation surfaces relevant to the claims.
- Inventory each meaningful section by current location, target audience, must-read-before-edit status, user-facing value, and long-form detail.
- Select one canonical owner for each rule or command. Keep short summaries in root entrypoints and link to long-form detail instead of duplicating it.
- For
audit, report evidence-backed placement findings and proposed actions without editing. - For
new-repo, draft the smallest completeREADME.mdandDEVELOPMENT.md; createdocs/files only when necessary to prevent root entrypoint bloat. - For
apply, edit narrowly and preserve the established tone, headings, language, and link style. Do not rewrite unrelated sections to fit a generic template. - Run the repository's declared docs or development validation. If none exists, check changed Markdown links and obvious stale references; report any skipped validation and why.
Review Checklist
- A non-contributor can understand and try the project from
README.md. - Contributors can find setup, preflight, source-of-truth, and validation gates
in
DEVELOPMENT.mdwithout reading a long runbook first. - Long-lived detail has one stable owner under
docs/or a narrower existing project area. - Root docs link to canonical detail without maintaining duplicate rules.
- Relative links resolve and claims agree with current project files.
- The result distinguishes verified facts, assumptions, and open questions.
Boundary
This skill owns documentation placement judgment, audits, and narrow docs edits. It does not own product strategy, package design, CI design, release automation, or repository policy changes beyond documenting the current source of truth. When the documentation review reveals a behavior gap, name and route the gap through the repository's implementation workflow instead of papering over it with prose.
04 同仓库更多 Skills
removable-skill
暂无简介
removable-skill
暂无简介
removable-project-skill
Fixture project-local skill used to prove remove-project-skill dry-run coverage.
project-sample-skill
Fixture project-local skill used to prove create-project-skill governance coverage.
project-local-skill
Fixture project-local skill used by runtime-kit project-local smoke checks.
topic-radar
Aggregate read-only AI and technology trend signals (Polymarket, Hacker News, GitHub, arXiv, Hugging Face, news search) into source-grounded Markdown or JSON; the lower-level data engine behind `daily-brief`.