home / skills / acking-you / myclaude-skills / tech-impl-doc

tech-impl-doc skill

safe

This skill writes precise technical implementation docs with structured sections, Mermaid diagrams, and a Code Index tailored for developers and users.

npx playbooks add skill acking-you/myclaude-skills --skill tech-impl-doc

Review the files below or copy the command above to add this skill to your agents.

Files (1)

SKILL.md

2.5 KB

---
name: tech-impl-doc
description: Write precise technical implementation docs (developer or user) with clear structure, accurate flows, render-safe Mermaid diagrams, and audience-appropriate detail; avoid boilerplate; include a meaningful Code Index for developer docs.
---

# Technical Implementation Doc Skill

## When to use
- The user asks for an implementation doc, technical deep dive, architecture/design write-up, or a user guide describing how a system works.

## Confirm up front
- **Audience**: user / developer / mixed.
- **Scope**: which features or subsystems to cover.
- **Output location** and **language**.
- **Diagrams**: include Mermaid for multi-step flows unless the user says not to.

## Audience rules

### User-facing docs
- **No code locations** or internal class names unless explicitly requested.
- Focus on configuration, behavior, and operational steps.
- Use **direct clickable links** (raw URLs). Do not hide references behind footnotes.
- **Avoid boilerplate**: no “this document describes…”, no “version info”, no filler headings.

### Developer-facing docs
- Include **code paths and line numbers**.
- Add a **Code Index**: each entry must explain what the code is responsible for.
- Call out **constraints, failure modes, and trade-offs**.

## Structure rules
- Headings must be **meaningful** (no parenthetical fluff like “(quick copy)” or “(notes)”).
- Prefer **numbered sections** for complex systems.
- Keep intro minimal; skip generic explanations.

## Mermaid rules (avoid parse errors)
- Keep node labels simple; **avoid parentheses** and heavy punctuation in labels.
- If a label must contain special characters, **wrap it in quotes**.
- Avoid line breaks inside labels.
- Use simple node IDs (A, B, C…).

**Safe example:**
```mermaid
flowchart TB
    A["buildRemotePlan (query_port)"] --> B["CrossClusterMergeStep"]
```

## Workflow
1) Identify audience and constraints.
2) Scan existing docs; consolidate instead of duplicating.
3) Verify claims against source code or authoritative docs.
4) Draft core flow first (request path → execution → merge → output).
5) Add Mermaid diagrams for key flows.
6) Add constraints/unsupported features section.
7) Add Code Index with descriptions (developer docs only).
8) Final pass to remove boilerplate and meaningless headings.

## Output checklist
- Audience-appropriate detail level.
- No redundant intro/version sections unless requested.
- Mermaid diagrams render without parse errors.
- Code Index entries explain their purpose (developer docs only).
- Links are clickable in user docs.

Overview

This skill produces precise technical implementation documents for developer or user audiences, with clear structure, accurate execution flows, render-safe Mermaid diagrams, and audience-appropriate detail. It avoids boilerplate, emphasizes concrete steps and trade-offs, and adds a meaningful Code Index for developer docs.

How this skill works

I confirm audience, scope, output location, language, and diagram preferences up front. I draft the core request-to-execution flow, add render-safe Mermaid diagrams for multi-step processes, and then add constraints, failure modes, and a Code Index when the audience is developers. The result is a compact, actionable doc with links or code references tailored to the chosen audience.

When to use it

You need a developer implementation guide with code paths, line numbers, and a Code Index.
You need an operator or user guide describing configuration, behavior, and operational steps.
You need a focused architecture or design write-up that calls out trade-offs and failure modes.
You want a render-safe sequence or interaction diagram using Mermaid for flows.
You want a consolidated doc that synthesizes multiple existing sources without duplication.

Best practices

Confirm audience and exact scope before drafting (features, subsystems, or endpoints).
Prefer numbered sections for complex flows and minimize introductory filler.
Use render-safe Mermaid labels (simple IDs and quoted labels if they include special chars).
For developer docs include file paths, line numbers, and a Code Index explaining responsibility.
Call out constraints, unsupported features, and likely failure modes explicitly.

Example use cases

Developer-facing doc that maps HTTP request → handler → service → DB and includes a Code Index with file and function roles.
Operator guide that lists required config, startup steps, health checks, and recovery procedures with raw links.
Design decision record that compares two approaches, lists trade-offs, and includes a flowchart of the chosen path.
Migration plan describing stepwise cutover, verification checks, and rollback steps with a Mermaid sequence diagram.
Component deep dive that documents performance constraints, failure scenarios, and mitigation tactics.

FAQ

Do you include code when the audience is users?

No. User-facing docs avoid internal class names and code locations; they focus on configuration, behavior, and operational steps with raw links if needed.

What does the Code Index contain for developer docs?

A Code Index maps file paths and key functions to their responsibilities, plus notes on constraints, side effects, and important line-number references.