{"id":"bdd565a7-3a7f-4ffe-9343-bcbc0256ed7e","shortId":"Zywybd","kind":"skill","title":"code-documentation","tagline":"Writing effective code documentation - API docs, README files, inline comments, and technical guides. Use for documenting codebases, APIs, or writing developer guides.","description":"# Code Documentation\n\n## README Structure\n\n### Standard README Template\n```markdown\n# Project Name\n\nBrief description of what this project does.\n\n## Quick Start\n\n\\`\\`\\`bash\nnpm install\nnpm run dev\n\\`\\`\\`\n\n## Installation\n\nDetailed installation instructions...\n\n## Usage\n\n\\`\\`\\`typescript\nimport { something } from 'project';\n\n// Example usage\nconst result = something.doThing();\n\\`\\`\\`\n\n## API Reference\n\n### `functionName(param: Type): ReturnType`\n\nDescription of what the function does.\n\n**Parameters:**\n- `param` - Description of parameter\n\n**Returns:** Description of return value\n\n**Example:**\n\\`\\`\\`typescript\nconst result = functionName('value');\n\\`\\`\\`\n\n## Configuration\n\n| Option | Type | Default | Description |\n|--------|------|---------|-------------|\n| `option1` | `string` | `'default'` | What it does |\n\n## Contributing\n\nHow to contribute...\n\n## License\n\nMIT\n```\n\n## API Documentation\n\n### JSDoc/TSDoc Style\n```typescript\n/**\n * Creates a new user account.\n *\n * @param userData - The user data for account creation\n * @param options - Optional configuration\n * @returns The created user object\n * @throws {ValidationError} If email is invalid\n * @example\n * ```ts\n * const user = await createUser({\n *   email: 'user@example.com',\n *   name: 'John'\n * });\n * ```\n */\nasync function createUser(\n  userData: UserInput,\n  options?: CreateOptions\n): Promise<User> {\n  // Implementation\n}\n\n/**\n * Configuration options for the API client.\n */\ninterface ClientConfig {\n  /** The API base URL */\n  baseUrl: string;\n  /** Request timeout in milliseconds @default 5000 */\n  timeout?: number;\n  /** Custom headers to include in requests */\n  headers?: Record<string, string>;\n}\n```\n\n### OpenAPI/Swagger\n```yaml\nopenapi: 3.0.0\ninfo:\n  title: My API\n  version: 1.0.0\n\npaths:\n  /users:\n    post:\n      summary: Create a user\n      description: Creates a new user account\n      requestBody:\n        required: true\n        content:\n          application/json:\n            schema:\n              $ref: '#/components/schemas/UserInput'\n      responses:\n        '201':\n          description: User created successfully\n          content:\n            application/json:\n              schema:\n                $ref: '#/components/schemas/User'\n        '400':\n          description: Invalid input\n\ncomponents:\n  schemas:\n    UserInput:\n      type: object\n      required:\n        - email\n        - name\n      properties:\n        email:\n          type: string\n          format: email\n        name:\n          type: string\n    User:\n      type: object\n      properties:\n        id:\n          type: string\n        email:\n          type: string\n        name:\n          type: string\n        createdAt:\n          type: string\n          format: date-time\n```\n\n## Inline Comments\n\n### When to Comment\n```typescript\n// GOOD: Explain WHY, not WHAT\n\n// Use binary search because the list is always sorted and\n// can contain millions of items - O(log n) vs O(n)\nconst index = binarySearch(items, target);\n\n// GOOD: Explain complex business logic\n// Users get 20% discount if they've been members for 2+ years\n// AND have made 10+ purchases (per marketing team decision Q4 2024)\nif (user.memberYears >= 2 && user.purchaseCount >= 10) {\n  applyDiscount(0.2);\n}\n\n// GOOD: Document workarounds\n// HACK: Safari doesn't support this API, fallback to polling\n// TODO: Remove when Safari adds support (tracking: webkit.org/b/12345)\nif (!window.IntersectionObserver) {\n  startPolling();\n}\n```\n\n### When NOT to Comment\n```typescript\n// BAD: Stating the obvious\n// Increment counter by 1\ncounter++;\n\n// BAD: Explaining clear code\n// Check if user is admin\nif (user.role === 'admin') { ... }\n\n// BAD: Outdated comments (worse than no comment)\n// Returns the user's full name  <-- Actually returns email now!\nfunction getUserIdentifier(user) {\n  return user.email;\n}\n```\n\n## Architecture Documentation\n\n### ADR (Architecture Decision Record)\n```markdown\n# ADR-001: Use PostgreSQL for Primary Database\n\n## Status\nAccepted\n\n## Context\nWe need a database for storing user data and transactions.\nOptions considered: PostgreSQL, MySQL, MongoDB, DynamoDB.\n\n## Decision\nUse PostgreSQL with Supabase hosting.\n\n## Rationale\n- Strong ACID compliance needed for financial data\n- Team has PostgreSQL experience\n- Supabase provides auth and realtime features\n- pgvector extension for future AI features\n\n## Consequences\n- Need to manage schema migrations\n- May need read replicas for scale\n- Team needs to learn Supabase-specific features\n```\n\n### Component Documentation\n```markdown\n## Authentication Module\n\n### Overview\nHandles user authentication using JWT tokens with refresh rotation.\n\n### Flow\n1. User submits credentials to `/auth/login`\n2. Server validates and returns access + refresh tokens\n3. Access token used for API requests (15min expiry)\n4. Refresh token used to get new access token (7d expiry)\n\n### Dependencies\n- `jsonwebtoken` - Token generation/validation\n- `bcrypt` - Password hashing\n- `redis` - Refresh token storage\n\n### Configuration\n- `JWT_SECRET` - Secret for signing tokens\n- `ACCESS_TOKEN_EXPIRY` - Access token lifetime\n- `REFRESH_TOKEN_EXPIRY` - Refresh token lifetime\n```\n\n## Documentation Principles\n\n1. **Write for your audience** - New devs vs API consumers\n2. **Keep it close to code** - Docs in same repo, near relevant code\n3. **Update with code** - Stale docs are worse than none\n4. **Examples over explanations** - Show, don't just tell\n5. **Progressive disclosure** - Quick start first, details later","tags":["code","documentation","agent","skills","moizibnyousaf","agent-skills","claude-code","cli","codex","cursor","developer-tools","productivity"],"capabilities":["skill","source-moizibnyousaf","skill-code-documentation","topic-agent-skills","topic-claude-code","topic-cli","topic-codex","topic-cursor","topic-developer-tools","topic-productivity"],"categories":["Ai-Agent-Skills"],"synonyms":[],"warnings":[],"endpointUrl":"https://skills.sh/MoizIbnYousaf/Ai-Agent-Skills/code-documentation","protocol":"skill","transport":"skills-sh","auth":{"type":"none","details":{"cli":"npx skills add MoizIbnYousaf/Ai-Agent-Skills","source_repo":"https://github.com/MoizIbnYousaf/Ai-Agent-Skills","install_from":"skills.sh"}},"qualityScore":"0.700","qualityRationale":"deterministic score 0.70 from registry signals: · indexed on github topic:agent-skills · 1044 github stars · SKILL.md body (5,494 chars)","verified":false,"liveness":"unknown","lastLivenessCheck":null,"agentReviews":{"count":0,"score_avg":null,"cost_usd_avg":null,"success_rate":null,"latency_p50_ms":null,"narrative_summary":null,"summary_updated_at":null},"enrichmentModel":"deterministic:skill-github:v1","enrichmentVersion":1,"enrichedAt":"2026-05-02T18:52:54.546Z","embedding":null,"createdAt":"2026-04-18T21:56:12.561Z","updatedAt":"2026-05-02T18:52:54.546Z","lastSeenAt":"2026-05-02T18:52:54.546Z","tsv":"'-001':432 '/auth/login':528 '/b/12345)':372 '/components/schemas/user':236 '/components/schemas/userinput':225 '/users':206 '0.2':349 '1':388,523,589 '1.0.0':204 '10':335,347 '15min':544 '2':330,345,529,599 '20':322 '201':227 '2024':342 '3':537,612 '3.0.0':198 '4':546,622 '400':237 '5':631 '5000':182 '7d':555 'accept':439 'access':534,538,553,575,578 'account':120,127,217 'acid':465 'actual':415 'add':367 'admin':398,401 'adr':426,431 'ai':485 'alway':296 'api':8,21,66,111,167,172,202,359,542,597 'application/json':222,233 'applydiscount':348 'architectur':424,427 'async':154 'audienc':593 'auth':477 'authent':510,515 'await':148 'bad':381,390,402 'base':173 'baseurl':175 'bash':45 'bcrypt':561 'binari':290 'binarysearch':312 'brief':36 'busi':318 'check':394 'clear':392 'client':168 'clientconfig':170 'close':602 'code':2,6,26,393,604,611,615 'code-document':1 'codebas':20 'comment':13,279,282,379,404,408 'complex':317 'complianc':466 'compon':241,507 'configur':94,132,163,568 'consequ':487 'consid':452 'const':63,90,146,310 'consum':598 'contain':300 'content':221,232 'context':440 'contribut':105,108 'counter':386,389 'creat':116,135,209,213,230 'createdat':271 'createopt':160 'createus':149,156 'creation':128 'credenti':526 'custom':185 'data':125,448,470 'databas':437,444 'date':276 'date-tim':275 'decis':340,428,457 'default':97,101,181 'depend':557 'descript':37,72,80,84,98,212,228,238 'detail':52,637 'dev':50,595 'develop':24 'disclosur':633 'discount':323 'doc':9,605,617 'document':3,7,19,27,112,351,425,508,587 'doesn':355 'dynamodb':456 'effect':5 'email':141,150,247,250,254,265,417 'exampl':61,88,144,623 'experi':474 'expiri':545,556,577,583 'explain':285,316,391 'explan':625 'extens':482 'fallback':360 'featur':480,486,506 'file':11 'financi':469 'first':636 'flow':522 'format':253,274 'full':413 'function':76,155,419 'functionnam':68,92 'futur':484 'generation/validation':560 'get':321,551 'getuseridentifi':420 'good':284,315,350 'guid':16,25 'hack':353 'handl':513 'hash':563 'header':186,191 'host':462 'id':262 'implement':162 'import':57 'includ':188 'increment':385 'index':311 'info':199 'inlin':12,278 'input':240 'instal':47,51,53 'instruct':54 'interfac':169 'invalid':143,239 'item':303,313 'john':153 'jsdoc/tsdoc':113 'jsonwebtoken':558 'jwt':517,569 'keep':600 'later':638 'learn':502 'licens':109 'lifetim':580,586 'list':294 'log':305 'logic':319 'made':334 'manag':490 'markdown':33,430,509 'market':338 'may':493 'member':328 'migrat':492 'million':301 'millisecond':180 'mit':110 'modul':511 'mongodb':455 'mysql':454 'n':306,309 'name':35,152,248,255,268,414 'near':609 'need':442,467,488,494,500 'new':118,215,552,594 'none':621 'npm':46,48 'number':184 'o':304,308 'object':137,245,260 'obvious':384 'openapi':197 'openapi/swagger':195 'option':95,130,131,159,164,451 'option1':99 'outdat':403 'overview':512 'param':69,79,121,129 'paramet':78,82 'password':562 'path':205 'per':337 'pgvector':481 'poll':362 'post':207 'postgresql':434,453,459,473 'primari':436 'principl':588 'progress':632 'project':34,41,60 'promis':161 'properti':249,261 'provid':476 'purchas':336 'q4':341 'quick':43,634 'rational':463 'read':495 'readm':10,28,31 'realtim':479 'record':192,429 'redi':564 'ref':224,235 'refer':67 'refresh':520,535,547,565,581,584 'relev':610 'remov':364 'replica':496 'repo':608 'request':177,190,543 'requestbodi':218 'requir':219,246 'respons':226 'result':64,91 'return':83,86,133,409,416,422,533 'returntyp':71 'rotat':521 'run':49 'safari':354,366 'scale':498 'schema':223,234,242,491 'search':291 'secret':570,571 'server':530 'show':626 'sign':573 'skill' 'skill-code-documentation' 'someth':58 'something.dothing':65 'sort':297 'source-moizibnyousaf' 'specif':505 'stale':616 'standard':30 'start':44,635 'startpol':375 'state':382 'status':438 'storag':567 'store':446 'string':100,176,193,194,252,257,264,267,270,273 'strong':464 'structur':29 'style':114 'submit':525 'success':231 'summari':208 'supabas':461,475,504 'supabase-specif':503 'support':357,368 'target':314 'team':339,471,499 'technic':15 'tell':630 'templat':32 'throw':138 'time':277 'timeout':178,183 'titl':200 'todo':363 'token':518,536,539,548,554,559,566,574,576,579,582,585 'topic-agent-skills' 'topic-claude-code' 'topic-cli' 'topic-codex' 'topic-cursor' 'topic-developer-tools' 'topic-productivity' 'track':369 'transact':450 'true':220 'ts':145 'type':70,96,244,251,256,259,263,266,269,272 'typescript':56,89,115,283,380 'updat':613 'url':174 'usag':55,62 'use':17,289,433,458,516,540,549 'user':119,124,136,147,211,216,229,258,320,396,411,421,447,514,524 'user.email':423 'user.memberyears':344 'user.purchasecount':346 'user.role':400 'user@example.com':151 'userdata':122,157 'userinput':158,243 'valid':531 'validationerror':139 'valu':87,93 've':326 'version':203 'vs':307,596 'webkit.org':371 'webkit.org/b/12345)':370 'window.intersectionobserver':374 'workaround':352 'wors':405,619 'write':4,23,590 'yaml':196 'year':331","prices":[{"id":"4cb81dab-2cf8-47ea-b8a0-b5f41e1474f1","listingId":"bdd565a7-3a7f-4ffe-9343-bcbc0256ed7e","amountUsd":"0","unit":"free","nativeCurrency":null,"nativeAmount":null,"chain":null,"payTo":null,"paymentMethod":"skill-free","isPrimary":true,"details":{"org":"MoizIbnYousaf","category":"Ai-Agent-Skills","install_from":"skills.sh"},"createdAt":"2026-04-18T21:56:12.561Z"}],"sources":[{"listingId":"bdd565a7-3a7f-4ffe-9343-bcbc0256ed7e","source":"github","sourceId":"MoizIbnYousaf/Ai-Agent-Skills/code-documentation","sourceUrl":"https://github.com/MoizIbnYousaf/Ai-Agent-Skills/tree/main/skills/code-documentation","isPrimary":false,"firstSeenAt":"2026-04-18T21:56:12.561Z","lastSeenAt":"2026-05-02T18:52:54.546Z"}],"details":{"listingId":"bdd565a7-3a7f-4ffe-9343-bcbc0256ed7e","quickStartSnippet":null,"exampleRequest":null,"exampleResponse":null,"schema":null,"openapiUrl":null,"agentsTxtUrl":null,"citations":[],"useCases":[],"bestFor":[],"notFor":[],"kindDetails":{"org":"MoizIbnYousaf","slug":"code-documentation","github":{"repo":"MoizIbnYousaf/Ai-Agent-Skills","stars":1044,"topics":["agent-skills","claude-code","cli","codex","cursor","developer-tools","productivity"],"license":"mit","html_url":"https://github.com/MoizIbnYousaf/Ai-Agent-Skills","pushed_at":"2026-04-13T19:04:12Z","description":"my curated agent skills library ","skill_md_sha":"7887254996be4d7b59d71e653d0ef412d2d66351","skill_md_path":"skills/code-documentation/SKILL.md","default_branch":"main","skill_tree_url":"https://github.com/MoizIbnYousaf/Ai-Agent-Skills/tree/main/skills/code-documentation"},"layout":"multi","source":"github","category":"Ai-Agent-Skills","frontmatter":{"name":"code-documentation","license":"MIT","description":"Writing effective code documentation - API docs, README files, inline comments, and technical guides. Use for documenting codebases, APIs, or writing developer guides."},"skills_sh_url":"https://skills.sh/MoizIbnYousaf/Ai-Agent-Skills/code-documentation"},"updatedAt":"2026-05-02T18:52:54.546Z"}}