Agent skill
obsidian-markdown-structure
Validate and enforce markdown document structure including frontmatter positioning, heading hierarchy, and content organization. Use when creating or validating markdown files.
Install this agent skill to your Project
npx add-skill https://github.com/majiayu000/claude-skill-registry/tree/main/skills/data/obsidian-markdown-structure
SKILL.md
Markdown Structure Validation
Enforce consistent markdown structure across all vault content.
When to Use This Skill
Activate when you need to:
- Create new markdown documents
- Validate document structure
- Fix structural issues
- Ensure consistent formatting
Core Structure Rules
1. Frontmatter Positioning
Single YAML block at top, blank line after:
✅ CORRECT:
---
title: Document Title
created: 2025-10-31
tags:
- tag1
---
## First Section Header
Content starts here...
❌ INCORRECT:
---
title: Document Title
---
## First Section (no blank line)
❌ INCORRECT:
## Title
---
frontmatter: here
---
(frontmatter not at top)
Critical Rules:
- One YAML block only
- Must be first thing in file
- Blank line after closing
--- - No content before first heading
Note: This skill validates frontmatter POSITION (where it goes in the document). For frontmatter CONTENT (properties, values, formatting), use
obsidian-yaml-frontmatterskill.
2. Heading Hierarchy
Start with H2, no H1 duplication:
✅ CORRECT:
---
title: Document Title
---
## Introduction
Content...
### Subsection
Content...
❌ INCORRECT:
# Document Title (duplicates frontmatter title)
## Section
Hierarchy Rules:
- Use H2 (
##) for main sections - Use H3 (
###) for subsections - Use H4 (
####) sparingly - Don't skip levels (H2 → H4)
3. Content Organization
Summary-first structure:
✅ CORRECT:
---
frontmatter
---
## Summary
Overview of key points...
## Main Content
Detailed content...
## Related Topics
Links and connections...
❌ INCORRECT:
---
frontmatter
---
This is content without a heading.
## First Section
4. Quote Block Formatting
Blockquotes with attribution:
✅ CORRECT:
> "Quote text here" - Speaker/Context
> "Knowledge is power, but enthusiasm pulls the switch."
> - Ivern Ball
❌ INCORRECT:
"Quote text" (not in blockquote)
> Quote without attribution
Structure Validation Workflow
Step 1: Check Frontmatter
Verify:
- [ ] Single YAML block at top
- [ ] Blank line after closing ---
- [ ] All required properties present
- [ ] Consistent property names
Step 2: Check Heading Hierarchy
Verify:
- [ ] No H1 after frontmatter (except special cases)
- [ ] Main sections use H2
- [ ] Subsections use H3
- [ ] No skipped levels
- [ ] Logical organization
Step 3: Check Content Organization
Verify:
- [ ] No content before first heading
- [ ] Summary/overview section first
- [ ] Sections follow logical order
- [ ] Proper quote formatting
Step 4: Content-Type Specific
Check content follows appropriate template structure:
- [ ] Journal: H1 title, standard sections
- [ ] Roundup: Opening quote(s), structured headers
- [ ] Events: Executive Summary, Key Takeaways, Next Actions
- [ ] Clippings: Summary first, then detailed sections
Quality Checklist
Before completing structure validation:
- Single YAML frontmatter at top
- Blank line after frontmatter
- No content before first heading
- Heading hierarchy correct (H2 → H3 → H4)
- Quote blocks properly formatted
- Summary/overview section present
- Sections in logical order
- Template structure followed for content type
Recommended Agent Skills
Expand your agent's capabilities with these related and highly-rated skills.
majiayu000/claude-skill-registry
agent-ops-spec
Manage specification documents in .agent/specs/. Use when user provides requirements, acceptance criteria, or feature descriptions that need to be tracked and validated against implementation.
majiayu000/claude-skill-registry
agent-ops-state
Maintain .agent state files. Use at session start, after meaningful steps, and before concluding: read/update constitution/memory/focus/issues/baseline consistently.
majiayu000/claude-skill-registry
agent-ops-spec
Manage specification documents in .agent/specs/. Use when user provides requirements, acceptance criteria, or feature descriptions that need to be tracked and validated against implementation.
majiayu000/claude-skill-registry
agent-ops-testing
Test strategy, execution, and coverage analysis. Use when designing tests, running test suites, or analyzing test results beyond baseline checks.
majiayu000/claude-skill-registry
agent-ops-testing
Test strategy, execution, and coverage analysis. Use when designing tests, running test suites, or analyzing test results beyond baseline checks.
majiayu000/claude-skill-registry
agent-ops-state
Maintain .agent state files. Use at session start, after meaningful steps, and before concluding: read/update constitution/memory/focus/issues/baseline consistently.
Didn't find tool you were looking for?