Markdown Editor

Quick Start

Prerequisites:

• Git configured (git config user.name for author extraction)
• Write access to target directory

Tools Used: Read, Write, Edit, Bash (for git config, mkdir)

Basic Usage:

1. Determine document type (research, plan, docs, README, TODO, CHANGELOG)
2. Choose location based on type
3. Create directory if needed
4. Write with appropriate frontmatter (or none for special files)

When to Use Me

Use this skill when you:

• Create, write, or generate new markdown (.md) files
• Edit, update, or modify existing markdown content
• Write research notes, findings, or analysis documents
• Create implementation plans, strategies, or roadmaps
• Build or update README files for projects or modules
• Manage TODO lists or CHANGELOG files
• Need to save agent research findings persistently

Additional Triggers

Also use this skill when you:

• Fix markdown lint issues or formatting problems
• Reflow or wrap long lines in documentation
• Validate frontmatter structure or fix schema issues
• Check or fix broken links in documentation

What I Do

• Create and edit markdown files with consistent structure
• Apply YAML frontmatter (title, author, timestamps, type, tags)
• Organize docs by type: research → ./docs/research/, plans → ./docs/plans/
• Handle special files (README, TODO, CHANGELOG) without frontmatter
• Generate descriptive kebab-case filenames
• Extract author from git config, manage ISO 8601 timestamps

Document Type Quick Reference

Frontmatter Template

---
title: Descriptive Title
created: 2025-12-25T14:30:00Z
last_modified: 2025-12-25T14:30:00Z
author: John Doe
type: research|plan|documentation
tags: [tag1, tag2]
---

Common Errors

Diagrams and Callouts

Modern docs often include inline diagrams and callouts. Use these Markdown extensions where the renderer supports them.

Mermaid Diagrams

GitHub, GitLab, and most static-site generators render ```mermaid fenced blocks into diagrams.

Flowchart:

```mermaid
flowchart LR
    A[User] --> B[API Gateway]
    B --> C[Service A]
    B --> D[Service B]
```

Sequence diagram:

```mermaid
sequenceDiagram
    participant U as User
    participant A as API
    U->>A: POST /orders
    A-->>U: 201 Created
```

Keep diagrams small. If a diagram needs more than ~15 nodes, split it or use the referenced examples.md for larger compositions.

Admonitions (GitHub-Flavored)

GitHub renders blockquote-prefixed callouts as colored admonitions:

> [!NOTE]
> Highlights information that users should take into account.

> [!TIP]
> Optional advice to help users be more successful.

> [!IMPORTANT]
> Crucial information necessary for success.

> [!WARNING]
> Critical content demanding immediate attention.

> [!CAUTION]
> Advises about risks or negative outcomes.

Other renderers (MkDocs admonition, Docusaurus, Hugo shortcodes) use different syntax — only emit > [!TYPE] when you know the renderer is GitHub or a GitHub-compatible adapter.

References

Validation Checklist

• Document type identified (research, plan, docs, README, TODO, CHANGELOG)
• Location follows conventions
• Directory exists (create if needed)
• Filename is descriptive, kebab-case, no timestamp
• Frontmatter included only when appropriate
• Timestamps in ISO 8601 UTC format (ending in 'Z')
• When editing: preserve created/author, update last_modified

Related Skills