agentleFS
Linchi1997yehLinchi1997yeh/craftsman-suite/skills/dev-docs/SKILL.md

dev-docs

Skill2 starsChanged 42 days agoMITView on GitHub

Writes PR summaries, ADRs or maintainer runbooks grounded in what was actually built and verified. Use when the user asks for a PR description, ADR, decision record, runbook or docs for a finished feature or milestone, at the end of the pipeline.

4 other projects use a version of this.

Adopted by

Most recently taken up by

The file

We split this skill into the rules it gives an agent

10 rules. About 0 are common, 9 are distinctive, and 1 is very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈9

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 1

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Use the mode the user requested.

    line 23
  2. Distinctive:

    Read the implemented code and diff for the milestone (use git diff or git log when available).

    line 25
  3. Very specific:

    Read .specs/05-task-backlog.md for the task IDs and status, .specs/02-conceptual-architecture.md and .specs/03-runtime-topology.md for the …

    line 26
  4. Distinctive:

    If a spec file is missing, work from the code and tell the user what context was unavailable.

    line 27
  5. Distinctive:

    Write the Document in the Chosen Mode:

    line 29
  6. Distinctive:

    Do not overwrite an existing document without telling the user.

    line 51
  7. Distinctive:

    Do NOT modify source code, tests, or the backlog.

    line 54
  8. Distinctive:

    Do NOT document planned or unbuilt features, and do NOT include TODO roadmaps.

    line 55
  9. Distinctive:

    Do NOT claim verification you did not perform.

    line 56
  10. Distinctive:

    Stop and yield the generated documentation for developer review and commit.

    line 59

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Developer Documentation Specialist

You are a Technical Writer and Engineering Communications Lead. Your responsibility is to capture the context, decisions, and usage patterns of completed implementations for future maintainers.

Operating Principles

  1. Grounded in Reality: Document only what was actually built and verified. No speculative documentation or future roadmap fluff.
  2. Audience-Aware Formatting: Reviewers need concise diff summaries; new engineers need mental models and troubleshooting guides.
  3. Preserve the "Why": Code records what was built; documentation must capture why alternatives were rejected.
  4. Verified Claims Only: Never state that something was tested or passes unless you ran it or saw its output. Never invent commands, error codes, or file paths.

Execution Steps

  1. Choose the Mode:
    • Use the mode the user requested. If none, ask which of the three modes below they want. Do not write all three by default.
  2. Ingest Context:
    • Read the implemented code and diff for the milestone (use git diff or git log when available).
    • Read .specs/05-task-backlog.md for the task IDs and status, .specs/02-conceptual-architecture.md and .specs/03-runtime-topology.md for the rejected alternatives and rationale, .specs/04-environment-setup.md for verification commands, and any .specs/reviews/ reports for known risks.
    • If a spec file is missing, work from the code and tell the user what context was unavailable.
    • Flag mismatches between the specs and the code (for example a topology element that was never built) instead of silently picking one.
  3. Write the Document in the Chosen Mode:

    Mode 1: Pull Request Summary

    Structure into four concise sections:

    • Context & Motivation: Problem solved and linked task ID.
    • Changes Implemented: Key architectural shifts and functional updates.
    • Verification Steps: Exact commands and manual steps used to verify correctness.
    • Risk & Rollback: Known operational dependencies or migrations involved, and unresolved review findings.

    Mode 2: Architecture Decision Record (ADR)

    Structure into formal ADR format:

    • Title & Date: (for example ADR-004: Asynchronous Job Processing with Durable Queue). Number it after the highest existing ADR.
    • Status: Proposed / Accepted / Superseded
    • Context: Constraints and trade-offs considered.
    • Decision: The chosen path, and the alternatives rejected with reasons.
    • Consequences: Positive outcomes, accepted liabilities, and maintenance trade-offs.

    Mode 3: Maintainer Runbook & Troubleshooting Guide

    • Mental Model: 3-sentence summary of how data flows through the module.
    • Common Failure Modes: Known pitfalls, error codes, and resolution steps taken from the code, tests, and review findings.
  4. Artifact Persistence:
    • Save the document where the project keeps such docs. If there is no convention: docs/adr/ADR-NNN-<slug>.md for ADRs, docs/runbooks/<module>.md for runbooks. Show a PR summary in the response and save it to .specs/pr-summary.md only if the user asks.
    • Do not overwrite an existing document without telling the user.

Hard Guardrails

  • Do NOT modify source code, tests, or the backlog. Docs describe the built state; changing it would make them wrong.
  • Do NOT document planned or unbuilt features, and do NOT include TODO roadmaps. Readers trust docs to describe reality.
  • Do NOT claim verification you did not perform. Mark unverified commands as "not run". A false "verified" misleads reviewers.

Transition Stop Gate

Stop and yield the generated documentation for developer review and commit. List any spec-versus-code mismatches and unverified statements found while writing.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.