Skills documentation-and-adrs
📦

documentation-and-adrs

Content revision r2 Safe ⚙️ External commands

Document Decisions and Architecture Clearly

Teams lose context when important technical decisions remain in chat, code comments, or individual memory. This skill turns architectural reasoning, API guidance, project instructions, and release changes into structured documentation.

Supports: Claude Codex Code(CC)
🥉 78 Bronze

Install with my Agent

Copy this request to your Agent. It includes the canonical Skill page and manifest.

Agent request
Review the Skillstore skill "documentation-and-adrs" from https://skillstore.io/skills/addyosmani-documentation-and-adrs.md and its manifest at https://skillstore.io/api/skills/addyosmani-documentation-and-adrs/manifest. Verify the artifact. You may proceed after verification, subject to the environment's own policy.

Your Agent should still show its plan and request any confirmation required by the security policy.

Agent-readable resources

Use these links when an AI agent, crawler, or script needs clean context instead of reading the full page.

Markdown detail GET /skills/addyosmani-documentation-and-adrs.md Signed manifest GET /api/skills/addyosmani-documentation-and-adrs/manifest Signed lockfile GET /api/skills/addyosmani-documentation-and-adrs/lockfile

Test it

Using "documentation-and-adrs". We chose PostgreSQL over SQLite and MongoDB for a multi-user task application.

Expected outcome:

An ADR outline with status, context, relational data requirements, alternatives considered, the PostgreSQL decision, and operational consequences.

Using "documentation-and-adrs". Document a task creation endpoint that requires a title and returns an identifier.

Expected outcome:

API reference guidance covering the request fields, validation errors, authentication expectations, response details, and a short usage example.

Using "documentation-and-adrs". Create onboarding documentation for a project with a development server and test suite.

Expected outcome:

  • A README structure covering project purpose, setup, commands, architecture, and contribution practices.
  • A verification checklist for setup instructions, API documentation, known gotchas, and current agent rules.

Security Audit

Safe
v2 • 9/19/2026 Open versioned report

All 28 external-command detections are Markdown examples or inline command references in SKILL.md, not executable behavior. The environment-file and system-reconnaissance detections also point to documentation examples, and no prompt injection or data-exfiltration intent was found.

1
Files scanned
289
Lines analyzed
0
Review items
0
False positives ignored

Risk Factors

⚙️ External commands (28)
SKILL.md:38 SKILL.md:40 SKILL.md:41 SKILL.md:48 SKILL.md:50-91 SKILL.md:91-95 SKILL.md:95-97 SKILL.md:97-108 SKILL.md:108-120 SKILL.md:120-124 SKILL.md:124-135 SKILL.md:135-139 SKILL.md:139-150 SKILL.md:150-158 SKILL.md:158-174 SKILL.md:174-178 SKILL.md:178-198 SKILL.md:198-204 SKILL.md:204-211 SKILL.md:211-212 SKILL.md:212-213 SKILL.md:213-218 SKILL.md:218-219 SKILL.md:219-220 SKILL.md:220-221 SKILL.md:221-229 SKILL.md:229-235 SKILL.md:235-248
No confirmed security findings were detected by the latest completed static and semantic audit. This does not prove the skill has no side effects.
Audited by: codex View Audit History →
Share & cite this report

Share the versioned assessment report, neutral badge, embed card, and citations. Skillstore reports evidence without deciding whether this Skill is safe.

Open versioned report
Security Assessment

Copy report link

https://skillstore.io/skills/addyosmani-documentation-and-adrs/audits/2?utm_source=security_passport&utm_medium=share&utm_campaign=versioned_report

Markdown badge

[![Skillstore security assessment](https://skillstore.io/badges/skills/addyosmani-documentation-and-adrs/security.svg)](https://skillstore.io/skills/addyosmani-documentation-and-adrs?utm_source=security_passport_badge)

HTML badge

<a href="https://skillstore.io/skills/addyosmani-documentation-and-adrs?utm_source=security_passport_badge"><img src="https://skillstore.io/badges/skills/addyosmani-documentation-and-adrs/security.svg" alt="Skillstore security assessment" loading="lazy"></a>

Embed card

<iframe src="https://skillstore.io/embed/skills/addyosmani-documentation-and-adrs.html" title="Skillstore Security Assessment" sandbox="allow-popups allow-popups-to-escape-sandbox" loading="lazy" referrerpolicy="no-referrer" width="420" height="180"></iframe>
Academic citations (APA · BibTeX · CFF)

APA citation

addyosmani. (2026). documentation-and-adrs security audit report (audit version 2) [Author version unspecified]. Skillstore. https://skillstore.io/skills/addyosmani-documentation-and-adrs/audits/2

BibTeX citation

@techreport{addyosmani-addyosmani-documentation-and-adrs-2026, author = {addyosmani}, title = {documentation-and-adrs security audit report (audit version 2)}, institution = {Skillstore}, year = {2026}, number = {2}, url = {https://skillstore.io/skills/addyosmani-documentation-and-adrs/audits/2}, note = {Author version unspecified} }

CITATION.cff

cff-version: 1.2.0 message: "If you use this Skill, cite its author and this versioned security audit report." title: "documentation-and-adrs security audit report (audit version 2)" version: "unspecified" type: report authors: - name: "addyosmani" date-released: "2026-09-19" url: "https://skillstore.io/skills/addyosmani-documentation-and-adrs/audits/2" identifiers: - type: other value: "skillstore:addyosmani-documentation-and-adrs:audit:2" description: "Skillstore immutable audit report identifier"

Skillstore Score

Why this score Evidence Confidence: High
55
Architecture
85
Maintainability
87
Content
67
Community
83
Spec Compliance

What You Can Build

Record an architecture decision

Create an ADR that compares options, explains trade-offs, records the selected approach, and preserves consequences for future maintainers.

Document a public API

Draft consistent API documentation covering inputs, outputs, errors, authentication expectations, and representative usage guidance.

Improve project onboarding

Build a practical README, changelog structure, and agent guidance so contributors can understand setup, architecture, conventions, and recent changes.

Try These Prompts

Draft a simple ADR 
Create a concise ADR for this decision: [decision]. Include context, selected approach, two alternatives, consequences, status, and date. Use clear headings.
Match repository conventions 
Review the repository context I provide and identify its ADR location, file format, numbering pattern, and headings. Then draft an ADR for [decision] that follows those conventions.
Document a public API 
Write documentation for this public API: [API details]. Cover parameters, return values, validation, authentication, errors, and one realistic example. State unknowns instead of inventing behavior.
Build a documentation system 
Design a documentation update for [project]. Propose ADRs for durable decisions, README sections for onboarding, API reference coverage, changelog entries, agent guidance, and a verification checklist. Preserve existing conventions and identify missing evidence.

Best Practices

  • Provide repository conventions and factual project context before requesting documentation.
  • Document the reasoning, constraints, alternatives, and consequences instead of restating implementation details.
  • Review every generated command, example, link, and security statement against the current project.

Avoid

  • Do not invent repository conventions, API behavior, commands, or architectural constraints.
  • Do not create duplicate ADR numbering schemes or replace established project formats without evidence.
  • Do not use documentation as a substitute for implementation, testing, access control, or operational validation.

Frequently Asked Questions

What does this skill create?
It creates ADRs, API documentation, README structures, changelog guidance, and documentation plans for human and AI contributors.
Can it find the correct ADR format?
Yes, when you provide repository context. It can identify existing locations, naming patterns, file formats, and section headings.
Does it write files automatically?
No. It produces documentation content and recommendations. The surrounding agent must review and apply file changes.
Can it validate API behavior?
No. It can organize supplied API facts, but it cannot test endpoints or confirm undocumented implementation behavior.
Who benefits most from this skill?
Engineering leads, API maintainers, open-source maintainers, developer experience teams, and agents working in unfamiliar repositories.
How should generated documentation be reviewed?
Check decisions, commands, links, examples, security claims, project conventions, and dates against the current repository before publishing.

Developer Details

Author

addyosmani

License

MIT

Skillstore revision

r2

Version notice

The author did not declare a version.

Repository

https://github.com/addyosmani/agent-skills/tree/c004a74784a08295d52749b04cda634125b9a581/skills/documentation-and-adrs

Ref

5d5054f8a23586f9b500fece1cb613a9dffc787b

Maintenance freshness

9/19/2026

Usage

2 downloads · 0 views

File structure

📄 SKILL.md