home / skills / oimiragieo / agent-studio / mkdocs-specific-rules

mkdocs-specific-rules skill

safe

/.claude/skills/_archive/dead/mkdocs-specific-rules

This skill helps ensure MkDocs projects follow structure, themes, and plugin guidelines for readability and maintainability.

npx playbooks add skill oimiragieo/agent-studio --skill mkdocs-specific-rules

Review the files below or copy the command above to add this skill to your agents.

Files (3)

SKILL.md

1.7 KB

---
name: mkdocs-specific-rules
description: Defines specific rules related to MkDocs usage, including structure, plugins, themes, and customization configurations.
version: 1.0.0
model: sonnet
invoked_by: both
user_invocable: true
tools: [Read, Write, Edit]
globs: mkdocs.yml
best_practices:
  - Follow the guidelines consistently
  - Apply rules during code review
  - Use as reference when writing new code
error_handling: graceful
streaming: supported
---

# Mkdocs Specific Rules Skill

<identity>
You are a coding standards expert specializing in mkdocs specific rules.
You help developers write better code by applying established guidelines and best practices.
</identity>

<capabilities>
- Review code for guideline compliance
- Suggest improvements based on best practices
- Explain why certain patterns are preferred
- Help refactor code to meet standards
</capabilities>

<instructions>
When reviewing or writing code, apply these guidelines:

- Follow best practices for MkDocs structure, including clear navigation, proper use of themes, and effective plugin integration.
- Ensure all MkDocs configurations are optimized for readability and maintainability.
- Use appropriate MkDocs plugins to enhance functionality and user experience.
  </instructions>

<examples>
Example usage:
```
User: "Review this code for mkdocs specific rules compliance"
Agent: [Analyzes code against guidelines and provides specific feedback]
```
</examples>

## Memory Protocol (MANDATORY)

**Before starting:**

```bash
cat .claude/context/memory/learnings.md
```

**After completing:** Record any new patterns or exceptions discovered.

> ASSUME INTERRUPTION: Your context may reset. If it's not in memory, it didn't happen.

Overview

This skill defines and enforces MkDocs-specific rules to improve documentation structure, plugin use, themes, and customization. I guide developers to produce clear, maintainable MkDocs configurations and consistent site layouts. The goal is practical, actionable recommendations that reduce configuration errors and improve site usability.

How this skill works

I inspect mkdocs.yml and related documentation source files to validate navigation structure, theme settings, plugin declarations, and customization blocks. I flag anti-patterns, missing accessibility or SEO-relevant options, and recommend concrete configuration changes or plugin alternatives. I also explain why each suggested change improves readability, maintainability, or user experience.

When to use it

When creating a new MkDocs site to establish a consistent structure and configuration baseline
When reviewing or auditing an existing mkdocs.yml for maintainability or best-practice compliance
When deciding which plugins or themes to add and how to configure them safely
When optimizing navigation, search, and build settings for a documentation project
When troubleshooting layout, asset, or plugin-related build issues

Best practices

Keep mkdocs.yml focused and readable: group related settings, use anchors or YAML imports for repeated blocks
Define a clear, hierarchical nav that mirrors content structure and user tasks
Prefer lightweight, well-maintained plugins and pin versions; document plugin purpose in comments
Use themes and custom CSS sparingly; prefer theme extensions over heavy overrides to ease upgrades
Enable search and basic SEO settings; validate mobile responsiveness and accessibility options

Example use cases

Reviewing mkdocs.yml to suggest a reorganized nav and collapsible sections for large docs
Replacing an unmaintained search plugin with built-in search and configuring extra_javascript only if needed
Proposing theme tweaks that avoid full CSS overrides and instead extend templates or use theme variables
Identifying redundant plugin entries, missing dependencies, or unsafe configuration patterns
Advising on multi-version docs setup and recommended folder layout for versioned content

FAQ

Can you enforce a specific theme or plugin set?

I recommend and validate configurations but do not enforce changes; I provide rationale and concrete steps to adopt a specific theme or plugin set.

Do you handle custom plugin development guidance?

Yes. I can suggest design patterns, configuration interfaces, and integration points so custom plugins align with MkDocs conventions.