writing-docs

Match your task to the correct reference file first: prose-style.md for general writing, markdown.md for formatting, doc-structure.md for document organization. Read the file before writing rather than working from memory, then apply rules only to new or modified content.

Run markdownlint with the project config at .github/linters/.markdown-lint.yml, then run textlint with the terminology rule on changed files. Also verify all links work, tables are aligned, and cross-reference anchors still match after any heading renames.

Diataxis splits documentation into four types: how-to guides, explanations, reference docs, and tutorials. Each type has its own directory, voice, and structure rules, and you should not mix types such as embedding theory inside a practical how-to guide.

Almost every rule applies to new and modified content only. When editing an existing document, apply rules to the lines you add or rewrite without reflowing surrounding prose, which avoids large noisy diffs unrelated to your task.

Read the object entry in docs/envgene-objects.md and the matching JSON Schema under schemas/ before writing any example. Include all required fields, never invent fields, and validate the example against the schema before shipping it.

Do not use it for pure code changes, config-value edits, debugging, linter or CI setup, or answering factual questions about identifiers. The skill targets authoring and polishing prose and Markdown, not code work.