Skip to content
Skills Library
Programming · Writing

documentation-guidelines

/documentation-guidelines

Create, audit, or consolidate durable project documentation, including feature rules, contracts, workflows, and runbooks. Use when documentation is the main deliverable; routine code changes can update their owning docs directly.

Licence
Apache-2.0
Last repository change
01.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
5
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 01.10.2026, without references to retired models or APIs.

Licence

Apache-2.0, otwarta: można używać i zmieniać, z zachowaniem licencji i informacji o zmianach.

What it does and when to use it

Create, audit, or consolidate durable project documentation, including feature rules, contracts, workflows, and runbooks. Use when documentation is the main deliverable; routine code changes can update their owning docs directly.

Original author description

Create, audit, or consolidate durable project documentation, including feature rules, contracts, workflows, and runbooks. Use when documentation is the main deliverable; routine code changes can update their owning docs directly.

How it works

  1. Delegation
  2. Find the owner and evidence
  3. Change docs when durable meaning changes
  4. Write for discovery and maintenance
  5. Verify and report
Original SKILL.md headings · 44 lines, 499 words
SKILL.md preview
---
name: documentation-guidelines
description: Create, audit, or consolidate durable project documentation, including feature rules, contracts, workflows, and runbooks. Use when documentation is the main deliverable; routine code changes can update their owning docs directly.
---

# Documentation Guidelines

Capture durable meaning that code alone does not explain: business intent, ownership, invariants, permissions, contracts, and operational decisions. Let source and tests own implementation details and executable evidence.

## Delegation

Run in the main conversation by default. Delegation can increase usage: obtain explicit approval for the proposed agent count and scope before using subagents. Reuse that approval within its bounds; ask again before expanding the approved count or scope.

## Find the owner and evidence

Read the relevant documentation index and owner when present, then verify affected facts against source, tests, schemas, configuration, and runtime evidence. Follow links needed to understand the changed contract; stop when further reading no longer affects the result. Missing or stale documentation is a reason to inspect source, not a prerequisite that blocks work.

For the scope at hand, identify applicable actors, triggers, rules, state transitions, inputs/outputs, side effects, failure paths, ownership, and compatibility requirements. Omit irrelevant categories; record unresolved material facts without inventing them.

## Change docs when durable meaning changes

| Change | Documentation action |
|---|---|
| Internal refactor, formatting, or fix restoring documented behavior | Update only affected paths or evidence anchors, if any |
| User behavior, business rule, or workflow | Update its existing owner |
| API, schema, permissions, events, or compatibility | Update the contract and affected consumer mappings |
| Setup, migration, deployment, backup, or recovery | Update the owning runbook |
| Entity renamed, moved, or removed | Repair discovery routes and stale references |
| Duplicate or contradictory docs | Preserve valid facts in one owner, repair links, then remove stale copies within scope |

Avoid docs changes that merely record task activity. Keep transient plans, command logs, and CI output in the task, PR, or an existing evidence surface unless they represent a durable operating requirement.

## Write for discovery and maintenance

- Give each durable fact a clear owner. Consumers link to it and document only their own mapping or constraints.
- Follow the repository's layout. Add routers, registries, or metadata only when a real discovery or tooling need justifies their upkeep.
- Use concrete rules, stable searchable headings, examples, and a few source/test anchors. Prefer symbols and paths over brittle line numbers.
- Separate facts, recommendations, and unknowns. Remove generic tutorials, speculative requirements, copied implementation, and status metadata that will rot.
- Preserve historical records when they still serve an audit, migration, or operational purpose. Use Git history for superseded tracked content when sufficient.

Read [templates.md](references/templates.md) for the document type, [architecture.md](references/architecture.md) for multi-owner structure, or [audit-cleanup.md](references/audit-cleanup.md) for consolidation.

## Verify and report

Trace discovery from the existing entrypoint to the updated owner. Check links, identifiers, commands, evidence anchors, and any affected consumer contracts. Search for contradictory copies and old names. Run focused doc or generation validators plus applicable required gates; application tests are warranted only if the change affects executable behavior or their contract.

Report the durable facts changed, important removals or consolidations, verification, and remaining gaps.
Files in this package (5)
  • SKILL.md 4 KB
  • agents/openai.yaml 1 KB
  • references/architecture.md 4 KB
  • references/audit-cleanup.md 5 KB
  • references/templates.md 6 KB

Versions

The database has no other skills named documentation-guidelines.

Identical content appears in 1 other GitHub folders. We show one copy with the highest score.

Database snapshot: 13.11.2026 · package version 012c2a48afc4 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100documenting-projects
    Use when generating, improving, or auditing project documentation. Triggers: 'document this project', 'write docs', 'generate documentation', 'docs are outdated', 'need a README', 'create tutorials', 'API reference docs', 'doc audit', 'documentation review'. Standalone README:…
  • 100document
    Technical documentation expert for creating clear, comprehensive documentation including API docs (OpenAPI), ADRs, system architecture docs, developer guides, and runbooks. Use when creating or improving technical documentation.
  • 100rust-docs-guidelines
    Guidelines for writing Rust documentation. Use this when you want to write Rust documentation.
  • 100documentation
    Write and maintain technical documentation. Trigger with "write docs for", "document this", "create a README", "write a runbook", "onboarding guide", or when the user needs help with any form of technical writing — API docs, architecture docs, or operational runbooks.
  • 100documentation-updater
    Update all project documentation including implementation docs, user guides, API docs, and architecture diagrams. Use when finalizing features to ensure comprehensive documentation.
  • 100docs-sync
    Use when the user asks to update documentation after code or configuration changes, audit documentation drift, or prepare README, API, runbook, or release docs. Changes only affected documentation and verifies examples, links, contracts, and operational steps against source code.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.