How do I install the Documentation Principles skill?

Run npx skillmds@latest add tomevault-io/documentation-principles in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.

Is Documentation Principles safe to use?

This skill has not completed SkillMD's automated safety review yet. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.

Which AI agents work with Documentation Principles?

This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.

Is Documentation Principles free to use?

Yes. Installing skills from SkillMD is free, and the skill stays under its author's original license.

Who published Documentation Principles?

tomevault-io (@tomevault-io) published this skill. Their other Agent Skills are listed on their SkillMD profile.

Documentation Principles by tomevault-io

Name: Documentation Principles
Author: tomevault-io

Documentation Principles

14 documentation principles for Japanese quality, conciseness, visual expression, technical documents, and project-specific rules. Applied by document review, fix, and writing agents. Use when this capability is needed.

tomevault-io 825cad6 2 files · 3.8 KB Updated Sep 17, 2026

File contents

14 Documentation Principles

Japanese Quality (1-3)

Use Natural Japanese - Avoid programming jargon
- NG: スローする, リターンする, フェッチする
- OK: 発生させる, 返す, 取得する
Follow Textlint Rules - Avoid redundant expressions
- NG: 〜を行う, 〜することができる
- OK: 〜する, 〜できる
Avoid Sentence-Ending Colons - Do not end sentences with : or ：
- NG: 以下のシナリオで発生する可能性があります：
- OK: 以下のシナリオで発生します。

Conciseness (4-8)

Eliminate Redundant Explanations - If process flow is clear, results are self-evident
- Remove: この仕組みにより〜, これによって〜
Keep Overview Sections Concise - State document purpose only (1-3 sentences)
- Details belong in specific sections
Avoid Outcome/Benefit Statements - If feature description is clear, benefits are self-evident
- Remove: 〜できます, 〜を削減, 〜が可能になり
Avoid Abstract Verbs - Specify concrete changes
- NG: 改善しました, 最適化しました
- OK: 接続タイムアウト時に3回まで自動リトライします
Explain Reasons Concisely - Provide technical justification in 2-3 sentences

Visual Expression (9)

Use Emphasis Sparingly
- Headers: H2→H3→H4 only
- Bold: 1 per sentence maximum

Technical Documentation (10-12)

Avoid Implementation Details - Describe what features do, not how
- NG: LoanRepository.ExtendLoanPeriod() を呼び出して貸出期間を延長します
- OK: 貸出期間を延長します
Explicitly State Conditional Behavior - Clearly state when behavior varies
- Avoid: always, must (unless truly unconditional)

Distinguish Admonitions - Use correct types:

Type	Purpose
`:::info`	Document scope, references
`:::note`	Design rationale, technical reasons
`:::tip`	Best practices, recommendations
`:::warning`	Document status (TODO, WIP)
`:::caution`	Operation warnings
`:::danger`	Critical risks, irreversible actions

Project-Specific (13-14)

Match UI Terminology - Use exact terms from KNOWLEDGE
- Check KNOWLEDGE for project-specific terms
Standardize Document Structure - Use consistent structure
- Overview → Process Flow → Error Cases

Severity Levels

Level	Violation Type
Critical	Principles 1-3 (Japanese Quality)
High	Principles 4-8, 10-12 (Conciseness, Technical)
Medium	Principles 9, 13-14 (Visual, Project-specific)

Converted and distributed by TomeVault — claim your Tome and manage your conversions.

---name: documentation-principlesdescription: 14 documentation principles for Japanese quality, conciseness, visual expression, technical documents, and project-specific rules. Applied by document review, fix, and writing agents. Use when this capability is needed.---## 14 Documentation Principles### Japanese Quality (1-3)1. **Use Natural Japanese** - Avoid programming jargon - NG: スローする, リターンする, フェッチする - OK: 発生させる, 返す, 取得する2. **Follow Textlint Rules** - Avoid redundant expressions - NG: 〜を行う, 〜することができる - OK: 〜する, 〜できる3. **Avoid Sentence-Ending Colons** - Do not end sentences with `:` or `：` - NG: 以下のシナリオで発生する可能性があります： - OK: 以下のシナリオで発生します。### Conciseness (4-8)4. **Eliminate Redundant Explanations** - If process flow is clear, results are self-evident - Remove: この仕組みにより〜, これによって〜5. **Keep Overview Sections Concise** - State document purpose only (1-3 sentences) - Details belong in specific sections6. **Avoid Outcome/Benefit Statements** - If feature description is clear, benefits are self-evident - Remove: 〜できます, 〜を削減, 〜が可能になり7. **Avoid Abstract Verbs** - Specify concrete changes - NG: 改善しました, 最適化しました - OK: 接続タイムアウト時に3回まで自動リトライします8. **Explain Reasons Concisely** - Provide technical justification in 2-3 sentences### Visual Expression (9)9. **Use Emphasis Sparingly** - Headers: H2→H3→H4 only - Bold: 1 per sentence maximum### Technical Documentation (10-12)10. **Avoid Implementation Details** - Describe what features do, not how - NG: LoanRepository.ExtendLoanPeriod() を呼び出して貸出期間を延長します - OK: 貸出期間を延長します11. **Explicitly State Conditional Behavior** - Clearly state when behavior varies - Avoid: always, must (unless truly unconditional)12. **Distinguish Admonitions** - Use correct types: | Type | Purpose | |------|---------| | `:::info` | Document scope, references | | `:::note` | Design rationale, technical reasons | | `:::tip` | Best practices, recommendations | | `:::warning` | Document status (TODO, WIP) | | `:::caution` | Operation warnings | | `:::danger` | Critical risks, irreversible actions |### Project-Specific (13-14)13. **Match UI Terminology** - Use exact terms from KNOWLEDGE - Check KNOWLEDGE for project-specific terms14. **Standardize Document Structure** - Use consistent structure - Overview → Process Flow → Error Cases## Severity Levels| Level | Violation Type ||-------|----------------|| Critical | Principles 1-3 (Japanese Quality) || High | Principles 4-8, 10-12 (Conciseness, Technical) || Medium | Principles 9, 13-14 (Visual, Project-specific) |---> Converted and distributed by [TomeVault](https://tomevault.io/claim/sato-dev1234) — claim your Tome and manage your conversions.

Frequently asked questions