Load when creating or editing any Markdown file or documentation HTML, such as README, DEVELOPMENT, architecture docs, reference docs, SKILL.md and AGENTS.md, and when rewriting or reviewing one.
72%
Does it follow best practices?
Run evals on this skill
Adds up to 20 points to the overall score
Low
Low-risk findings worth noting
Fix and improve this skill with Tessl
tessl review fix ./.agents/skills/docs-writing/SKILL.mdProblems with a kendex-owned skill go through kendex report; check ownership in the file first.
After an authorized documentation rewrite changes kendex-owned inputs, use the repository refresh and verification route. Respect a launched lane's refresh restriction. Keep refresh with the existing owner: kendex uses its lock-record Actions workflow and rolling kendex/lock pull request; consumers with automatic refresh use their kendex-refresh Actions workflow and rolling kendex/refresh pull request. When no refresh workflow exists and the fleet is local, the overseer owns refresh in the base checkout. Keep the local-fleet full post-merge route. This local owner is not a hosted control VM. Confirm any other execution owner before adoption. A hosted consumer without a refresh workflow must confirm an authorized owner outside the control VM. The hosted control checkout receives committed outputs through sync-base after they merge.
Migrate this repository hand-written harness instructions only through an authorized instruction migration. Put rules used by one installed skill in that skill's named [skill-instructions] key in kendex.toml, or kendex-local.toml only for a source catalog. Put agent-specific rules in the named [agent-additional-instructions] key and command-specific rules in the named [command-instructions] key. Keep only rules every agent needs in AGENTS.md. Keep operator instructions in consumer docs. Preserve every still-required rule. Remove an empty source instruction file only after its replacement is checked.
A repository's internal design documentation holds what the code cannot show: the principle behind a design, the rule an agent could break without noticing, a decision with its reason, a convention that differs from a tool default, and a pointer to the canonical code. Everything else lives in the code, its comments, the tests and git history.
This skill governs repository markdown and documentation HTML. It states one writing standard, one repository layout, what each file type holds, and the finished example an author reads before writing one. Policy and operating documents also follow § Writing.
Do not hand-copy code-owned inventories or defaults. A reference may define a contract not declared elsewhere, or explain semantics beside a link to its declaration. A generated reference may show declared values. A claim that a checker enforces something names the checker.
| Instead of | Write |
|---|---|
| A value you set is never overwritten and one you deleted is never put back. | kendex does not overwrite a value you set, and does not restore a value you removed. |
| ## What you can count on | ## Features |
| Simply run the apply command and you are good to go. | Run kendex apply. |
| One place your whole setup finally lives, in harmony across every tool. | kendex installs packages into the directories each tool reads. |
| It is generally recommended that callers should probably check the result. | Check the result. |
This is the default layout for a repository with no established structure. A repository's existing structure wins: a rewrite keeps the locations and names it finds and does not move established documents onto this layout.
| Path | Reader | Holds | Required |
|---|---|---|---|
README.md | a person choosing or using it | the sections references/readme.md orders | yes |
AGENTS.md | every agent, at session start | what the repo is, the commands, the conventions every agent needs, and task routes to principle docs, directly or through named nested instructions | yes |
DEVELOPMENT.md | a maintainer | build, run, test and debug: only what the tooling does not show | where needed |
LICENSE | a person | the licence | yes |
CHANGELOG.md, changelog.d/ | a person reading a release | release notes | released packages |
<dir>/AGENTS.md | an agent working in that folder | the folder's commands, rules every agent there needs that no linked principle doc owns, and task triggers for the principle docs that govern it | where a folder has its own rules |
docs/architecture/<name>.md | an agent about to do the work the doc governs | one principle: the approach, why, the rules, one code example | where a principle exists |
docs/decisions/INDEX.md and <DECISION_ID>-<slug>.md (names and locations follow decider) | a reviewer or agent about to reverse a choice | decision records: the choice, why, the rejected option, when to revisit | where such choices exist |
docs/images/ | a reader of a README or doc | the screenshots and images those files show | when used |
docs/runbook.md | an operator | step-by-step procedures for a running system | operated systems |
.github/copilot-instructions.md | Copilot features that support repository instructions, including code review | repository instructions and the review pointer; bot-instructions owns the render | yes, written by kendex |
.github/instructions/*.instructions.md | Copilot features that support matching path instructions | path rules; bot-instructions owns the render and cloud-agent exclusion | yes, written by kendex |
.github/instructions/code-review.md | review agents following the generated pointer | shared review doctrine; bot-instructions owns the render, not a native Copilot instruction file | yes, written by kendex |
Nothing else lives under docs/. A software implementation plan, research report, measurement or handoff is tracker or tmp/ content (§ Plans and research). An assistant home's policy, memory and session records keep their owning locations and reading routes; when writing or rewriting those records, read references/assistant-home.md. Product content a repository ships to its users, such as a help site, legal pages or an adapter reference, stays and is named in that repository's AGENTS.md. A skill's reference docs stay in its references/.
AGENTS.md gives each principle doc a task trigger, or routes to a nested AGENTS.md that gives the local trigger: "Before writing a plugin: docs/architecture/plugins.md".AGENTS.md names the principle doc for its folder. Codex reads every AGENTS.md on the path to the working directory. Claude Code loads a nested AGENTS.md when it reads a file there. Copilot reads the nested file when it opens files there.AGENTS.md. Review and dev workflows find them by keyword with decisions search, and a code comment cites a decision ID only where that code carries out the choice.AGENTS.md.Each section says who reads the file, what it holds, and what it never carries. Each finished example under examples/ ends with a contrast drawn from a real failure and one sentence on why that failure fails the reader.
Before writing a file, find its type in this table, then read its section and its example. The first row whose path matches wins; * matches across /. Shape names the structural rules that apply to the type: order is the numbered section order, and value-table is the rule against a value table. The commit-guards md-type lane checks them.
| Path | Section | Example | Shape |
|---|---|---|---|
docs/decisions/*.md | § Decision records | decision.md | none |
docs/architecture/*.md | architecture.md | architecture-plugins.md | value-table |
docs/runbook.md | § Runbooks | runbook.md | none |
AGENTS.md | agents.md | root-agents.md | none |
*/AGENTS.md | agents.md | nested-agents-plugins.md | none |
SKILL.md, */SKILL.md, */workflows/*.md, agents/*.md, */agents/*.md | skill-files.md | skill-entry.md | none |
*/documentation/*.md | human-page.md | HIW-tasks.md | none |
*/references/*.md, */schemas/*.md, */patterns/*.md, CHECKS.md, */CHECKS.md | reference-docs.md | reference.md | none |
DEVELOPMENT.md, */DEVELOPMENT.md | development.md | development.md | none |
README.md, */README.md | readme.md | readme.md | order, value-table |
| none: the product content directory a repository names | human-page.md | human-page.md | none |
For an internal design claim, ask the questions below in order and stop at the first yes. First classify user help, operating steps, skill procedures and reference contracts by their file-type section.
Read by a reviewer or agent about to reverse a choice. The bar, the format and the workflows are the decider skill's; this skill ships no second format. A principle doc states the current actionable rule and cites the decision ID. It does not repeat the decision's reasons or alternatives. Example: examples/decision.md.
Read by an operator maintaining or recovering a running system. A procedure names the task and when to use it, the target environment, required access and tools, and approval for effects that change service or data. Put steps in execution order. Give each step its expected reading and the condition that permits the next step. Name the source of the reading, such as a status page, command result or log. An unavailable reading is unresolved, not success.
State when the operator stops, how to leave or restore the system, and who receives a failure with its evidence. Describe recovery only where the system's current operating contract supports it. Finish with the end-state check and cleanup of temporary access, files or changed settings; preserve evidence until its handoff is checked. Verify instructions against the current tools and operating contract. Link to declarations and tool help instead of copying their inventories or defaults.
Never: build and test instructions for package development, design rationale, incident history or a record of one run. Those facts keep their homes under § Layout and § Plans and research. Example: examples/runbook.md.
Read in a browser. An offline page a skill or repository ships beside its markdown, opening with no build step, under the rules of the equivalent markdown type, with local styles only and no framework or external asset. Inline SVG is available where a diagram shows a relationship more clearly than prose. Never: a page served from a web root or built by an application bundler; that is a product file.
CHANGELOG.md and changelog.d/The changelog-entries lane owns the shape, and its release-version rule, the commit-guards skill's CHECKS.md § Release versions, owns the version and the fragment section. Follow the repository's changelog.d/README.md.
AGENTS.md, CLAUDE.md, GEMINI.md and SKILL.md, and nothing else. The commit-guards md-type lane checks the shapes the route table names; every other rule is held by the owner's review of each rewrite.A software implementation plan, research report, measurement or handoff is not repository content. Write it under tmp/ and attach it to the tracker issue it serves. Research that is the evidence behind a constraint still in force is attached to that constraint's issue, verified readable, and the constraint links to it; every other research file is deleted when its work lands. An assistant home's sourced memory and live handoff follow their owning contracts, not this software-artifact rule.
md-reflow script rewrites a file to this format, and md-reflow --check names a file that departs from it.kendex.toml.A focused change edits the affected text and verifies each claim against its owning source. A focused change whose paragraph adds a fact first takes § One home per fact. Use code where code owns the claim. Preserve the actor, scope, exceptions, required order, dates, attribution, supersession and evidence status. An unread source leaves verification unresolved; it does not establish or erase the claim. Converting a document onto this convention, or restructuring it, follows workflows/rewrite.md at the scope asked for, one file, one folder or the repository; the workflow extracts what is unique, then writes each file in scope from a blank page. The scope names the files: a docs/ cleanup edits AGENTS.md only for the "Read when" lines of the docs it retains or deletes, and edits no SKILL.md; a rewrite of an AGENTS.md or SKILL.md body is a separate request the owner approves by naming the file. Both follow § Per file type and start from the example its table names for the file type.
vanillagreencom/kendex
3a2f84c
If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.