Smithery is now a part of Arcade.dev! Read more in our announcement here
This skill should be used when writing, reviewing, or refactoring documentation that will be consumed as AI context...
Documentation consumed by AI has fundamentally different requirements than human-facing docs. LLMs process documentation at passage-level (phrase chunks), build mental models from heading structure, and are confused by meta-commentary, synonym variation, and narrative prose.
This skill provides:
When to use: Writing, reviewing, or refactoring any documentation intended for AI consumption (setup guides, architecture docs, API references, workflow guides, configuration specs).
Completeness: Every critical piece of information must be present. No assumptions about reader background.
Efficiency: Only essential information. No explanations of design choices, meta-commentary, or justifications.
Zero Fluff: No meta-commentary ("Updated!", "We added..."), conversational language ("You'll want to..."), transition phrases ("As mentioned..."), or redundant restatements.
Pick the format that best serves the content:
Configuration/Relationships: Use YAML/code blocks, not prose
**Fallback chain:**
- ja → en
- ko → en
- zh-tw → zh-cn → en
Procedures: Numbered steps with inputs/outputs
1. Load recipe with eager-loaded associations
2. Instantiate RecipeTranslator
3. For each language, call translator.translate_recipe()
4. Apply translations via apply_translations()
Behavior: Code examples only when they show edge cases/counterintuitive behavior
I18n.with_locale(:ja) { recipe.name } # Falls back to 'en' if translation missing
Before committing:
python3 scripts/fluff-detector.py your-doc.md
Detector catches:
Meta-commentary: Remove entirely. Just describe current state.
Conversational language: Convert to imperative structure.
Hierarchy violations: Insert missing heading level.
## Configuration → #### Translation Tables## Configuration → ### Translation System → #### Translation TablesSynonym variation: Replace all with single consistent term.
Redundant restatement: Keep only the version that's clearest.
Examples should reveal non-obvious behavior. If example just restates description, remove it.
✅ Include: Shows edge case/counterintuitive behavior
# Fallback behavior when translation missing
I18n.with_locale(:ja) { recipe.name } # Returns English translation
❌ Exclude: Restates description
# To read a translation, use I18n.with_locale
I18n.with_locale(:ja) { recipe.name }
See references/style-guide.md for:
Automated checker for common violations.
Usage:
# Check single file
python3 scripts/fluff-detector.py documentation.md
# Check multiple files
python3 scripts/fluff-detector.py doc1.md doc2.md doc3.md
Output: Lists line numbers with violation type and content snippet
Catches:
Before:
Mobility is configured with several important plugins. The fallbacks plugin
handles missing translations gracefully by falling back to the fallback locale.
We've configured the fallback chain so that Japanese falls back to English.
After:
**Plugins:** fallbacks, reader, writer, query, cache, locale_accessors
**Fallback chain:**
- ja → en
Before:
When a recipe is created, the system triggers a background job called
TranslateRecipeJob. This job instantiates the RecipeTranslator service and
then calls the translate method for each language. Finally, it updates the
recipe's translations_completed flag.
After:
**Trigger:** Recipe creation (background job)
**Process:**
1. Instantiate RecipeTranslator
2. For each language [ja, ko, zh-tw, zh-cn, es, fr]:
- Call translator.translate_recipe(recipe, lang)
- Apply translations via apply_translations()
3. Set recipe.translations_completed = true
Before:
The system uses the Mobility gem (also known as the i18n library or translation system)
to manage translations (also called locales or language variants).
After:
Mobility manages translations across 6 languages.
python3 scripts/fluff-detector.py file.mdSee provided before/after examples in this skill documentation for patterns:
