manage-markdown-docs
Standardize markdown document creation and updates with proper headers and footers. Use when creating OR updating any markdown file that is NOT a subagent, command, or skill definition. Ensures consistent metadata, classification, and change tracking.
When & Why to Use This Skill
This Claude skill standardizes the creation and maintenance of Markdown documents by enforcing consistent metadata headers and change history footers. It streamlines technical documentation workflows, ensuring all files—from research notes to design docs—are professionally formatted, lint-compliant, and easily trackable for better project governance.
Use Cases
- Technical Documentation: Automatically generating structured design documents or architecture reviews with mandatory metadata and version tracking.
- Knowledge Management: Organizing internal research findings and analysis reports into standardized categories like 'external-research' or 'internal-analysis' for easier retrieval.
- Audit Trails: Maintaining an automated 'Change History' table in project documents to track who made specific updates and when, ensuring accountability.
- Quality Assurance: Enforcing markdown linting rules and Mermaid diagram standards across all project files to ensure professional and consistent visual presentation.
| name | manage-markdown-docs |
|---|---|
| description | Standardize markdown document creation and updates with proper headers and footers. Use when creating OR updating any markdown file that is NOT a subagent, command, or skill definition. Ensures consistent metadata, classification, and change tracking. |
Diagrams:
- All diagrams MUST use Mermaid format
- Use fenced code blocks with
mermaidlanguage identifier - Supported diagram types: flowchart, sequence, class, state, ER, gantt, pie, mindmap
Example:
flowchart TD
A[Start] --> B{Decision}
B -->|Yes| C[Action]
B -->|No| D[End]
If user provides a specific file path:
- MUST use that path exactly
- NEVER suggest alternatives
- NEVER question the location
If NO path provided, determine based on document type and project structure.
Classify every document into ONE of these categories: **External Research Finding** - Information gathered from outside sources - Web research, API documentation, third-party analysis - Competitor analysis, market research - Directory suggestion: `research/` or `docs/research/` **Internal Analysis Report** - Analysis of internal systems, code, or processes - Performance reports, architecture reviews - Code quality assessments, technical debt analysis - Directory suggestion: `analysis/` or `docs/analysis/` **Contextual Document** - Background information for ongoing work - Project context, decision rationale - Historical context, migration notes - Directory suggestion: `context/` or `docs/context/` **Other** - Documents that don't fit above categories - Meeting notes, scratch documents, miscellaneous - Directory suggestion: `docs/` or project root Every document MUST start with this header structure:---
document: [Document Name]
created: [YYYY-MM-DD HH:MM]
classification: [external-research | internal-analysis | contextual | other]
---
**Purpose**: [What this document is for]
**Author**: [Who created it - can be "Claude" or user name]
**Context**: [Why this document was created - what prompted it]
---
- **document**: Clear, descriptive name (not the filename)
- **created**: Current date and time when document is first created
- **classification**: One of the four categories above
- **Purpose**: 1-2 sentences on what the document achieves
- **Author**: Who or what produced this document
- **Context**: The triggering event or need that led to creation
Every document MUST end with this footer structure:
---
## Change History
| Date | Change | Author |
|------|--------|--------|
| [YYYY-MM-DD] | Initial creation | [Author] |
After EVERY modification to the document:
1. Add a new row to the Change History table
2. Include date, brief description of change, and who made it
3. Keep entries in reverse chronological order (newest first)
Example after updates:
## Change History
| Date | Change | Author |
|------|--------|--------|
| 2024-03-15 | Added section on error handling | Claude |
| 2024-03-14 | Expanded API examples | User |
| 2024-03-14 | Initial creation | Claude |
```markdown
---
document: Authentication Flow Analysis
created: 2024-03-14 09:30
classification: internal-analysis
---
Purpose: Document the current authentication flow and identify potential improvements Author: Claude Context: User requested security review of login system
[Document content goes here...]
Change History
| Date | Change | Author |
|---|---|---|
| 2024-03-14 | Initial creation | Claude |
</complete_example>
<success_criteria>
Document is correctly structured when:
- Header contains all required fields (document, created, classification)
- Purpose, Author, and Context are clearly stated
- Classification matches document content
- Footer has Change History table
- Change History is updated after every modification
- Path respects user-provided location or follows classification-based suggestion
- Markdown is lint-free (proper spacing, heading levels, code fences)
- Any diagrams use Mermaid format
</success_criteria>
<anti_patterns>
<avoid>
- Creating documents without headers
- Skipping change history updates
- Overriding user-specified paths
- Applying this to subagents, commands, or skills
- Using vague document names like "Notes" or "Document"
- Leaving Purpose/Author/Context empty
- Producing markdown with lint errors (missing blank lines, skipped heading levels)
- Using ASCII art, PlantUML, or other diagram formats instead of Mermaid
- Code fences without language specifiers
</avoid>
</anti_patterns>