Skill: smilingwayne/refine-markdown-to-mkdocs (version 1.0.0)

--- name: refine-markdown-to-mkdocs description: Refines raw reading notes by merging similar ideas, removing noise, and summarizing key points. Outputs structured markdown with different format (mkdocs materials style), e.g., Admonitions, bullet points, hightlights, blockquotes and so on. Use for "clean up notes", "summarize reading", "refine bookmarks", "get highlight cores". --- # refine-markdown-to-mkdocs Transforms raw, scattered reading notes into structured, high-density knowledge modules. Unlike the Formatter, this Skill **IS ALLOWED** to delete, merge, add (minor), or rewrite content flexibily for clarity and brevity. **Core Principle**: Domain-Adaptive Structuring, Category-Specific Logic, Controlled Fidelity and High-Density Output. ## Workflow ### Step 1: Read & Detect category or content type Read the input file. Identify the source material (Book Title, Author, Nation, Chapter, Genre, Style). You MUST classify it into the following categories (quick reference): 1. **Philosophy theory, thoughts** 2. **Plays** (tragedy, comedy, stage play etc) 3. **Novels** 4. **Poetry** (epic, sonnet,lyric, narrative, satirical etc.) 5. **Literary Theory and Criticism** (poem/novel/prose/play etc. theories) 6. **Prose** 7. **History and history notes** 8. **Art Theory and collections** 9. **Biography** (philosophers, celebrities, leaders etc.) 10. **Programming and Computer Science** (Artificial Intelligence, Deep Learning, Large Language Models etc.) 11. **Mathematical models and theory** (Operations Research, Linear Algebra, Calculus, Algorithms etc) 12. **Integration of materials without a clear focus** 13. **Others** (notes that don't belong to any of the above) **Sure about category**: Pause and ask the user for confirmation to continue, present: ```markdown One category detected. - [Category A]: Confirm, or choose a custom category: (Y/N) ``` `Y` for `yes` and `N` for `no`. If `N`, If not, enumrate the full categories to user with numebr in front and ask user to pick one. Note your recommended one with `(recommended)`. **Not sure or ambigous about category**: Pause and ask the user: "Mutliple categories covered. What genre or category do you believe it belongs to?" Generate 2~3 different categories candidates, present to user: ``` Pick a genre: 1. [Category A] - (recommend) 2. [Category B] - (category note) 3. [Category C] - (category note) Enter number, or type a custom category: ``` The category you present and user select MUST be in the given categories. If not, enumrate the full categories to user with numebr in front and ask user to pick one. Note your recommended one with `(recommended)` ### Step 2: Semantic Clustering (Analysis) Based on category chosen in Step.1, view the classification rules of the specific category in [references/notes_classify.md](references/notes_classify.md). The category-specific **Primary Focus** and High/Medium/Low Value Classification Rules are the guidelines you follow. For example, category `Novels` follows: ```markdown **Primary Focus:** Narrative voice, character development, thematic depth, and stylistic devices. **Classification Rules:** 1. **High Value:** Character arcs (psychological evolution), narrative perspective shifts, symbolic imagery, author's stylistic signatures, critical reception. -> **Keep & Polish** 2. **Medium Value:** Plot points, setting details, secondary character profiles, timeline of events. -> **Merge & Summarize** 3. **Low Value:** Minor plot details, redundant summaries, subjective emotional rants without textual evidence. -> **Delete (Log in report)** ``` After your analysis and cluster, save your plans in the **Output Plan File**: `{filename}-plan.md` Structure: ```markdown # Refinement Plan ## Cluster 1: [Theme Name] - Source snippets: [Line numbers or quotes] - Action: Merge into 1/2/3 Admonition block - Draft Summary: [One sentence] ## Cluster 2: [Theme Name] ... ## Deletion List - [Snippet content] -> Reason: Redundant/Unclear ``` **Pause for User Confirmation:** Show the plan. Ask: "Proceed with this refinement structure? (Yes/No/Edit)" ### Step 3: Content Reconstruction (The Core) Generate the refined content based on the approved plan. **Writing Rules:** 1. **One Block, One Idea**: Each semantic cluster becomes **one Admonition block**. 2. **Summary First**: Every Admonition must start with a **1-sentence summary** (bolded or as title). 3. **Merge Smoothly**: When combining snippets, rewrite transitions so it reads like a coherent paragraph, not a list of quotes. 4. **Preserve Voice**: If it's literature, keep the emotional tone. If non-fiction, keep the logical precision, if philosophy, follow strict logic, etc. 5. **No Hallucination**: Do not add new knowledge not found in the notes. Only clarify existing knowledge. Apply formatting guided by the Step 2 analysis to make markdown text prettier. Encouraged to use different styles to make text prettier. The goal is making the content scannable and the key points impossible to miss. **Formatting toolkit:** | Element | When to use | Format | | --------------- | --------------------------------------------------------------------- | ------------------------------------------------------ | | Headings | Natural topic boundaries, section breaks | `##`, `###` hierarchy | | Bold | Key conclusions, important terms, core takeaways | `**bold**` | | Unordered lists | Parallel items, feature lists, examples | `- item` | | Ordered lists | Sequential steps, ranked items, procedures | `1. item` | | Highlights | Critical details, important comparisons for quick and short attention | `==text==` | | Color highlight | Colored emphasis where standard bold are insufficient | `<span style="color:red;font-weight:bold">text</span>` | | Tables | Comparisons, structured data, option matrices | Markdown table | | Code | Commands, file paths, technical terms, variable names | `` `inline` `` or fenced blocks | | Blockquotes | Notable quotes, important warnings, cited text | `> blockquotes` | | Admonition | More notable quotes, definition, examples, conclusion | Follow **Admonition Syntax Rules** below. | | Separators | Major topic transitions | `---` | For Unordered lists, Ordered lists (e.g., `- TEXT` and `1. TEXT`), there MUST be one empty line before the very beginning and one empty line after the end. - Correct Format: ```markdown This is the previous text. - This is bullet point 1; (correct, 1 empty line before) - This is bullet point 2; This is the line afterwards (correct. ). ``` - Incorrect Format (DO NOT DO THIS): ``` This is the previous text. - This is bullet point 1; (Wrong! MUST be 1 empty line) - This is bullet point 2; This is the line afterwards (Wrong! No empty line away from bullet points). ``` For Admonition you created, strictly follows **Admonition Syntax Rules** below. **Admonition Syntax Rules** Strict Enforcement. When using MkDocs-style admonitions (e.g., `!!! note`, `!!! example`, `!!! warning`), you must follow these indentation rules strictly. Markdown parsers require content inside blocks to be indented. - Correct Format: ```markdown !!! note "Title Text" This is the content. It must start with 4 spaces, and the above line is empty. This is a second paragraph. It also needs **4** spaces indentation. - List items also follows. The end line should have an empty line with no indent below. - List items follows too. This is the line outside admonition (correct). ``` - Incorrect Format (DO NOT DO THIS): ```markdown !!! note "Title Text" This content has no indent. (Wrong - breaks indent rule) !!! note "Title Text" First paragraph ok. Second paragraph has no indent. (Wrong - breaks the block) ``` Syntax rules: 1. **Indentation**: All content belonging to the admonition must be indented **4 spaces** relative to the `!!!`. 2. **Paragraph Breaks**: Blank lines inside the block must also be indented (or simply ensure the next paragraph starts with 4 spaces). 3. **Nested Lists/Code**: If using lists or code inside an admonition, indent them **8 spaces** total. 4. **Consistency**: Do not mix tabs and spaces. Use 4 spaces consistently. ``` ### Step 4: Save & Backup Save as `{filename}-refined.md`. Backup existing refined file if present (same logic as Formatter). ### Step 5: Completion Report Report specifically on **Content Changes**: ``` **Refinement Complete** **Stats:** - Original Snippets: X - Refined Blocks: Y - Deletion Rate: Z% **Major Mergers:** - [Theme A]: Merged 5 snippets into 1 block - [Theme B]: Merged 3 snippets into 1 block **Deleted Content (Summary):** - Removed 10+ repetitive observations about [Character X] - Removed incomplete thoughts regarding [Topic Y] **Files:** - Plan: {filename}-plan.md - Refined: {filename}-refined.md ``` ## Notes - **Safety**: Never delete a direct quote without marking it as deleted in the report. - **Category-Specific Mode**: based on the category you detected (user selected), cluster contents via different standards and perspectives without diminish the inner cores. - **Admonition Integrity**: Must generate correct structure initially to avoid parsing errors. ```

path: references/notes_classify.md
content: # Notes by Category (Quick Reference)

1. **Philosophy theory, thoughts**
2. **Plays** (tragedy, comedy, stage play etc)
3. **Novels**
4. **Poetry** (epic, sonnet,lyric, narrative, satirical etc.)
5. **Literary Theory and Criticism** (poem/novel/prose/play etc. theories)
6. **Prose**
7. **History and history notes**
8. **Art Theory and collections**
9. **Biography** (philosophers, celebrities, leaders etc.)
10. **Programming and Computer Science** (Artificial Intelligence, Deep Learning, Large Language Models etc.)
11. **Mathematical models and theory** (Operations Research, Linear Algebra, Calculus, Algorithms etc)
12. **Integration of materials without a clear focus**
13. **Others** (notes that don't belong to any of the above)

## 1. Philosophy theory, thoughts

**Primary Focus:** Epistemological frameworks, logical arguments, ontological claims, and ethical systems.

**Classification Rules:**
1.  **High Value:** Core arguments, seminal propositions, logical fallacies identified, paradoxes, and transformative insights. -> **Synthesize & Archive**
2.  **Medium Value:** Historical context of the school of thought, biographical details of the philosopher, comparisons with opposing views. -> **Summarize & Link**
3.  **Low Value:** Redundant definitions, obvious tautologies, personal musings without logical grounding. -> **Discard or Tag for Review**

## 2. Plays (Tragedy, Comedy, Stage Play etc.)

**Primary Focus:** Dramatic structure, dialogue dynamics, staging implications, and conflict resolution.

**Classification Rules:**
1.  **High Value:** Dramatic arc (exposition to resolution), character conflicts, thematic motifs, significant stage directions, subtext analysis. -> **Keep & Polish**
2.  **Medium Value:** Plot summary by act/scene, cast list, setting descriptions, historical premiere context. -> **Merge & Summarize**
3.  **Low Value:** Trivial dialogue exchanges, repetitive stage instructions, production-specific trivia unrelated to the text. -> **Delete (Log in report)**

## 3. Novels

**Primary Focus:** Narrative voice, character development, thematic depth, and stylistic devices.

**Classification Rules:**
1.  **High Value:** Character arcs (psychological evolution), narrative perspective shifts, symbolic imagery, author's stylistic signatures, critical reception. -> **Keep & Polish**
2.  **Medium Value:** Plot points, setting details, secondary character profiles, timeline of events. -> **Merge & Summarize**
3.  **Low Value:** Minor plot details, redundant summaries, subjective emotional rants without textual evidence. -> **Delete (Log in report)**

## 4. Poetry (Epic, Sonnet, Lyric, Narrative, Satirical etc.)

**Primary Focus:** Prosody, imagery, symbolism, emotional resonance, and structural form.

**Classification Rules:**
1.  **High Value:** Metrical analysis (meter/rhyme scheme), key symbols/metaphors, emotional tone shifts, structural integrity (stanza form). -> **Keep & Polish**
2.  **Medium Value:** Biographical context of the poet, publication history, literal paraphrase of content. -> **Merge & Summarize**
3.  **Low Value:** Obvious translations (if original is known), generic praise, formatting errors in transcription. -> **Delete (Log in report)**

## 5. Literary Theory and Criticism

**Primary Focus:** Critical frameworks, methodologies, key terminology, and application to texts.

**Classification Rules:**
1.  **High Value:** Definitional frameworks (e.g., Structuralism, Post-colonialism), methodological applications, key critic arguments, paradigm shifts. -> **Synthesize & Archive**
2.  **Medium Value:** Specific case studies used in the theory, critic's biography, affiliation with schools of thought. -> **Summarize & Link**
3.  **Low Value:** Outdated critiques, redundant definitions, unrelated literary gossip or news. -> **Discard or Tag for Review**

## 6. Prose (Essays, Non-fiction)

**Primary Focus:** Argumentation structure, rhetorical strategies, voice, and actionable insights.

**Classification Rules:**
1.  **High Value:** Central thesis, rhetorical devices (ethos/pathos/logos), unique authorial voice, actionable takeaways. -> **Keep & Polish**
2.  **Medium Value:** Supporting arguments, anecdotal evidence, contextual background information. -> **Merge & Summarize**
3.  **Low Value:** Filler content, repetitive statements, obvious facts already known. -> **Delete (Log in report)**

## 7. History and history notes

**Primary Focus:** Chronological causality, socio-political context, turning points, and historiographical debates.

**Classification Rules:**
1.  **High Value:** Causal relationships (cause/effect), pivotal turning points, socio-political impact, conflicting historical interpretations. -> **Synthesize & Archive**
2.  **Medium Value:** Chronological timelines, key figures (roles only), geographic context, treaty/terms details. -> **Summarize & Link**
3.  **Low Value:** Minor dates without significance, trivial biographical details of minor figures, unverified anecdotes. -> **Discard or Tag for Review**

## 8. Art Theory and collections

**Primary Focus:** Aesthetic principles, movement characteristics, technical innovation, and critical reception.

**Classification Rules:**
1.  **High Value:** Aesthetic principles, movement manifestos, technical innovations, critical analysis of specific works. -> **Keep & Polish**
2.  **Medium Value:** Artist biography, provenance of works, museum locations, exhibition history. -> **Merge & Summarize**
3.  **Low Value:** Personal preference without justification, low-res image metadata, redundant catalog info. -> **Delete (Log in report)**

## 9. Biography (Philosophers, Celebrities, Leaders etc.)

**Primary Focus:** Life trajectory, pivotal decisions, psychological profile, and legacy impact.

**Classification Rules:**
1.  **High Value:** Pivotal life decisions, psychological profiling, correlation with historical events, legacy/impact analysis. -> **Synthesize & Archive**
2.  **Medium Value:** Chronological life events, professional relationships, career milestones, education background. -> **Summarize & Link**
3.  **Low Value:** Daily trivialities, unverified rumors, excessive family tree details unrelated to public life. -> **Discard or Tag for Review**

## 10. Programming and Computer Science (AI, DL, LLM etc.)

**Primary Focus:** Algorithmic logic, architectural patterns, complexity analysis, and implementation details.

**Classification Rules:**
1.  **High Value:** Core algorithms, architectural patterns, complexity analysis (Big O), edge cases, optimization strategies. -> **Keep & Polish**
2.  **Medium Value:** Syntax details, library documentation, standard use cases, version history, dependency management. -> **Merge & Summarize**
3.  **Low Value:** Deprecated code, trivial syntax errors, basic "Hello World" examples, redundant comments. -> **Delete (Log in report)**

## 11. Mathematical models and theory (OR, Linear Algebra, Calculus etc.)

**Primary Focus:** Axiomatic foundations, theorem proofs, model limitations, and practical applications.

**Classification Rules:**
1.  **High Value:** Theorem proofs, underlying assumptions, model limitations/boundaries, derivations, real-world applications. -> **Synthesize & Archive**
2.  **Medium Value:** Definitions, standard formulas, historical origin of theory, notation conventions. -> **Summarize & Link**
3.  **Low Value:** Arithmetic calculations, obvious algebraic steps, redundant notation explanations. -> **Discard or Tag for Review**

## 12. Integration of materials without a clear focus

**Primary Focus:** Cross-disciplinary connections, synthesized insights, emerging patterns, and meta-analysis.

**Classification Rules:**
1.  **High Value:** Cross-disciplinary connections, synthesized insights, emerging patterns, meta-analysis, new hypotheses. -> **Keep & Polish**
2.  **Medium Value:** Raw material links, tentative hypotheses, tagging for future review, source mapping. -> **Merge & Summarize**
3.  **Low Value:** Disconnected fragments, orphaned notes, duplicate imports, unprocessed raw data. -> **Delete (Log in report)**

## 13. Others (Notes that don't belong to any of the above)

**Primary Focus:** Triage, categorization, and temporary storage.

**Classification Rules:**
1.  **High Value:** Potentially valuable but uncategorized ideas (flag for immediate re-categorization). -> **Reclassify & Archive**
2.  **Medium Value:** Temporary storage, inbox items, pending verification. -> **Summarize & Link**
3.  **Low Value:** Spam, irrelevant data, fully processed/archived items, duplicates. -> **Delete (Log in report)**

Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: clean (LOW)