菜单
Enhanced docs linting with AI-powered features. Enhanced with Context7 MCP for up-to-date documentation.
默认使用会先检查来源的 Prompt；你也可以切换为直接命令，或下载本地副本。
决定是否安装前，请先阅读 SKILL.md，以及 SkillsMP 当前展示的配套文件。
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
直接命令不会经过审查 Prompt；运行前请先检查来源。
npx skills add https://github.com/AJBcoding/claude-skill-eval --skill moai-docs-linting命令会保持在同一行。复制前请横向滚动并检查完整内容。
想先保存到本地？可下载 SkillsMP 当前能够提供的文件。
基于 SOC 职业分类
正在显示 SKILL.md
| name | moai-docs-linting |
| version | 4.0.0 |
| created | 2025-11-12T00:00:00.000Z |
| updated | 2025-11-12T00:00:00.000Z |
| status | stable |
| tier | specialization |
| description | Enhanced docs linting with AI-powered features. Enhanced with Context7 MCP for up-to-date documentation. |
| allowed-tools | Read, Glob, Grep, WebSearch, WebFetch, mcp__context7__resolve-library-id, mcp__context7__get-library-docs |
| primary-agent | doc-syncer |
| secondary-agents | ["alfred"] |
| keywords | ["docs","linting","cd","spec","ci"] |
| tags | ["documentation"] |
| orchestration | null |
| can_resume | true |
| typical_chain_position | terminal |
| depends_on | [] |
Docs Linting
Primary Agent: doc-syncer
Secondary Agents: alfred
Version: 4.0.0
Keywords: docs, linting, cd, spec, ci
📚 Content
Documentation linting automatically detects formatting issues, broken references, and structural problems in markdown files. This skill provides comprehensive validation strategies for:
- and *), indentation problemsKey Benefits:
Rules:
- H1 (# Title): Exactly 1 per document
- H2-H6 (## Subtitle, etc.): Can be multiple
- Level Hierarchy: No skipping levels
Example - Good:
# Main Title (single H1)
---
### Level 2: Practical Implementation (Common Patterns)
📚 Content
### Section 1: Linting Overview
Documentation linting automatically detects formatting issues, broken references, and structural problems in markdown files. This skill provides comprehensive validation strategies for:
- **Header Structure**: Duplicate H1s, level skipping, hierarchy violations
- **Code Blocks**: Missing language declarations, unclosed blocks, syntax issues
- **Links**: Broken references, invalid paths, protocol consistency
- **Lists**: Marker consistency (mixing `-` and `*`), indentation problems
- **Tables**: Column count mismatch, alignment issues
- **Typography**: Trailing whitespace, full-width characters, encoding issues
**Key Benefits**:
- Catch errors before documentation builds
- Ensure consistency across all documents
- Improve readability and user experience
- Validate multilingual document structure
### Section 2: Core Linting Rules
#### Header Validation
```yaml
Rules:
- H1 (# Title): Exactly 1 per document
- H2-H6 (## Subtitle, etc.): Can be multiple
- Level Hierarchy: No skipping levels (# → ## → ###)
- Duplicates: No duplicate headers on same level
- Special Characters: No emojis in headers (MoAI-ADK standard)
Example - Good:
# Main Title (single H1)
---
Section 2
### Subsection 2.1
Example - Bad:
# Title 1
# Title 2 ❌ Multiple H1s
---
Subsection
#### Deep level ❌ Skipped H3
Rules:
- Language Declaration: Every block must specify language
- Matching Delimiters: Opening ``` must match closing ```
- Placement: Code blocks on separate lines
- Content: Valid code examples
Example - Good:
\`\`\`python
def hello():
print("Hello, World!")
\`\`\`
Example - Bad:
\`\`\`
def hello():
\`\`\`python ❌ Mismatched delimiters
\`\`\` ❌ No language specified
def hello():
\`\`\`
Rules:
- Relative Links: Use ../ for cross-directory navigation
- External Links: Must use https:// protocol
- Valid References: All linked files must exist
- Anchor Links: Point to valid headers
Example - Good:
[Install Guide](../getting-started/installation.md)
[External](https://example.com)
[Section](#header-anchor)
Example - Bad:
[Link](../../nonexistent.md) ❌ File doesn't exist
[Link](http://example.com) ❌ Not https
[Link](#invalid-section) ❌ Header doesn't exist
Rules:
- Marker Consistency: Don't mix - and * in same list
- Indentation: Use 2-4 spaces (never tabs)
- Nesting: Consistent indentation for nested items
- Separator: Blank line required after list
Example - Good:
- Item 1
- Item 2
- Nested 2.1
- Nested 2.2
- Item 3
Example - Bad:
- Item 1
* Item 2 ❌ Mixed markers
- Item 3 ❌ Tab indentation
Rules:
- Column Consistency: All rows must have same column count
- Header Line: Required | --- | separator
- Alignment: Optional but consistent :--|:--:|--:
Example - Good:
| Header 1 | Header 2 | Header 3 |
|----------|----------|----------|
| Cell 1 | Cell 2 | Cell 3 |
| Cell 4 | Cell 5 | Cell 6 |
Example - Bad:
| Header 1 | Header 2
| Cell 1 | Cell 2 | Cell 3 | ❌ Column mismatch
For Korean Documents (ko/):
For Other Languages (en/, ja/, zh/):
Python Linting Script Pattern:
class DocumentationLinter:
def __init__(self, docs_path: str):
self.docs_path = Path(docs_path)
self.errors = []
self.warnings = []
def lint_headers(self, content: str) -> List[str]:
"""Validate header structure"""
h1_count = len(re.findall(r'^# ', content, re.MULTILINE))
if h1_count != 1:
return [f"Error: Found {h1_count} H1 headers (expected 1)"]
return []
def lint_code_blocks(self, content: str) -> List[str]:
"""Validate code block pairs"""
issues = []
# Check for ```language declaration
# Check for matching delimiters
# Validate content
return issues
def lint_links(self, content: str, file_path: Path) -> List[str]:
"""Validate link references"""
# Find all [text](path) patterns
# Verify file existence
# Check protocol (https for external)
return issues
Integration with CI/CD:
# Pre-commit validation
python3 .moai/scripts/lint_korean_docs.py
python3 .moai/scripts/validate_mermaid_diagrams.py
python3 .moai/scripts/validate_korean_typography.py
# Generate comprehensive report
python3 .moai/scripts/generate_final_comprehensive_report.py
Header Style (from November 9 validation):
Link Standards:
Code Block Standards:
Internationalization:
✅ Validation Checklist
Note: Advanced patterns for complex scenarios.
Coming soon: Deep dive into expert-level usage.
Must-Have:
Recommended:
Security:
When to Use Context7 for This Skill:
This skill benefits from Context7 when:
Example Usage:
# Fetch latest documentation
from moai_adk.integrations import Context7Helper
helper = Context7Helper()
docs = await helper.get_docs(
library_id="/org/library",
topic="docs",
tokens=5000
)
Relevant Libraries:
| Library | Context7 ID | Use Case |
|---|---|---|
| [Library 1] | /org/lib1 | [When to use] |
When to use moai-docs-linting:
Start
├─ Need docs?
│ ├─ YES → Use this skill
│ └─ NO → Consider alternatives
└─ Complex scenario?
├─ YES → See Level 3
└─ NO → Start with Level 1
Prerequisite Skills:
Complementary Skills:
Next Steps:
Metadata
skill_id: moai-docs-linting
skill_name: Documentation Linting & Markdown Validation
version: 1.0.0
created_date: 2025-11-10
updated_date: 2025-11-10
language: english
word_count: 1400
triggers:
- keywords: [markdown lint, documentation validation, lint check, header validation, code block, link validation, table format]
- contexts: [docs-linting, @docs:lint, documentation-validation, quality-gate]
agents:
- docs-manager
- docs-auditor
- quality-gate
freedom_level: high
context7_references:
- url: "https://github.com/igorshubovych/markdownlint"
topic: "Markdownlint Rules"
- url: "https://www.markdownguide.org/basic-syntax/"
topic: "Markdown Basic Syntax"
v4.0.0 (2025-11-12)
Generated with: MoAI-ADK Skill Factory v4.0
Last Updated: 2025-11-12
Maintained by: Primary Agent (doc-syncer)