菜单
Use when an existing SKILL.md has review-best-practice-skill findings to address, a citation has become inaccurate, steps reference an outdated tool, or scope needs adjusting — splitting a skill that covers two concepts, or expanding one that is too shallow.
默认使用会先检查来源的 Prompt；你也可以切换为直接命令，或下载本地副本。
决定是否安装前，请先阅读 SKILL.md，以及 SkillsMP 当前展示的配套文件。
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
直接命令不会经过审查 Prompt；运行前请先检查来源。
npx skills add https://github.com/jeffreytse/grimoire-core --skill revise-best-practice-skill命令会保持在同一行。复制前请横向滚动并检查完整内容。
想先保存到本地？可下载 SkillsMP 当前能够提供的文件。
Use when comparing very differently-titled roles for compensation banding, leveling, or organizational design — score each role's inherent Know-How (knowledge, skills, experience required), Problem Solving (complexity and freedom of thinking, scored as a percentage of Know-How), and Accountability (freedom to act and magnitude of impact), because job titles and informal seniority perceptions vary inconsistently across departments and don't provide a comparable basis on their own.
Use when many people request your scarce time, mentorship, or expertise and you cannot evaluate their genuine commitment level from a conversation alone — require a specific, costly, objectively verifiable unit of self-directed output (a set number of completed attempts) before engaging, because genuine commitment is what a conversation cannot reliably reveal but a completed, verifiable body of work can.
Use when deciding how to allocate a manager's or leader's limited time across competing activities — before defaulting to whatever is most urgent, estimate each candidate activity's leverage (how many people's output it affects, for how long, and whether it requires your specific position), because a manager's actual output is the output of the organization under their influence, not their own individual task completion.
基于 SOC 职业分类
正在显示 SKILL.md
| name | revise-best-practice-skill |
| description | Use when an existing SKILL.md has review-best-practice-skill findings to address, a citation has become inaccurate, steps reference an outdated tool, or scope needs adjusting — splitting a skill that covers two concepts, or expanding one that is too shallow. |
| source | IETF RFC errata process (BCP 9), MDN Web Docs contribution guidelines, Wikipedia article improvement process |
| tags | ["skill-revision","quality-debt","targeted-fix","contributor","maintainer","review-pass"] |
Update an existing grimoire SKILL.md to resolve specific findings without touching validated content.
Adopted by: Targeted revision of specific findings is the standard maintenance model across all long-lived technical documentation systems — IETF errata correct specific claims in RFCs without replacing the full document, MDN Web Docs uses targeted pull requests per section rather than full-article rewrites, and Wikipedia's peer review process improves articles through iterative section-level fixes rather than wholesale replacement. Impact: Targeted revision preserves validated content while addressing gaps — wholesale rewrite discards working sections and resets review history unnecessarily. Aghajani et al. (2019, MSR) found that the vast majority of documentation fixes in OSS projects are targeted single-section changes; wholesale rewrites are rare and reserved for fundamental practice changes. The IETF errata model demonstrates that long-lived technical documents can remain accurate for decades through targeted correction while full replacements introduce regression risk across all sections. Why best: Fixing only flagged findings — vs. refactoring the whole file "while you're there" — prevents introducing new issues in sections that were already PASS. A full rewrite is the alternative; it costs more, discards verified content, and risks new failures in sections that passed.
Sources: IETF RFC errata process (BCP 9), MDN Web Docs contribution guidelines, Wikipedia article improvement process, Aghajani et al. 2019 (MSR documentation debt)
Get the finding set:
review-best-practice-skill on the file first; use its output| Finding type | Scope of fix |
|---|---|
| Frontmatter field (name, description, source, tags) | Frontmatter only — don't touch body |
| "Adopted by" inaccurate or vague | ## Why This Is Best Practice only |
| "Impact" citation weak or fabricated | ## Why This Is Best Practice only |
| Steps reference outdated tool or API | Affected step(s) only |
| Steps not actionable or too abstract | Affected step(s) only |
| Scope too broad (two separable concepts) | Split — see step 4 |
| Scope too shallow (<50 lines) | Expand Steps with concrete examples |
| Domain safety footer missing | Add footer only |
Structural before content: Always apply structural revisions before content revisions.
Structural changes invalidate content — if you improve wording in a step that will be removed, the content work is wasted. Structure is the skeleton; content is the flesh.
Fix the flagged item. Don't touch adjacent text that wasn't flagged.
If the finding involves a citation, adoption claim, or a tool/API's current status, search the internet to confirm the corrected information is accurate before writing it in — don't replace one unverified claim with another. If no internet-access tool is available in this environment, say so explicitly and proceed on best available knowledge — flag the fix as unverified rather than silently skipping the check or asserting it was confirmed. After searching, state what was found (or that nothing conclusive turned up) before proceeding — don't just announce the check and discard the result.
❌ Citation wrong → rewrite entire Why section
✅ Citation wrong → replace the one sentence containing the citation
❌ One step vague → rewrite all steps for consistency
✅ One step vague → rewrite that step only
If fixing a citation requires changing the surrounding sentence for grammatical coherence, that is acceptable. Touching unrelated paragraphs is not.
If the finding is "skill covers two separable concepts":
write-best-practice-skill to author the extracted skill from scratch — do not copy the removed content verbatim; the extracted skill needs its own Why section, sources, and stepsreview-best-practice-skill on both resulting skillsThis is a scope reduction, not a deprecation. Do not add a deprecation notice to the concept A skill.
After all fixes are applied, run review-best-practice-skill on the updated file:
PR title: fix(<domain>/<skill-name>): <one-line description of what changed>
PR description: one line per finding, stating what it was and how it was resolved.
PR template: When submitting a skill revision as a PR, title format: fix(skills): [what was fixed] in [skill-name]. Body must include:
review-best-practice-skill after revision — don't assume the fix resolved the findingdeprecate-best-practice-skill insteadRewriting the whole skill for one citation: fix the citation sentence; leave everything else.
"Improving" unflagged sections: if review-best-practice-skill didn't flag it, don't touch it — even if you'd write it differently.
Skipping re-verification: a fix can introduce a new failure. Always re-run review-best-practice-skill after editing.
Treating scope reduction as deprecation: splitting a skill that was too broad is a fix. Both resulting skills live on — neither is retired.