[]
Brief one-line description of what the project does.
- Feature 1
- Feature 2
- Feature 3
npm install package-name
import { example } from "package-name";
const result = example();
console.log(result);
See full documentation for detailed guides.
Contributions welcome! See CONTRIBUTING.md.
MIT
All requests require an API key in the Authorization header:
Authorization: Bearer YOUR_API_KEY
https://api.example.com/v1
Retrieve a list of users.
Parameters:
limit (integer, optional): Number of results (default: 10)
offset (integer, optional): Pagination offset (default: 0)
Response:
{
"users": [
{ "id": 1, "name": "John Doe" },
{ "id": 2, "name": "Jane Smith" }
],
"total": 100
}
Error Codes:
401: Unauthorized - Invalid API key
429: Rate limit exceeded
Problem: Brief description of the problem being solved
Solution: High-level approach
Scope: What's included and what's not
Context and motivation for this design.
Goals:
Non-Goals:
- What we're explicitly not doing
- Future considerations
[Diagram or description of system architecture]
- User action
- System processing
- Response
Component A: Responsible for X
Component B: Responsible for Y
<alternative 1>
Pros: ...
Cons: ...
Decision: Not chosen because...
- Data encryption at rest and in transit
- Authentication and authorization
- Input validation
- Unit tests for component logic
- Integration tests for API contracts
- E2E tests for critical user flows
- Phase 1: Internal testing
- Phase 2: Beta release (10% of users)
- Phase 3: Full rollout
Welcome! This guide will help you get started with [Product Name].
Workspace: A container for your projects
Project: A collection of related items
Item: The basic unit of work
- Click the "New Project" button
- Enter a project name
- Choose a template (optional)
- Click "Create"
You'll see your new project in the sidebar.
- Check your email address is correct
- Click "Forgot Password" to reset
- Contact support if the issue persists
Ensure you have a stable internet connection. The app auto-saves every 30 seconds.
Term: Definition
Another Term: Another definition
Professional but approachable
Unnecessarily complex words, idioms that don't translate
Good
Run this command to start the server.
Bad
The server can be started by running the following command.
Bad
サーバーの起動については、下記コマンドを実行することで可能となります。
- Type: [readme/api_spec/design_doc/user_guide]
- Audience: [developer/team/end_user]
- Language: [en/ja/both]
[Proposed sections based on document type]
[Actual documentation content]
1---2name: technical-documentation-43description: This skill should be used when the user asks to "write documentation", "create README", "API docs", "design document", "specification", "user guide", or needs documentation guidance. Provides comprehensive documentation patterns for developers, teams, and end-users in both English and Japanese.4---56<purpose>7Provide structured patterns for creating technical documentation including README, design documents, API specifications, and user guides for diverse audiences.8</purpose>910<tools>11<tool>Write - Create new documentation files</tool>12<tool>Edit - Update existing documentation</tool>13<tool>Read - Review existing documentation and code</tool>14<tool>Grep - Search for patterns across documentation</tool>15<tool>Glob - Find related documentation files</tool>16</tools>1718<concepts>19<concept name="document_types">Four primary types: README (project intro), API spec (endpoints/interfaces), design doc (architecture decisions), user guide (end-user tutorials)</concept>20<concept name="audience_levels">Developer (technical depth), team member (context + depth), end user (no jargon, step-by-step)</concept>21<concept name="progressive_disclosure">Start with quick start, then common cases, then advanced config, finally edge cases</concept>22<concept name="documentation_lifecycle">Plan (outline) → Draft (write + examples) → Review (verify accuracy) → Maintain (update with code)</concept>23</concepts>2425<patterns>26<pattern name="readme_document_type">27<description>Project introduction and quick start guide</description>28<decision_tree name="when_to_use">29<question>Is this the main entry point for project documentation?</question>30<if_yes>Create README with quick start and overview</if_yes>31<if_no>Consider using design doc for detailed architecture or user guide for end-user documentation</if_no>32</decision_tree>33<context>34<audience>Developers, contributors, users</audience>35<when_to_use>Creating or updating main project documentation</when_to_use>36</context>37<structure>38<section>Project title and badges</section>39<section>One-line description</section>40<section>Key features (3-5 bullet points)</section>41<section>Quick start / Installation</section>42<section>Basic usage example</section>43<section>Documentation links</section>44<section>Contributing / License</section>45</structure>46</pattern>4748<pattern name="api_specification_document_type">49<description>API reference documentation</description>50<decision_tree name="when_to_use">51<question>Are you documenting API endpoints or SDK interfaces?</question>52<if_yes>Create API specification with authentication, endpoints, and examples</if_yes>53<if_no>Use README for library usage or design doc for internal architecture</if_no>54</decision_tree>55<context>56<audience>Developers integrating with the API</audience>57<when_to_use>Documenting REST APIs, GraphQL schemas, or SDK interfaces</when_to_use>58</context>59<structure>60<section>Overview and authentication</section>61<section>Base URL and versioning</section>62<section>Endpoints (method, path, parameters, response)</section>63<section>Error codes and handling</section>64<section>Rate limits</section>65<section>Examples (curl, language-specific)</section>66</structure>67</pattern>6869<pattern name="design_document_type">70<description>Technical design and architecture documentation</description>71<decision_tree name="when_to_use">72<question>Are you proposing a major feature or architectural change?</question>73<if_yes>Create design document with technical details, alternatives, and rollout plan</if_yes>74<if_no>Use inline code comments for small changes or README for usage instructions</if_no>75</decision_tree>76<context>77<audience>Team members, reviewers, future maintainers</audience>78<when_to_use>Proposing new features, architectural changes, or major refactors</when_to_use>79</context>80<structure>81<section>Summary (problem, solution, scope)</section>82<section>Background and motivation</section>83<section>Goals and non-goals</section>84<section>Technical design (architecture, data flow)</section>85<section>Alternatives considered</section>86<section>Security / Privacy considerations</section>87<section>Testing strategy</section>88<section>Rollout plan</section>89</structure>90</pattern>9192<pattern name="user_guide_document_type">93<description>End-user facing documentation</description>94<decision_tree name="when_to_use">95<question>Is your audience non-technical end users?</question>96<if_yes>Create user guide with step-by-step tutorials and troubleshooting</if_yes>97<if_no>Use API docs for developers or README for contributors</if_no>98</decision_tree>99<context>100<audience>Non-technical users, administrators</audience>101<when_to_use>Creating help documentation, tutorials, or product guides</when_to_use>102</context>103<structure>104<section>Getting started</section>105<section>Core concepts</section>106<section>Step-by-step tutorials</section>107<section>Feature reference</section>108<section>Troubleshooting / FAQ</section>109<section>Glossary</section>110</structure>111</pattern>112113<pattern name="readme_structure">114<description>Standard structure for README documentation</description>115<example>116<note>Project Name</note>117118[]119120Brief one-line description of what the project does.121122<features>123124- Feature 1125- Feature 2126- Feature 3127128<quick start>129130```bash131npm install package-name132```133134<basic usage>135136```typescript137import { example } from "package-name";138139const result = example();140console.log(result);141```142143<documentation>144145See [full documentation](link) for detailed guides.146147<contributing>148149Contributions welcome! See [CONTRIBUTING.md](link).150151<license>152153MIT154</example>155</pattern>156157<pattern name="api_documentation">158<description>Comprehensive API reference documentation structure</description>159<example>160<note>API Reference</note>161162<authentication>163164All requests require an API key in the Authorization header:165166```bash167Authorization: Bearer YOUR_API_KEY168```169170<base url>171172```173https://api.example.com/v1174```175176<endpoints>177178<get_users>179180Retrieve a list of users.181182**Parameters:**183184- `limit` (integer, optional): Number of results (default: 10)185- `offset` (integer, optional): Pagination offset (default: 0)186187**Response:**188189```json190{191 "users": [192 { "id": 1, "name": "John Doe" },193 { "id": 2, "name": "Jane Smith" }194 ],195 "total": 100196}197```198199**Error Codes:**200201- `401`: Unauthorized - Invalid API key202- `429`: Rate limit exceeded203 </example>204 </pattern>205206<pattern name="design_document_structure">207<description>Technical design document format for architectural decisions</description>208<example>209<note>Feature Name Design Document</note>210211<summary>212213**Problem:** Brief description of the problem being solved214**Solution:** High-level approach215**Scope:** What's included and what's not216217<background>218219Context and motivation for this design.220221<goals and non-goals>222223**Goals:**224225- Goal 1226- Goal 2227228**Non-Goals:**229230- What we're explicitly not doing231- Future considerations232233<technical design>234235<architecture>236237[Diagram or description of system architecture]238239<data flow>2402411. User action2422. System processing2433. Response244245<components>246247**Component A:** Responsible for X248**Component B:** Responsible for Y249250<alternatives considered>251252<alternative 1>253254Pros: ...255Cons: ...256Decision: Not chosen because...257258<security considerations>259260- Data encryption at rest and in transit261- Authentication and authorization262- Input validation263264<testing strategy>265266- Unit tests for component logic267- Integration tests for API contracts268- E2E tests for critical user flows269270<rollout plan>2712721. Phase 1: Internal testing2732. Phase 2: Beta release (10% of users)2743. Phase 3: Full rollout275 </example>276 </pattern>277278<pattern name="user_guide_structure">279<description>End-user documentation with step-by-step instructions</description>280<example>281<note>User Guide</note>282283<getting started>284285Welcome! This guide will help you get started with [Product Name].286287<core concepts>288289**Workspace:** A container for your projects290**Project:** A collection of related items291**Item:** The basic unit of work292293<creating your first project>2942951. Click the "New Project" button2962. Enter a project name2973. Choose a template (optional)2984. Click "Create"299300You'll see your new project in the sidebar.301302<troubleshooting>303304<troubleshooting_login>3053061. Check your email address is correct3072. Click "Forgot Password" to reset3083. Contact support if the issue persists309310<troubleshooting_data>311312Ensure you have a stable internet connection. The app auto-saves every 30 seconds.313314<glossary>315316**Term:** Definition317**Another Term:** Another definition318</example>319</pattern>320</patterns>321322<best_practices>323<practice priority="critical">324<description>Audience-first approach - Write for your specific audience's knowledge level</description>325<example>326Developers: Assume technical background, focus on implementation details327Team members: Balance context with technical depth328End users: Avoid jargon, use step-by-step instructions329</example>330</practice>331332<practice priority="critical">333<description>Progressive disclosure - Start with essentials, reveal complexity gradually</description>334<example>3351. Quick start for immediate value3362. Common use cases3373. Advanced configuration3384. Edge cases and troubleshooting339</example>340</practice>341342<practice priority="high">343<description>Make content scannable to enable quick information retrieval</description>344<example>345- Use descriptive headings346- Use bullet points for lists347- Include code blocks with syntax highlighting348- Use tables for structured data349- Use bold for key terms (sparingly)350</example>351</practice>352353<practice priority="high">354<description>Example-driven documentation - Show, don't just tell</description>355<example>356- Include working code examples357- Show expected output358- Provide copy-pasteable commands359</example>360</practice>361362<practice priority="medium">363<description>Active voice and present tense for clarity</description>364<example>365Good: Run this command to start the server.366Bad: The server can be started by running the following command.367</example>368</practice>369370<practice priority="medium">371<description>Test all code examples before publishing</description>372<example>373Always verify that code examples compile and run correctly374Include expected output375Test edge cases mentioned in documentation376</example>377</practice>378</best_practices>379380<language_guidelines>381<english>382383<style>Active voice, present tense</style>384385<tone>Professional but approachable</tone>386<avoid>Unnecessarily complex words, idioms that don't translate</avoid>387<example>388389<good_example>Good</good_example>390391Run this command to start the server.392393<bad_example>Bad</bad_example>394395The server can be started by running the following command.396</example>397</english>398399<japanese>400<style>です・ます調 (polite form) for user docs, である調 for technical specs</style>401<tone>丁寧だが簡潔</tone>402<avoid>過度なカタカナ語、曖昧な表現</avoid>403<example>404<good_example>Good</good_example>405以下のコマンドでサーバーを起動します。406407<bad_example>Bad</bad_example>408409サーバーの起動については、下記コマンドを実行することで可能となります。410</example>411</japanese>412413<bilingual>414<rule>Maintain parallel structure between languages</rule>415<rule>Keep code examples identical, translate only prose</rule>416<rule>Use consistent terminology (create glossary if needed)</rule>417</bilingual>418</language_guidelines>419420<workflow>421<phase name="plan">422<step>Identify document type and audience</step>423<step>Outline key sections</step>424<step>Gather technical details</step>425</phase>426427<phase name="draft">428<step>Write in order: overview → details → examples</step>429<step>Include all code examples (test them)</step>430<step>Mark TODOs for uncertain parts</step>431</phase>432433<phase name="review">434<step>Verify technical accuracy</step>435<step>Check all links and code examples work</step>436<step>Review for audience appropriateness</step>437<step>Proofread for grammar and typos</step>438</phase>439440<phase name="maintain">441<step>Update when code changes</step>442<step>Review periodically for accuracy</step>443<step>Track user feedback</step>444</phase>445</workflow>446447<output>448<format>449<document plan>450451- Type: [readme/api_spec/design_doc/user_guide]452- Audience: [developer/team/end_user]453- Language: [en/ja/both]454455<structure>456457[Proposed sections based on document type]458459<content>460461[Actual documentation content]462463<review checklist>464465- [ ] Technical accuracy verified466- [ ] Code examples tested467- [ ] Links working468- [ ] Appropriate for audience469- [ ] Grammar and spelling checked470 </format>471 </output>472473<anti_patterns>474<avoid name="wall_of_text">475<description>Long paragraphs without formatting</description>476<instead>Break into smaller paragraphs, use bullet points, headings, and code blocks</instead>477</avoid>478479<avoid name="outdated_info">480<description>Documenting historical context instead of current state</description>481<instead>Document what exists now, move history to a separate section if needed</instead>482</avoid>483484<avoid name="assuming_context">485<description>Using terms or concepts without definition</description>486<instead>Define terms on first use, link to prerequisites, provide glossary</instead>487</avoid>488489<avoid name="untested_examples">490<description>Including code examples that haven't been tested</description>491<instead>Always verify code examples compile and run correctly before publishing</instead>492</avoid>493494<avoid name="passive_voice">495<description>Using passive constructions that obscure agency</description>496<instead>Use active voice for clarity (e.g., "Run the command" not "The command should be run")</instead>497</avoid>498499<avoid name="jargon_overload">500<description>Using technical jargon without explanation</description>501<instead>Define technical terms on first use, provide a glossary, or use simpler language for user-facing docs</instead>502</avoid>503504<avoid name="missing_prerequisites">505<description>Assuming users have required knowledge or setup</description>506<instead>List prerequisites clearly at the beginning, link to setup guides</instead>507</avoid>508509<avoid name="vague_instructions">510<description>Using imprecise language like "simply" or "just" without concrete steps</description>511<instead>Provide specific, numbered steps with expected outcomes</instead>512</avoid>513</anti_patterns>514515<rules priority="critical">516<rule>Verify all code examples compile and run before including in documentation</rule>517<rule>Match documentation structure to audience knowledge level</rule>518<rule>Never publish documentation with placeholder content or TODOs</rule>519</rules>520521<rules priority="standard">522<rule>Use active voice and present tense for instructions</rule>523<rule>Include expected output for all code examples</rule>524<rule>Define technical terms on first use or link to glossary</rule>525<rule>Keep README under 500 lines; link to detailed docs for more</rule>526</rules>527528<error_escalation>529<level severity="low">530<example>Minor formatting inconsistency</example>531<action>Fix formatting, follow style guide</action>532</level>533<level severity="medium">534<example>Outdated information detected</example>535<action>Update content, verify with code</action>536</level>537<level severity="high">538<example>Incorrect technical information</example>539<action>Stop, verify with implementation before publishing</action>540</level>541<level severity="critical">542<example>Security-sensitive information exposed</example>543<action>Block publication, require security review</action>544</level>545</error_escalation>546547<constraints>548<must>Verify accuracy against actual implementation</must>549<must>Include runnable code examples</must>550<must>Follow project documentation style</must>551<avoid>Documenting without reading code</avoid>552<avoid>Adding timestamps to documents</avoid>553<avoid>Duplicating information unnecessarily</avoid>554</constraints>555556<related_agents>557<agent name="design">Requirements analysis and documentation structure planning</agent>558<agent name="docs">Technical documentation writing and generation</agent>559<agent name="execute">Documentation deployment and publishing tasks</agent>560<agent name="bug">Fixing broken links, outdated examples, and documentation inconsistencies</agent>561</related_agents>562563<related_skills>564<skill name="serena-usage">Symbol operations for extracting code examples and API signatures</skill>565<skill name="context7-usage">Library documentation lookup for accurate API references</skill>566<skill name="investigation-patterns">Analyzing codebases to understand features for documentation</skill>567<skill name="technical-writing">Creating blog posts and tutorials from documentation</skill>568</related_skills>