AGENT SKILL

technical-writing

Create architectural decision records (ADRs), system documentation, API documentation, and operational runbooks. Use when capturing design decisions, documenting system architecture, creating API references, or writing operational procedures.

License 许可
MIT
最近更新
2026-11-01
Stars
★ 3
Forks
1

01 前言 Front Matter

name
technical-writing
description
Create architectural decision records (ADRs), system documentation, API documentation, and operational runbooks. Use when capturing design decisions, documenting system architecture, creating API references, or writing operational procedures.

02 资源文件 2

03 SKILL.md 正文

Documentation Creation

A development skill for creating and maintaining technical documentation that preserves knowledge, enables informed decision-making, and supports system operations. This skill provides templates and patterns for common documentation needs.

When to Use

  • Recording architectural or design decisions with context and rationale
  • Documenting system architecture for new team members or stakeholders
  • Creating API documentation for internal or external consumers
  • Writing runbooks for operational procedures and incident response
  • Capturing tribal knowledge before it's lost to team changes

Core Documentation Types

Architecture Decision Records (ADRs)

ADRs capture the context, options considered, and rationale behind significant architectural decisions. They serve as a historical record that helps future developers understand why the system is built a certain way.

When to create an ADR:

  • Choosing between different technologies, frameworks, or approaches
  • Making decisions that are difficult or expensive to reverse
  • Establishing patterns that will be followed across the codebase
  • Deprecating existing approaches in favor of new ones
  • Any decision that a future developer might question

See: templates/adr-template.md

System Documentation

System documentation provides a comprehensive view of how a system works, its components, and their relationships. It helps new team members onboard and serves as a reference for operations.

Key elements:

  • System overview and purpose
  • Architecture diagrams showing component relationships
  • Data flows and integration points
  • Deployment architecture
  • Operational requirements

See: templates/system-doc-template.md

API Documentation

API documentation describes how to interact with a service, including endpoints, request/response formats, authentication, and error handling.

Key elements:

  • Authentication and authorization
  • Endpoint reference with examples
  • Request and response schemas
  • Error codes and handling
  • Rate limits and quotas
  • Versioning strategy

Runbooks

Runbooks provide step-by-step procedures for operational tasks, from routine maintenance to incident response.

Key elements:

  • Pre-requisites and access requirements
  • Step-by-step procedures with expected outcomes
  • Troubleshooting common issues
  • Escalation paths
  • Recovery procedures

Documentation Patterns

Pattern 1: Decision Context First

Always document the context and constraints that led to a decision before stating the decision itself. Future readers need to understand the "why" before the "what."

## Context

We need to store user session data that must be:
- Available across multiple application instances
- Retrieved in under 10ms
- Retained for 24 hours after last activity

Our current database is PostgreSQL, which would require additional
infrastructure for session management.

## Decision

We will use Redis for session storage.

Pattern 2: Living Documentation

Documentation should be updated as part of the development process, not as an afterthought. Integrate documentation updates into your definition of done.

  • Update ADRs when decisions change (mark old ones as superseded)
  • Revise system docs when architecture evolves
  • Keep API docs in sync with implementation (prefer generated docs where possible)
  • Review runbooks after each incident for accuracy

Pattern 3: Audience-Appropriate Detail

Tailor documentation depth to its intended audience:

Audience Focus Detail Level
New developers Onboarding, getting started High-level concepts, step-by-step guides
Experienced team Reference, troubleshooting Technical details, edge cases
Operations Deployment, monitoring Procedures, commands, expected outputs
Business stakeholders Capabilities, limitations Non-technical summaries, diagrams

Pattern 4: Diagrams Over Prose

Use diagrams to communicate complex relationships. A well-designed diagram can replace pages of text and is easier to maintain.

Recommended diagram types:

  • System context: Shows system boundaries and external interactions
  • Container: Shows major components and their relationships
  • Sequence: Shows how components interact for specific flows
  • Data flow: Shows how data moves through the system

Pattern 5: Executable Documentation

Where possible, make documentation executable or verifiable:

  • API examples that can be run against a test environment
  • Code snippets that are extracted from actual tested code
  • Configuration examples that are validated in CI
  • Runbook steps that have been recently executed

ADR Lifecycle

ADRs follow a specific lifecycle:

  1. Proposed: Decision is being discussed, not yet accepted
  2. Accepted: Decision has been made and should be followed
  3. Deprecated: Decision is being phased out, new work should not follow it
  4. Superseded: Decision has been replaced by a newer ADR (link to new one)

When superseding an ADR:

  • Add "Superseded by ADR-XXX" to the old record
  • Add "Supersedes ADR-YYY" to the new record
  • Explain what changed and why in the new ADR's context

Best Practices

  • Write documentation close to the code it describes (prefer docs-as-code)
  • Use templates consistently to make documentation predictable
  • Include diagrams for architecture; text for procedures
  • Date all documents and note last review date
  • Keep ADRs immutable once accepted (create new ones to supersede)
  • Store documentation in version control alongside code
  • Review documentation accuracy during code reviews
  • Delete or archive documentation for removed features

Anti-Patterns to Avoid

  • Documentation Drift: Docs that no longer match reality are worse than no docs
  • Over-Documentation: Documenting obvious code reduces signal-to-noise
  • Wiki Sprawl: Documentation scattered across multiple systems becomes unfindable
  • Future Fiction: Documenting features that don't exist yet as if they do
  • Write-Only Docs: Creating docs that no one reads or maintains

References

  • templates/adr-template.md - Architecture Decision Record template
  • templates/system-doc-template.md - System documentation template

04 同仓库更多 Skills

shengdabai
shengdabai/Tony-Claude-Code-Skills

seedance-prompt-en

Write effective prompts for Jimeng Seedance 2.0 multimodal AI video generation. Use when users want to create video prompts using text, images, videos, and audio inputs with the @ reference system. Covers camera movements, effects replication, video extension, editing, music beat-matching, e-commerce ads, short dramas, and educational content.

★ 3
shengdabai
shengdabai/Tony-Claude-Code-Skills

onepage-pdf

Convert an HTML page into a single continuous-page PDF (one tall page, no pagination breaks), preserving desktop layout, backgrounds and selectable text. Use when the user asks to turn an HTML file/report/proposal into a "single-page PDF", "long PDF", "不分页 PDF", "单页 PDF", "长图式 PDF", or complains that an HTML-to-PDF export breaks into pages or cuts content. Supports optional string redaction with leak verification.

★ 3
shengdabai
shengdabai/Tony-Claude-Code-Skills

native-feel-cross-platform-desktop

Use when the user is designing, prototyping, or rewriting a desktop app that must run on multiple OSes (macOS + Windows, optionally Linux) AND feel indistinguishable from a native app to its users — fast launch, native windowing, native input handling, native materials. Trigger words include "cross-platform desktop", "Electron alternative", "Tauri vs native", "WebView wrapper", "near-native performance", "Raycast architecture", "WebKit/WebView2 quirks", "WKWebView", "system tray app", "global hotkey app", "launcher app". Do NOT trigger this skill for pure web apps, pure mobile apps, or for greenfield projects that have no native-feel requirement.

★ 3
shengdabai
shengdabai/Tony-Claude-Code-Skills

gstack

Router for the gstack skill suite. (gstack)

★ 3
shengdabai
shengdabai/Tony-Claude-Code-Skills

fireworks-tech-graph

Use when the user wants to create any technical diagram - architecture, data flow, flowchart, sequence, agent/memory, or concept map - and export as SVG+PNG. Trigger on: "画图" "帮我画" "生成图" "做个图" "架构图" "流程图" "可视化一下" "出图" "generate diagram" "draw diagram" "visualize" or any system/flow description the user wants illustrated.

★ 3
shengdabai
shengdabai/Tony-Claude-Code-Skills

dbs-video-extract

接收抖音、小红书、微信视频号等短视频链接或分享文案,查询作品/账号数据并提取语音文字稿,按作者和标题归档为 Markdown。用户希望完整解析短视频、取得数据或文字稿时使用;运行前检查 TikHub 与轻抖使用凭证,缺少时用新手能理解的方式引导购买和安全配置。

★ 3