yuusakuriyuusakuri/agent-skills/skills/document-architecture/SKILL.md

document-architecture

Skill2 starsChanged 10 days agoMITView on GitHub

Coauthor, restructure, and quality-review formal system documents with a single canonical outline and traceable decisions. Use when creating or revising a requirements definition, technical specification, basic design, detailed design, system proposal, or business proposal. Default to GitHub-Flavored Markdown; create Word only when explicitly requested. Route PRDs, ADRs, unresolved technical choices, and implementation plans to their existing specialist skills instead of creating competing artifacts.

We split this skill into the rules it gives an agent

24 rules. About 0 are common, 15 are distinctive, and 9 are very specific to this project.

≈0
Common · estimate
Many files like this have a rule of this kind.
≈15
Distinctive · estimate
This author's own choices. Worth a look.
9
Very specific
Tied to their project's names, files or tools. Probably skip.

Common
Distinctive
Very specific

Distinctive:
Create decision-ready system documents without duplicating the responsibility of PRDs, ADRs, technical exploration, or implementation plans.
line 8
Very specific:
Always read references/quality-checklist.md before finalizing the document.
line 23
Very specific:
Use deliver-prd for a product requirements document covering the customer problem, value, product scope, and outcomes.
line 27
Very specific:
Use brainstorming when a technical approach is unresolved.
line 28
Very specific:
Use spec-driven-development for a coding implementation specification.
line 29
Very specific:
Use planning-and-task-breakdown for file-level implementation tasks and verification steps.
line 30
Very specific:
Use documentation-and-adrs for an architecture decision record explaining a costly-to-reverse decision.
line 31
Very specific:
Use develop-solution-brief for a short internal alignment document.
line 32
Distinctive:
Use this skill for formal requirements, specifications, designs, and proposals after identifying their inputs and decision audience.
line 33
Distinctive:
Update or reference an existing canonical artifact.
line 35
Distinctive:
Read the selected document reference and propose its outline.
line 42
Distinctive:
Add traceability identifiers where downstream verification matters.
line 45
Very specific:
Read references/quality-checklist.md, fix failures, and verify the document from the reader's perspective.
line 46
Distinctive:
Ask only for information that changes the structure, scope, or decision.
line 48
Distinctive:
Use standard GitHub heading levels, relative links, tables, task lists, and fenced code blocks.
line 55
Distinctive:
Use Mermaid only when a relationship, sequence, or boundary is materially clearer as a diagram.
line 56
Distinctive:
Keep one canonical statement for each requirement or decision and link to it instead of copying it.
line 57
Distinctive:
Prefer reviewable text diffs and repository history over presentation-only formatting.
line 58
Distinctive:
Use stable identifiers when the document feeds another lifecycle artifact.
line 62
Distinctive:
Do not assign identifiers to narrative that will never be referenced.
line 73
Distinctive:
Only create a Word deliverable when explicitly requested by the user or required by the named delivery contract.
line 77
Very specific:
Use assets/templates/base-document.docx as the common style source.
line 79
Distinctive:
Use the document creation skill to apply styles, render the DOCX to PNG, inspect every page, and iterate until clean.
line 81
Distinctive:
Do not append a redundant summary document when the requested document already contains an executive summary or decision section.
line 95

≈ “Common” is an estimate: at least 1 in 5 of the 308,232 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

Document Architecture

Create decision-ready system documents without duplicating the responsibility of PRDs, ADRs, technical exploration, or implementation plans.

Route the request

Select exactly one primary document type, then read its reference completely.

Requested outcome	Read
Define business and system requirements, scope, and acceptance	`references/requirements-definition.md`
Record a selected technical approach for implementers	`references/technical-spec.md`
Define externally observable behavior and major internal boundaries	`references/basic-design.md`
Define implementation-level modules, processing, data updates, and unit tests	`references/detailed-design.md`
Propose a system investment, delivery, cost, and benefit to a customer	`references/system-proposal.md`
Propose business improvement or a new operating initiative	`references/business-proposal.md`

Always read references/quality-checklist.md before finalizing the document. Do not read unrelated document references.

Preserve artifact ownership

Use deliver-prd for a product requirements document covering the customer problem, value, product scope, and outcomes.
Use brainstorming when a technical approach is unresolved. Compare options first, then record the selected approach in the technical document.
Use spec-driven-development for a coding implementation specification.
Use planning-and-task-breakdown for file-level implementation tasks and verification steps.
Use documentation-and-adrs for an architecture decision record explaining a costly-to-reverse decision.
Use develop-solution-brief for a short internal alignment document.
Use this skill for formal requirements, specifications, designs, and proposals after identifying their inputs and decision audience.

Update or reference an existing canonical artifact. Never create a second document that owns the same decision or requirement.

Follow the coauthoring workflow

Identify the primary reader, purpose, expected decision, use date, and delivery format.
Identify existing source artifacts and the owner of each fact or decision.
Select one primary document type. If several documents are needed, order them by dependency and create or update them one at a time.
Read the selected document reference and propose its outline. Preserve an existing approved outline unless changing it resolves a concrete gap.
Classify input as Fact, Decision, Assumption, or Open question. Cite the source of facts and name the owner and review date of assumptions.
Draft each section for its decision purpose. Prefer measurable statements, explicit scope boundaries, and testable conditions.
Add traceability identifiers where downstream verification matters.
Read references/quality-checklist.md, fix failures, and verify the document from the reader's perspective.

Ask only for information that changes the structure, scope, or decision. When information is unavailable, mark the specific assumption and its consequence instead of inventing data.

Default to GitHub Markdown

GitHub-Flavored Markdown is the default output.

Store the canonical document as a .md file in the project repository.
Use standard GitHub heading levels, relative links, tables, task lists, and fenced code blocks.
Use Mermaid only when a relationship, sequence, or boundary is materially clearer as a diagram.
Keep one canonical statement for each requirement or decision and link to it instead of copying it.
Prefer reviewable text diffs and repository history over presentation-only formatting.

Maintain traceability

Use stable identifiers when the document feeds another lifecycle artifact.

Item	Prefix example	Trace to
Business requirement	`BR-001`	Goal, stakeholder, process
Functional requirement	`FR-001`	Business requirement, acceptance condition
Non-functional requirement	`NFR-001`	Quality target, measurement method
Interface requirement	`IF-001`	Producer, consumer, contract
Design element	`DES-001`	Requirement and verification
Risk	`RSK-001`	Mitigation, owner, trigger

Do not assign identifiers to narrative that will never be referenced. Keep identifiers stable when wording changes.

Create Word deliverables only on request

Only create a Word deliverable when explicitly requested by the user or required by the named delivery contract.

Use assets/templates/base-document.docx as the common style source.
Generate the document chapters from the selected reference; do not copy a chapter list from the template.
Use the document creation skill to apply styles, render the DOCX to PNG, inspect every page, and iterate until clean.
Deliver the final document only after the latest render passes.

The template owns presentation. The selected reference owns document structure. The current artifact owns project-specific content.

Finalize the result

Return:

the completed or updated canonical document;
the decision it supports;
assumptions and open questions that materially affect approval or execution;
the next owned artifact, if one is required.

Do not append a redundant summary document when the requested document already contains an executive summary or decision section.

Download now (ZIP)

Other versions2 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 2
soderlind/skills★ 3same name
frameforged/technical-documentation-framework★ 2same name
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository100 other files it gives its agents.
- ab-test-analysisSkill
- analyze-feature-requestsSkill
- ansoff-matrixSkill
- api-and-interface-designSkill
- beachhead-segmentSkill
- brainstorm-experiments-existingSkill
- brainstorm-experiments-newSkill
- brainstorm-ideas-existingSkill
- brainstorm-ideas-newSkill
- brainstormingSkill
- brainstorm-okrsSkill
- browser-testing-with-devtoolsSkill
- business-modelSkill
- ci-cd-and-automationSkill
- code-review-and-qualitySkill
- code-simplificationSkill
- cohort-analysisSkill
- competitive-battlecardSkill
- context-engineeringSkill
- customer-journey-mapSkill
- debugging-and-error-recoverySkill
- define-hypothesisSkill
- define-jtbd-canvasSkill
- define-opportunity-treeSkill
- define-problem-statementSkill
- deliver-acceptance-criteriaSkill
- deliver-edge-casesSkill
- deliver-prdSkill
- deprecation-and-migrationSkill
- develop-solution-briefSkill
- discover-competitive-analysisSkill
- discover-interview-synthesisSkill
- discover-market-sizingSkill
- documentation-and-adrsSkill
- draft-ndaSkill
- dummy-datasetSkill
- frontend-ui-engineeringSkill
- git-workflow-and-versioningSkill
- grammar-checkSkill
- growth-loopsSkill
- gtm-motionsSkill
- gtm-strategySkill
- ideal-customer-profileSkill
- identify-assumptions-existingSkill
- identify-assumptions-newSkill
- incremental-implementationSkill
- intended-vs-implementedSkill
- interview-meSkill
- interview-scriptSkill
- job-storiesSkill
- lean-canvasSkill
- marketing-ideasSkill
- market-segmentsSkill
- measure-experiment-designSkill
- metrics-dashboardSkill
- modern-web-guidanceSkill
- monetization-strategySkill
- north-star-metricSkill
- observability-and-instrumentationSkill
- outcome-roadmapSkill
- The first 60 shown.

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.

Check your setup, free