docs-config-authoring

name	docs-config-authoring
description	Write or edit non-code documentation and configuration files: Markdown, YAML, JSON, TOML, INI, agent files, README, CONTRIBUTING, workflow docs, config schemas, .env templates. USE FOR: README, CONTRIBUTING, workflow docs, config files, agent definitions, non-code documentation. DO NOT USE FOR: in-code documentation like JSDoc/docstrings (use code-documentation), code review (use code-review), implementation (use impl-* skills).
argument-hint	Point me at a doc or config file and I will write or improve it.
phase	6
phase-family	documentation

Docs and Config Authoring

When to Use

• The target files are Markdown or configuration, not source code.
• Agent files, repo guidance, workflow docs, YAML, JSON, TOML, or INI need clear technical edits.
• README, CONTRIBUTING, or other non-code documentation needs to be written or improved.
• Config schemas, .env templates, or .github/ files need authoring.

When Not to Use

• In-code documentation like JSDoc, docstrings, or XML docs — use code-documentation.
• Code review or quality feedback — use code-review.
• Implementation or refactoring of source code — use the appropriate impl-* skill.

Scope and Boundaries

In Scope

• *.md
• *.yaml / *.yml
• *.json
• *.toml
• *.ini
• .github/**
• .vscode/**
• agent-progress/**
• Agent definition files (*.agent.md)
• Other clearly non-code docs/config files requested by the user

Out of Scope (refuse and redirect)

• Source code files: *.ts, *.tsx, *.js, *.jsx, *.py, *.cs, *.go, *.java, *.rs, *.cpp, *.c, *.h, *.hpp, *.swift, *.kt, *.php, *.rb, *.scala
• Binary and generated artifacts: images, compiled files, lockfiles generated by tooling, build outputs, minified bundles

When the request is out of scope, explain the boundary and redirect to the right skill.

Relationship to code-documentation

• code-documentation: in-code documentation comments and API reference for source code symbols.
• docs-config-authoring: non-code docs, config, and agent file authoring and edits.

Do not overlap responsibilities. If the user asks for both, split work by scope.

Procedure

1. Confirm file type and scope — Verify the target is a non-code file before editing.
2. Preserve required structure — Keep YAML frontmatter keys, heading hierarchy, schema-sensitive layout, and any required fields intact.
3. Make minimal edits — Satisfy the request without unnecessary rewriting.
4. Keep terminology consistent — Match wording and conventions used in nearby files.
5. Validate syntax — Check formatting correctness for syntax-sensitive files (.agent.md, YAML, JSON, TOML).
6. Refuse out-of-scope requests — If the request includes code-file edits, refuse that part and propose a redirect.
7. Produce the output contract — Write the Documentation Completion Report (see Output Contract below).

Writing Style Rules

• Use clear and direct language.
• Keep sentences short when possible.
• Use precise terms when they improve understanding.
• Avoid inflated wording, filler, and stylistic flourish.
• Preserve intended meaning when rewriting.
• Prefer concrete nouns and active voice.
• Keep headings and lists scannable.

Priority order when these conflict:

1. Correctness — Technical statements must be accurate.
2. Clarity — The reader must understand with minimal effort.
3. Brevity — Remove unnecessary words, but not at the cost of correctness or clarity.

Writing Patterns by File Type

Markdown (README, CONTRIBUTING, guides)

• Use ATX headings (#, ##, ###).
• Keep paragraphs short (3-5 sentences max).
• Use lists for sequential steps or enumerated items.
• Use fenced code blocks with language identifiers for examples.
• Add a table of contents for documents longer than three sections.

YAML / JSON / TOML / INI

• Add inline comments explaining non-obvious values.
• Group related keys and separate groups with blank lines.
• Use consistent quoting and indentation.
• Provide example values in templates (.env.example, config templates).

Agent Files (.agent.md)

• Keep frontmatter keys in the order the schema expects.
• Write the description as a concise paragraph covering what, when, and when-not.
• Body sections should follow the agent's established structure.

Quality Checklist

Before finishing, verify:

• Edits are in allowed non-code scope
• Technical statements are correct
• Wording is clear and concise
• No unnecessary verbosity
• Existing structure and conventions are preserved
• No source code files were modified
• Syntax-sensitive files validate correctly

Output Contract

All skills in the documentation phase family use this identical report. Present it in chat before logging progress.

### Documentation Completion Report

**Summary**
[What was documented: symbols, modules, or pages.]

**Changes**
| Path | Purpose |
|------|---------|
| `path/to/file` | [doc added/updated] |

**Public API / exported symbols**
- [List key symbols documented, or topics/sections covered for non-code docs] or **N/A**

**Verification**
- [build or doc check if any] — [result] or **N/A**

**Suggested next step**
[Typically code-review or human review.]

Guardrails

• Do not edit source code in this mode.
• Keep correctness first, clarity second, brevity third.
• Use code-documentation for in-code documentation comments.
• When refusing out-of-scope requests, provide a short refusal with a one-line reason and a redirect suggestion to the appropriate skill.