Skip to content
Back to search

developer-documentation-skill

A standalone AI skill for creating accurate, usable developer documentation.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/natebjones-projects--developer-documentation-skill/badge.svg)](/listings/natebjones-projects--developer-documentation-skill)

HTML

<a href="/listings/natebjones-projects--developer-documentation-skill"><img src="/api/listings/natebjones-projects--developer-documentation-skill/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Keep the complete `developer-documentation` directory together. Place it in the skill directory used by your AI host.

Common locations are:

| Host and scope | Destination | |---|---| | Codex project | `.agents/skills/developer-documentation` | | Codex user | `~/.agents/skills/developer-documentation` | | Claude Code project | `.claude/skills/developer-documentation` | | Claude Code user | `~/.claude/skills/developer-documentation` |

Do not overwrite an existing directory with the same name until you confirm that it is obsolete. Restart the AI host if the newly installed skill does not appear.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

SKILL.md · Manifest · 114 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. ---
  2. name: developer-documentation
  3. description: Create, restructure, or maintain accurate developer documentation for software, tools, automations, packages, APIs, SDKs, CLIs, installations, migrations, operations, and troubleshooting. Use when the user asks for a README, overview, quickstart, tutorial, how-to guide, concept page, reference, API or CLI documentation, installation guide, runbook, migration guide, release notes, troubleshooting page, or a complete documentation set.
  4. metadata:
  5. version: "1.0.0"
  6. ---
  7. # Developer documentation
  8. Create documentation that helps the intended reader understand or use the real system without needing its author beside them.
  9. ## Establish the documentation contract
  10. Before writing:
  11. 1. Read the user's request and the instructions in the target project.
  12. 2. Inspect the current code, tests, schemas, configuration, command help, interfaces, and existing documentation that define the behavior.
  13. 3. Identify the reader, the job they need to complete, the documentation location, and the required output format.
  14. 4. Separate current behavior from proposed behavior. Do not document a proposal as an implemented feature.
  15. 5. Preserve unrelated documentation and user changes.
  16. Use current product behavior as the source for product claims. Use official primary documentation for a dependency, platform, or standard that can change. If a material claim cannot be verified, label the limitation instead of filling the gap.
  17. ## Choose the right document type
  18. Create only the pages the reader needs. Do not turn every request into a full documentation site.
  19. Use these common forms:
  20. - An overview explains what the system is, who it is for, and where to start.
  21. - A quickstart gets a prepared reader to the first useful result through the shortest supported path.
  22. - A tutorial teaches by guiding the reader through a complete learning sequence.
  23. - A how-to guide helps an informed reader complete one goal.
  24. - A concept page explains how or why the system works.
  25. - A reference page states the exact interface, fields, commands, defaults, constraints, and errors.
  26. - A troubleshooting page starts with observable symptoms and gives verified ways to diagnose and resolve them.
  27. - An operations runbook gives an operator the prerequisites, safe procedure, checks, rollback, and escalation path for a recurring operation.
  28. - A migration guide explains the starting state, destination state, compatibility limits, ordered changes, verification, and rollback.
  29. - Release notes record user-visible changes, dates or versions, compatibility effects, and required action.
  30. Read [documentation types](references/documentation-types.md) when the request needs several pages, the correct form is unclear, or the information architecture needs to change.
  31. ## Build the documentation set
  32. For a multi-page set:
  33. 1. Choose one entry page.
  34. 2. Give each page one primary reader job.
  35. 3. Put the shortest useful path near the entry point.
  36. 4. Separate learning, task, explanation, and exact reference content when combining them makes the page hard to scan.
  37. 5. Link related pages with descriptive text.
  38. 6. Update or remove stale navigation when pages move.
  39. Do not copy the same procedure across several pages. Keep one maintained procedure and link to it from the other pages.
  40. ## Write procedures
  41. State prerequisites and permission requirements before the steps. Use numbered steps when order matters and bullets when it does not.
  42. For each step:
  43. 1. Start with the action.
  44. 2. State the tool, screen, directory, or environment before the action when that context matters.
  45. 3. Put one main action in each step.
  46. 4. Explain placeholders immediately after the command or example that uses them.
  47. 5. State the expected result when it helps the reader continue or verify success.
  48. 6. Mark an optional step with `Optional:` at the start.
  49. Prefer one supported path. Add alternatives only when different readers genuinely need them.
  50. ## Write reference documentation
  51. Organize reference content around the public interface, not the source file layout. Derive exact names, types, required fields, defaults, return values, errors, and compatibility notes from the implementation or an authoritative schema.
  52. For API, SDK, and CLI reference material:
  53. - distinguish required, optional, and mutually exclusive inputs;
  54. - show valid values and defaults;
  55. - explain side effects and permission requirements;
  56. - include representative success and failure output when it improves use;
  57. - link to the maintained source of exhaustive generated reference when one exists;
  58. - do not expose internal details that are not part of the supported contract.
  59. ## Create usable examples
  60. Make examples minimal, runnable, and safe to copy. Use placeholders for secrets and user-specific values. Introduce each code block with the purpose of the code. Add a language identifier to fenced code blocks when the language is known.
  61. Run commands and examples in a safe environment when possible. If an example cannot be run, say that it is illustrative. Never state that an installation, deployment, migration, or recovery procedure works unless the relevant boundary was tested.
  62. ## Apply the writing standard
  63. Project-specific terminology and style take priority. Otherwise, follow [the developer documentation writing standard](references/writing-standard.md).
  64. Use sentence-case headings, direct procedures, active voice, second person, American English, and one consistent term for each thing. Use code font for filenames, commands, flags, fields, methods, and text the reader must enter. Remove promotional claims, filler, fake certainty, and unexplained jargon.
  65. ## Verify the result
  66. Run the project's documentation build, linter, link checker, or test suite when one exists. Test documented commands and examples in proportion to the risk. For a rendered documentation site, inspect the rendered pages and navigation.
  67. For Markdown without an existing checker, run the bundled validator:
  68. ```bash
  69. python3 "/path/to/developer-documentation/scripts/validate_docs.py" PATH [PATH ...]
  70. ```
  71. The validator checks UTF-8 decoding, heading structure, fenced code blocks, local links, and image alternative text. Add `--check-fragments` when the documentation uses GitHub-style heading anchors.
  72. Add `--allow-empty-alt` only when each image with empty alternative text is confirmed to be decorative.
  73. The validator cannot prove technical accuracy, clarity, sentence case, or whether an example works. Check those against the real system.
  74. ## Finish the work
  75. Deliver the finished documentation at the requested path. Report what changed, how the documentation was checked, and any specific behavior that remains unverified. Do not report a draft as published or an untested procedure as working.
README.md · README · 117 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # Developer documentation skill
  2. `developer-documentation` is a standalone Agent Skills package for creating, restructuring, and maintaining accurate documentation for software, tools, automations, packages, APIs, SDKs, CLIs, installations, migrations, operations, and troubleshooting.
  3. The skill reads the working system before it writes. It separates implemented behavior from proposals, chooses the documentation form that matches the reader's job, and checks the finished Markdown with a bundled validator.
  4. ## Download the skill
  5. Download [developer-documentation-skill-1.0.1.zip](https://github.com/NateBJones-Projects/developer-documentation-skill/releases/download/v1.0.1/developer-documentation-skill-1.0.1.zip) from the latest release. The ZIP contains one complete `developer-documentation` directory that you can place in your AI host's skill directory.
  6. To follow the project or contribute changes, clone the repository:
  7. ```bash
  8. git clone https://github.com/NateBJones-Projects/developer-documentation-skill.git developer-documentation
  9. ```
  10. ## Supported documentation
  11. Use the skill for:
  12. - READMEs and overview pages;
  13. - quickstarts and tutorials;
  14. - how-to and concept guides;
  15. - API, SDK, CLI, and package references;
  16. - installation and migration guides;
  17. - operations runbooks;
  18. - release notes;
  19. - troubleshooting pages;
  20. - complete linked documentation sets.
  21. ## Package contents
  22. ```text
  23. developer-documentation/
  24. ├── ATTRIBUTION.md
  25. ├── LICENSE
  26. ├── README.md
  27. ├── SKILL.md
  28. ├── docs/
  29. │ ├── quickstart.md
  30. │ ├── reference.md
  31. │ └── troubleshooting.md
  32. ├── references/
  33. │ ├── documentation-types.md
  34. │ └── writing-standard.md
  35. ├── scripts/
  36. │ └── validate_docs.py
  37. └── tests/
  38. └── test_validate_docs.py
  39. ```
  40. `SKILL.md` contains the working method loaded by the AI host. The `docs` directory explains how to install, invoke, and operate the skill. The `references` directory contains detailed writing guidance. The validator and its tests are independent Python files with no third-party dependencies.
  41. ## Install the skill
  42. Keep the complete `developer-documentation` directory together. Place it in the skill directory used by your AI host.
  43. Common locations are:
  44. | Host and scope | Destination |
  45. |---|---|
  46. | Codex project | `.agents/skills/developer-documentation` |
  47. | Codex user | `~/.agents/skills/developer-documentation` |
  48. | Claude Code project | `.claude/skills/developer-documentation` |
  49. | Claude Code user | `~/.claude/skills/developer-documentation` |
  50. Do not overwrite an existing directory with the same name until you confirm that it is obsolete. Restart the AI host if the newly installed skill does not appear.
  51. ## Use the skill
  52. Invoke the skill by name and state the documentation result you need. For example:
  53. ```text
  54. $developer-documentation Create a quickstart and CLI reference for this project. Verify every documented command.
  55. ```
  56. The host can also select the skill automatically when the request clearly asks for developer documentation.
  57. For a complete first run, see the [quickstart](docs/quickstart.md).
  58. ## Validate Markdown
  59. Use the bundled validator when the project does not already have a documentation checker:
  60. ```bash
  61. python3 developer-documentation/scripts/validate_docs.py PATH [PATH ...]
  62. ```
  63. The validator checks UTF-8 decoding, heading structure, fenced code blocks, local links, and image alternative text. Add `--check-fragments` for GitHub-style heading targets. Add `--allow-empty-alt` only when every image with empty alternative text is confirmed to be decorative.
  64. The validator does not prove that technical claims are correct or that commands work. The skill checks those against the current code, interface, tests, or runtime.
  65. ## Requirements
  66. - Access to the code, interface, current behavior, or authoritative product files needed to verify the documentation.
  67. - Python 3 only when you use the validator or run its tests.
  68. - No third-party Python packages.
  69. ## License and attribution
  70. The documentation is licensed under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/). The validator, tests, and GitHub workflow are licensed under the MIT License. Both licenses permit commercial use.
  71. Portions of the documentation adapt the [Google developer documentation style guide](https://developers.google.com/style/). See [ATTRIBUTION.md](ATTRIBUTION.md) for the source, modification notice, and terms. This project is independent and is not endorsed by Google.
  72. See [LICENSE](LICENSE) for the file-by-file license boundary.
  73. ## Test the package
  74. From the directory that contains `developer-documentation`, run:
  75. ```bash
  76. python3 -m unittest discover \
  77. -s developer-documentation/tests \
  78. -p "test_*.py"
  79. ```
  80. For the full interface and validation behavior, see the [skill reference](docs/reference.md). For common failures, see [troubleshooting](docs/troubleshooting.md).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.