dev-technical-writing

Write ADRs, module specs, and smart-memory docs in Markdown with Mermaid diagrams.

3|3|Updated Apr 23, 2026
One-click install
npx skills add https://github.com/joaoguirunas/team-os --skill dev-technical-writing-joaoguirunas
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: dev-technical-writing
Source: https://github.com/joaoguirunas/team-os/tree/main/.claude/skills/dev-technical-writing
Command: npx skills add https://github.com/joaoguirunas/team-os --skill dev-technical-writing-joaoguirunas

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Software teams lose architectural context when decisions and module designs live only in chat or memory. This Skill standardizes how technical documentation is written so decisions, module contracts, and project knowledge stay versioned alongside the code. ## Core Features & Use Cases - ADR Templates: Produce Architecture Decision Records with status, context, consequences, and alternatives, stored under docs/decisions/ with date-based naming. - Module Specs: Document module responsibility, public interface, dependencies, and data flow in docs/modules/. - Smart Memory in Obsidian Format: Create frontmatter-tagged notes with wiki-style links for persistent project knowledge. - Mermaid Diagrams: Generate flowchart, sequence, ER, and state diagrams that version together with the repository. - Use Case: After choosing a new authentication approach, an Architect agent writes an ADR with a Mermaid sequence diagram, links it from the affected module spec, and records the decision in smart memory for future sessions. ## Quick Start Ask the agent to write an ADR documenting a recent architectural decision, including a Mermaid diagram and links to the affected module specs.

Frequently Asked Questions about dev-technical-writing

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I write an Architecture Decision Record in Markdown?▼

Create a file in docs/decisions/ named with the date and a slug, then follow the ADR template: title, date, status, context, decision, positive and negative consequences, and a table of rejected alternatives. Add a Mermaid diagram when the decision involves system structure.

What should a software module specification document include?▼

A module spec states the module's responsibility in one sentence, its owner, the public interface with typed signatures, dependencies in both directions, a Mermaid sequence diagram of the data flow, and links to relevant ADRs.

Can Mermaid diagrams be versioned in a Git repository?▼

Yes, Mermaid diagrams are plain text inside Markdown code fences, so they diff and version like any source file. This skill requires Mermaid instead of external images so diagrams stay in sync with the code.

What frontmatter is required for Obsidian smart-memory notes?▼

Each note needs title, type (overview, story, decision, schema, research, or task-log), agent, created and updated dates, tags, and related links. Internal links use the double-bracket wiki syntax with relative paths for Obsidian compatibility.

When should I use an ADR instead of a code comment?▼

Use an ADR for decisions with architectural impact, such as technology choices, data model changes, or cross-module contracts, where trade-offs and alternatives matter. Code comments suit local implementation details that do not affect other modules.