diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index 0f0bbe83d..b9e2b4e0c 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -125,4 +125,8 @@ Use these repo-local skills for recurring SD.Next model integration work: File: `.github/skills/todo/SKILL.md` Use when searching the full codebase for `TODO` markers and producing a markdown document with proposed next steps for each item. +- `update-docs` + File: `.github/skills/update-docs/SKILL.md` + Use when reading markdown files from `wiki/` to correct markdown syntax, improve readability, and optionally normalize structure, links, and terminology while preserving technical meaning. + When creating and updating skills, update this file and the index in `.github/skills/README.md` accordingly. diff --git a/.github/skills/README.md b/.github/skills/README.md index d41712ee2..a1f4a3c70 100644 --- a/.github/skills/README.md +++ b/.github/skills/README.md @@ -60,6 +60,10 @@ This folder contains repo-local Copilot skills for recurring SD.Next tasks. File: `todo/SKILL.md` Use when scanning the full codebase for `TODO` markers and producing a markdown document with proposed next steps for each item. +- `update-docs` + File: `update-docs/SKILL.md` + Use when reading markdown files from `wiki/` to correct markdown syntax, improve readability, and optionally normalize structure/links while preserving technical meaning. + ## Notes - Keep skills narrowly task-oriented and reusable. diff --git a/.github/skills/update-docs/SKILL.md b/.github/skills/update-docs/SKILL.md new file mode 100644 index 000000000..be45a9694 --- /dev/null +++ b/.github/skills/update-docs/SKILL.md @@ -0,0 +1,163 @@ +--- +name: update-docs +description: "Update wiki markdown docs for syntax correctness, readability, link integrity, heading hierarchy normalization, and code block language tagging. Use when a user asks to clean up markdown formatting and improve clarity while preserving technical meaning." +argument-hint: "Provide one or more wiki/*.md paths and optional scope (syntax-only, readability, or full pass)" +--- + +# Update Wiki Docs + +Read markdown files in the `wiki/` folder, fix markdown syntax issues, and improve readability without changing technical intent. + +## When To Use + +- The user asks to clean, polish, or normalize markdown docs in `wiki/` +- Headings/lists/code fences/tables render incorrectly +- Documentation is hard to scan due to long paragraphs or inconsistent structure +- A doc needs editorial cleanup before sharing or release + +## Scope + +Primary scope: + +- Files under `wiki/**/*.md` + +Baseline actions: + +- Correct markdown syntax +- Correct general readability issues +- Run link integrity pass for obvious broken links and anchors +- Normalize heading hierarchy and section flow +- Add or correct code block language tags when known + +Expanded actions (when user allows full pass): + +- Improve list/table/code-block consistency +- Standardize terminology and naming across the document +- Flag stale or unverifiable claims for follow-up + +## Style Rules + +- Write in concise technical style that remains approachable to non-expert users +- Prefer short to medium sentences; avoid unnecessary long sentences +- Explain terms briefly when first used if they may be unfamiliar +- Avoid unexplained jargon and acronym-heavy phrasing +- Keep wording direct, specific, and neutral + +## Safety Rules + +- Preserve technical meaning and factual content +- Do not invent commands, API behavior, or version claims +- Keep edits narrow and reversible +- Preserve existing project-specific terminology unless clearly inconsistent +- If uncertainty is high, prefer adding a short clarification request over guessing + +## Procedure + +### 1. Confirm Target And Depth + +Extract from user prompt: + +- target markdown file(s) in `wiki/` +- desired depth: syntax-only, readability, or full pass +- constraints (tone, audience, preserve wording, max rewrite level) + +If targets are missing, ask for paths before editing. + +### 2. Read And Diagnose + +For each target file: + +- Scan for syntax/rendering issues +- Identify readability pain points (dense blocks, weak headings, mixed terminology) +- Note risky sections where edits may alter meaning + +### 3. Normalize Heading Hierarchy + +Apply heading structure rules before deep rewrites: + +- keep one logical top-level heading per file where appropriate +- avoid skipped levels (`##` directly to `####`) unless source constraints require it +- ensure sibling sections use consistent levels +- rename headings only when it improves clarity without changing meaning + +### 4. Apply Syntax Fixes First + +Fix rendering/correctness issues first, such as: + +- broken heading levels +- malformed lists +- unclosed/misfenced code blocks +- malformed links/images +- inconsistent table delimiter rows +- accidental HTML/markdown mixing that breaks rendering + +### 5. Apply Readability Improvements + +Make editorial improvements while preserving meaning: + +- split long paragraphs +- convert prose enumerations into lists when clearer +- improve section titles for scanability +- remove repetition and tighten wording +- align terminology within the same document + +Apply tone constraints during edits: + +- concise technical phrasing +- approachable wording for normal users +- no unexplained technical babble + +### 6. Run Link Integrity Pass + +Check and fix obvious link issues: + +- malformed inline/reference links +- anchors that no longer match heading text after edits +- obvious relative-path mistakes in wiki cross-links + +If link targets cannot be verified from repo context, keep the original target and flag it in the report. + +### 7. Add Code Block Language Tags + +For fenced code blocks: + +- add language tags when confidently inferable (`bash`, `python`, `json`, `yaml`, etc.) +- correct clearly wrong tags +- leave tag blank only when language cannot be inferred safely + +### 8. Run Completion Checks + +Validate each edited file against this checklist: + +- markdown renders correctly +- heading hierarchy is logical +- code fences include language where known +- links/anchors are internally consistent and obviously valid +- no factual changes introduced +- tone is concise, technical, and approachable + +### 9. Report Results + +Return: + +- files edited +- categories of changes made (syntax/readability/structure) +- any unresolved ambiguity or potential factual follow-ups + +## Branching Guidance + +- If the user asks minimal edits, still run heading normalization, link integrity checks, and code-block language tagging with minimal wording changes. +- If the user asks broad cleanup, run full pass including structure and terminology normalization. +- If a section appears technically outdated but cannot be verified from repo context, do not rewrite claims; flag it in the report. + +## Pass Criteria + +A successful pass means: + +- requested wiki markdown files were edited +- syntax/rendering issues were corrected +- heading hierarchy was normalized +- link integrity pass was completed +- code block language tagging was applied where known +- readability clearly improved without changing intent +- output report summarizes edits and open follow-ups diff --git a/CHANGELOG.md b/CHANGELOG.md index b8a1cce80..c9dfc834b 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -90,6 +90,7 @@ In addition, to jump on a bandwagon, we're now fully **AI agent** ready with det *model*: `port-model`, `debug-model`, `analyze-model`, `reference-catalog` *github*: `github-issues`, `github-features` *diffusers*: `diffusers-code` + *docs*: `update-docs` *other*: `todo` - **CLI** - add `cli/hf-info` and update `cli/hf-search.py`