name: managing-shirokuma-md-docs
description: Manages shirokuma-md documentation workflows including build, validate, analyze, lint, and token optimization operations. Use when user requests "build docs", "validate markdown", "lint documentation", "analyze structure", "optimize docs", "token reduction", "ビルドして", "検証して", "分析して", "最適化して", or when working with shirokuma-md projects and markdown documentation.
allowed-tools: Read, Write, Edit, Glob, Grep, Bash

shirokuma-md Skill

Unified skill for all shirokuma-md documentation operations. Analyzes user requests and executes appropriate workflows.

Tool Usage Constraints

When using Bash tool:
- ✅ ONLY use shirokuma-md CLI commands:
- shirokuma-md build
- shirokuma-md validate
- shirokuma-md analyze
- shirokuma-md lint (with --fix, --suggest-fixes options)
- ❌ DO NOT use Python scripts directly
- ❌ DO NOT use other tools or commands
- ❌ DO NOT use general-purpose agents

Rationale: The shirokuma-md CLI is the single source of truth for all operations. Using it ensures consistency, proper configuration loading, and maintainability.

When to Use

Automatically invoke when the user:
- Requests "build documentation", "combine markdown files", or "ビルドして"
- Says "validate markdown", "検証して", "check docs", or "verify documentation"
- Mentions "lint docs", "format markdown", "fix formatting", or "フォーマット"
- Asks to "analyze structure", "show dependencies", "分析して", or "check relationships"
- Requests "create new document", "新しいドキュメント作成", or "generate character"
- Says "review this file", "レビューして", or "check this document"
- Asks about "document structure", "architecture", "構造設計", or "organize docs"
- Mentions "schema", "catalog", "template", or "frontmatter" in context of documentation
- Requests "token optimization", "最適化", "reduce tokens", or "apply suggestions"
- Works with shirokuma-md projects or LLM-optimized markdown documentation
- References shirokuma-md.config.yaml or .claude/skills/shirokuma-md/

Architecture

• SKILL.md - Router and coordinator (this file)
• reference/ - Centralized rules (single source of truth)
• validation-rules, lint-rules, layer-structure, token-optimization
• frontmatter-schemas, authoring-reference, examples
• workflows/ - Execution workflows
• build, validate, analyze, lint, optimizer
• authoring, architect, schema, catalog, template

How This Skill Works

1. Analyze user request - Identify intent from keywords and context
2. Select workflow - Choose appropriate workflow from workflows/
3. Load rules - Reference centralized rules from reference/
4. Execute workflow - Follow workflow steps
5. Report results - Provide clear feedback to user

Intent Analysis

Build Operations

Keywords: "build", "ビルド", "combine", "結合", "merge"

Workflow: workflows/build.md

Example requests:
- "ビルドして"
- "Combine markdown files"
- "Build LLM context"

Actions:
1. Check shirokuma-md.config.yaml exists
2. Collect files matching build.include pattern
3. Sort by dependencies (topological)
4. Apply optimizations (strip frontmatter, remove internal links)
5. Combine with separators
6. Write output file
7. Report token count

Validation Operations

Keywords: "validate", "検証", "check", "チェック", "verify"

Workflow: workflows/validate.md

Example requests:
- "検証して"
- "Validate documentation"
- "Check for errors"

Actions:
1. Load validation rules from reference/validation-rules.md
2. Scan markdown files
3. Check frontmatter against schemas
4. Validate dependencies (layer rules)
5. Check format compliance
6. Generate validation report
7. Report errors/warnings/info

Analysis Operations

Keywords: "analyze", "分析", "structure", "dependencies", "依存関係"

Workflow: workflows/analyze.md

Example requests:
- "分析して"
- "Analyze structure"
- "Show dependencies"

Actions:
1. Scan and parse files
2. Build dependency graph
3. Detect cycles
4. Find orphaned files
5. Generate visualization (Mermaid/DOT/JSON)
6. Create analysis report

Lint Operations

Keywords: "lint", "format", "fix", "フォーマット", "整形"

Workflow: workflows/lint.md

Example requests:
- "Lint実行"
- "Fix formatting"
- "整形して"

Actions:
1. Load lint rules from reference/lint-rules.md
2. Scan files
3. Apply rules (no-mermaid-styling, no-navigation-sections, no-structural-bold)
4. Generate lint report
5. If --fix or user confirms: apply fixes
6. Report changes

Token Optimization Operations

Keywords: "optimize", "最適化", "token reduction", "トークン削減", "apply suggestions"

Workflow: workflows/optimizer.md

Example requests:
- "ドキュメントを最適化して"
- "Apply token optimization"
- "トークン削減の提案を適用"

Actions:
1. Generate lint report with --suggest-fixes
2. Analyze optimization opportunities
3. Propose fixes interactively (with user approval)
4. Apply approved fixes only
5. Show before/after diffs
6. Calculate token savings
7. Optionally commit changes

Philosophy: Detection → Report → AI Judgment → User Approval → Fix

Authoring Operations

Keywords:
- Create: "create", "作成", "new"
- Review: "review", "レビュー", "check document"
- Fix: "fix", "修正", "apply fixes"

Workflow: workflows/authoring.md

Example requests:
- "新しいキャラクターを作成"
- "このファイルをレビュー"
- "ドキュメントを修正"

Sub-workflows:

Create Document:

1. Determine document type
2. Collect required fields (schemas)
3. Determine layer (layer rules)
4. Generate dependencies
5. Create frontmatter
6. Generate content stub
7. Write file
8. Validate output

Review Document:

1. Read file
2. Parse frontmatter
3. Validate format (validation rules)
4. Check dependencies
5. Generate review report with issues and fixes

Apply Fixes:

1. Re-read document
2. Apply auto-fixable issues
3. Report changes
4. Validate after fixes

Architecture Operations

Keywords: "architect", "構造", "設計", "organize", "structure"

Workflow: workflows/architect.md

Example requests:
- "ドキュメント構造を設計"
- "How should I organize?"
- "構造を改善"

Actions:
1. Understand project requirements
2. Recommend layer structure
3. Suggest directory organization
4. Design dependency strategy
5. Plan token budget
6. Recommend file splitting
7. Generate architecture document

Schema Operations

Keywords: "schema", "スキーマ", "validation schema"

Workflow: workflows/schema.md

Example requests:
- "スキーマを作成"
- "Define schema for character"

Actions:
1. Create JSON Schema
2. Register in config
3. Test validation

Catalog Operations

Keywords: "catalog", "palette", "カタログ", "パレット", "enum"

Workflow: workflows/catalog.md

Example requests:
- "カラーパレットを定義"
- "Create profession catalog"

Actions:
1. Create catalog YAML
2. Register in config
3. Reference in schemas
4. Validate usage

Template Operations

Keywords: "template", "テンプレート", "generate from template"

Workflow: workflows/template.md

Example requests:
- "テンプレートから作成"
- "Use character template"

Actions:
1. Load template
2. Collect variable values
3. Substitute variables
4. Generate document
5. Validate output

Execution Flow

Step 1: Intent Analysis

Parse user request and identify:
- Primary operation (build, validate, analyze, etc.)
- Target (whole project, specific directory, specific file)
- Options (fix, verbose, output path, etc.)

Step 2: Load Centralized Rules

Always reference rules from reference/:
- Validation: reference/validation-rules.md
- Lint: reference/lint-rules.md
- Layers: reference/layer-structure.md
- Tokens: reference/token-optimization.md
- Schemas: reference/frontmatter-schemas.md
- Authoring: reference/authoring-reference.md
- Examples: reference/examples.md

Step 3: Execute Workflow

Follow selected workflow from workflows/:
- Load workflow markdown
- Execute steps in order
- Use allowed tools (Read, Write, Edit, Glob, Grep, Bash)
- Apply rules from reference/

Step 4: Report Results

Provide clear, actionable feedback:
- Success/failure status
- Issues found (if any)
- Actions taken
- Next steps (if applicable)

Multi-Operation Requests

If user requests multiple operations, execute in logical order:

"ビルドして検証" (Build and validate):
1. Validate first (catch errors before build)
2. If validation passes, build
3. Report both results

"レビューして修正" (Review and fix):
1. Review document
2. Report issues
3. Apply fixes (if user confirms)
4. Re-review

"作成してビルド" (Create and build):
1. Create document
2. Validate new document
3. Build entire project
4. Report token count

Note: For complex multi-operation workflows, recommend using the orchestrator agent (see .claude/agents/shirokuma-md/AGENT.md)

Error Handling

Missing config:

❌ ERROR: shirokuma-md.config.yaml not found

Create config file in project root or use:
  --config path/to/config.yaml

Invalid operation:

❌ ERROR: Unknown operation: "{{operation}}"

Available operations:
  build, validate, analyze, lint,
  create, review, fix,
  architect, schema, catalog, template

Command not found:

❌ ERROR: shirokuma-md command not found

Install shirokuma-md:
  npm install -g @shirokuma-library/shirokuma-md

Or use npx:
  npx shirokuma-md <command>

CLI Integration

This skill can invoke actual shirokuma-md CLI commands:

# Check command availability
which shirokuma-md

# Execute build
shirokuma-md build

# Execute with options
shirokuma-md validate --severity error
shirokuma-md lint --fix
shirokuma-md analyze --graph --output deps.mermaid

Important: Always verify shirokuma-md command exists before invoking.

Integration with Orchestrator Agent

For complex, multi-step workflows:
- Use this skill: For single, focused operations
- Use orchestrator agent: For complex workflows with multiple steps, error recovery, and optimization

Example: "ビルドして検証してエラー修正"
- This skill: Can execute, but limited
- Orchestrator agent: Better choice - handles retry logic, error recovery, optimization

See: .claude/agents/shirokuma-md/AGENT.md

Notes

• Single source of truth: All rules in reference/
• No duplication: Rules referenced, not copied
• Consistent: Same rules for all operations
• Maintainable: Update once, applies everywhere
• Discoverable: All workflows documented
• Extensible: Add new workflows without changing core
• CLI-first: Prefers actual CLI when available
• Tool usage: Uses Read/Write/Edit/Glob/Grep/Bash as needed

Quick Reference