[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M6QHYJKA0AT8JZVEF43W0KT1":3,"skill-same:01M6QHYJKA0AT8JZVEF43W0KT1":82},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":15,"categories":16,"keywords":27,"publishedAt":48,"linkOnly":49,"markdownContent":50,"markdownBody":51,"frontMatter":52,"refName":62,"commitSha":63,"skillDirectory":64,"forksCount":13,"repositoryHtmlUrl":65,"repositoryHomepageUrl":6,"ownerHtmlUrl":66,"ownerBlogUrl":6,"ownerDescription":6,"updatedAt":67,"install":68,"resources":81},"01M6QHYJKA0AT8JZVEF43W0KT1","explain-code",null,"Master the art of explaining code clearly: how to distill complex logic into understandable explanations, adjust depth for audience, and make unfamiliar code accessible. Use when user asks to explain code, understand code, document code, or when they need to communicate how code works. Triggers especially when user says \"explain this code\", \"what does this do\", \"how does this work\", \"help me understand\", or \"explain this function\".","ImaginerLabs\u002Fskill-manager","ImaginerLabs","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F214277308?v=4","01M6QGGDPNF15RMMT1RCFDH9FN","01M6QGGDTH5BY64DQ123NR8M33",0,"MIT","https:\u002F\u002Fgithub.com\u002FImaginerLabs\u002Fskill-manager\u002Fblob\u002Fmain\u002Fskills\u002Fcoding\u002Fexplain-code\u002FSKILL.md",[17,22],{"categoryNo":18,"categoryName":19,"taxonomyType":20,"taxonomyTypeDesc":21},"01JBSEEDCAT000000000000002","文档处理","SCENARIO","使用场景",{"categoryNo":23,"categoryName":24,"taxonomyType":25,"taxonomyTypeDesc":26},"01JBSEEDCAT000000000000030","开发工程师","PROFESSION","适用职业",[28,29,30,31,32,33,34,35,36,37,38,39,40,41,42,43,44,45,46,47],"explain code","code","explain","depth","for","make","communicate","how to","triggers","adjust","me","do","document","master","Art","use","distill","work","coding","how","2026-11-10 10:12:30",false,"---\nname: explain-code\ndescription: >-\n  Master the art of explaining code clearly: how to distill complex logic into understandable explanations, adjust depth for audience, and make unfamiliar code accessible. Use when user asks to explain code, understand code, document code, or when they need to communicate how code works. Triggers especially when user says \"explain this code\", \"what does this do\", \"how does this work\", \"help me understand\", or \"explain this function\".\ncategory: coding\npriority: P1\ntrigger_patterns:\n  - \"explain this code\"\n  - \"what does this do\"\n  - \"how does this work\"\n  - \"help me understand\"\n  - \"explain this function\"\n  - \"code explanation\"\n  - \"document this code\"\n---\n\n# Explain Code — Code Comprehension Framework\n\n## Overview\n\nExplain-code is a **behavioral specification skill** that encapsulates the methodology for **clearly explaining code to humans**, whether that's documenting for future self, teaching teammates, or creating accessible documentation.\n\nThe core judgment it provides: **\"How do I explain this code so that someone can understand what it does and why?\"**\n\n## Core Philosophy\n\n### The Explanation Paradox\n\n> \"Code explains HOW, but not WHY. Comments explain WHY, but not HOW. Good explanation does both — in the right proportion for the audience.\"\n\nThe best code explanation is the one that answers the question behind the question.\n\n### The Three Levels of Code Understanding\n\n```\n┌─────────────────────────────────────────────────────────────┐\n│                 CODE UNDERSTANDING LEVELS                     │\n│                                                               │\n│  LEVEL 1: SYNTAX                                             │\n│  └─ \"I understand the code structure\"                       │\n│                                                               │\n│  LEVEL 2: BEHAVIOR                                           │\n│  └─ \"I understand what the code does\"                       │\n│                                                               │\n│  LEVEL 3: INTENT                                             │\n│  └─ \"I understand WHY the code does this\"                    │\n│                                                               │\n│  Best explanations address LEVEL 3 first,                    │\n│  then fill in levels 1-2 as needed.                          │\n└─────────────────────────────────────────────────────────────┘\n```\n\n## Decision Framework\n\n### Before Explaining: Audience Analysis\n\n| Question | Audience Adjustment |\n|----------|---------------------|\n| Who's reading? | Expert vs novice |\n| What's their goal? | Understand to use vs modify vs review |\n| What do they already know? | Domain concepts, tech stack |\n| What's their time pressure? | Quick summary vs deep dive |\n| Why are they asking? | Debugging vs learning vs reviewing |\n\n### The Audience Spectrum\n\n```\n┌─────────────────────────────────────────────────────────────────┐\n│                     AUDIENCE ADJUSTMENT                          │\n│                                                                   │\n│  NEWCOMER                   COLLEAGUE                   EXPERT   │\n│  ─────────                  ─────────                  ───────  │\n│  Explain basics             Assume some                Just show │\n│  Define terms               knowledge                  the code   │\n│  Show examples              Focus on interesting       Focus on  │\n│  Connect to concepts        parts                      edge cases │\n│                                                                   │\n│  WHY: Learn                  WHY: Collaborate            WHY: Review│\n└─────────────────────────────────────────────────────────────────┘\n```\n\n## Behavioral Specification\n\n### Phase 1: Code Analysis\n\n#### 1.1 First Read: Understanding Structure\n\n```markdown\n## Code Structure Analysis\n\nFile: paymentProcessor.ts\n\nLines 1-20: Imports and types\nLines 21-50: Helper functions\nLines 51-100: Main processor class\nLines 101-150: Error handling\nLines 151-200: Integration points\n\nInitial observations:\n- Uses class-based design\n- Depends on external payment gateway\n- Has significant error handling\n- ~200 lines suggests single responsibility concern\n```\n\n#### 1.2 Second Read: Understanding Flow\n\n```markdown\n## Execution Flow Analysis\n\npaymentProcessor.charge()\n\nEntry: User provides payment details\n    │\n    ▼\nStep 1: Validate payment data\n    │\n    ▼\nStep 2: Format for gateway API\n    │\n    ▼\nStep 3: Call payment gateway\n    │\n    ▼\nStep 4: Map response to internal format\n    │\n    ▼\nExit: Return payment result\n```\n\n#### 1.3 Third Read: Understanding Intent\n\n```markdown\n## Intent Discovery\n\nQuestions to ask:\n- Why was this approach chosen over alternatives?\n- What business rules are encoded here?\n- What constraints shaped the design?\n- What edge cases is this handling?\n\nClues in the code:\n- Comments mentioning business rules\n- Error handling for specific cases\n- Validation of specific formats\n- Comments referencing external systems\n```\n\n### Phase 2: Explanation Structure\n\n#### 2.1 The Intention-First Pattern\n\n**BAD:**\n```markdown\n\"This function takes a user ID, queries the database for the user,\ncreates an order object, saves it to the database, and returns the order.\"\n```\n\n**GOOD:**\n```markdown\n\"Creates an order for a user.\n\nThe function handles the full order creation flow:\n1. Fetches the user to ensure they exist\n2. Creates an order in PENDING state\n3. Saves to database\n4. Returns the created order\n\nWhy this flow matters: This ensures atomic order creation —\nif any step fails, no partial order is created.\"\n```\n\n#### 2.2 The Purpose-Signature-Body Pattern\n\n```markdown\n## FunctionName: What It Does\n\n**Purpose:** [One sentence describing WHY this exists]\n\n**Signature:**\n```typescript\nfunction processPayment(\n  amount: number,\n  paymentMethod: PaymentMethod\n): Promise\u003CPaymentResult>\n```\n\n**Behavior:**\n1. [Step 1]\n2. [Step 2]\n3. [Returns\u002FThrows]\n\n**Key decisions:**\n- [Why approach X over Y]\n- [Edge cases handled]\n- [Business rules enforced]\n```\n\n#### 2.3 The Story Pattern for Complex Logic\n\n```markdown\n## The Story of This Algorithm\n\nOnce upon a time, we needed to [problem].\n\nThe first approach was [naive solution], but it had issues:\n- [Problem with approach 1]\n\nSo we tried [alternative], which [worked because...]\n\nThen we discovered [edge case] which broke [previous approach].\n\nFinally, we settled on [current approach] because:\n- It handles [edge case]\n- It's efficient for [use case]\n- It's simple enough to maintain\n\nThe result is what you see today.\n```\n\n### Phase 3: Documentation Generation\n\n#### 3.1 Code Comment Best Practices\n\n```typescript\n\u002F\u002F ❌ BAD: States the obvious\n\u002F\u002F Increment counter\ncounter++;\n\n\u002F\u002F ❌ BAD: Explains HOW (code already does this)\n\u002F\u002F Loop through users array\nusers.forEach(user => {});\n\n\u002F\u002F ✅ GOOD: Explains WHY\n\u002F\u002F Retry logic needed because payment gateway occasionally\n\u002F\u002F returns 503 due to their own scaling events\nconst retryCount = 3;\n\n\u002F\u002F ✅ GOOD: Explains context\n\u002F\u002F Business rule: Orders over $1000 require manual review\n\u002F\u002F This is enforced by the compliance team (see TICKET-123)\nconst MANUAL_REVIEW_THRESHOLD = 1000;\n```\n\n#### 3.2 JSDoc Pattern for Functions\n\n```typescript\n\u002F**\n * Processes a payment for the given amount.\n *\n * @param amount - The payment amount in cents (integer only)\n * @param paymentMethod - The payment method to charge\n * @returns Promise resolving to payment result\n * @throws {PaymentDeclinedError} When payment is declined\n * @throws {InsufficientFundsError} When balance is too low\n *\n * @example\n * const result = await processPayment(5000, card);\n * if (result.success) {\n *   console.log(`Paid ${result.amount}`);\n * }\n *\u002F\nasync function processPayment(\n  amount: number,\n  paymentMethod: PaymentMethod\n): Promise\u003CPaymentResult> {\n  \u002F\u002F Implementation\n}\n```\n\n### Phase 4: Audience-Tailored Explanation\n\n#### 4.1 For a Newcomer\n\n```markdown\n## Understanding the Authentication Flow\n\n**What is authentication?**\nAuthentication answers: \"Who are you?\"\n\n**How our system does it:**\n\n1. User submits email + password\n2. System checks if credentials match\n3. If yes, system creates a \"session\" (like a temporary ID card)\n4. All future requests include this session\n5. System knows who you are from the session\n\n**Why this design?**\n- Passwords are never stored directly (stored as \"hash\")\n- Sessions expire automatically (security)\n- Separate from login means we can log out without losing your identity\n```\n\n#### 4.2 For a Colleague\n\n```markdown\n## Authentication Flow - Technical Summary\n\n**Login flow:**\n1. POST \u002Fauth\u002Flogin with credentials\n2. Verify password against bcrypt hash\n3. Create JWT with 24h expiry\n4. Return token to client\n\n**Token validation:**\n- Middleware extracts Bearer token\n- JWT verified with server secret\n- User ID extracted, attached to request\n- If invalid\u002Fexpired → 401\n\n**Key decisions:**\n- JWT over sessions (stateless, scalable)\n- 24h expiry (balance security\u002Fusability)\n- bcrypt over MD5\u002FSHA1 (cost factor for brute force)\n```\n\n#### 4.3 For an Expert\n\n```markdown\n## Auth Implementation Notes\n\n**JWT Strategy:**\n- RS256 signed (asymmetric)\n- Claims: sub (userId), iat, exp, roles[]\n- Refresh token rotation in separate endpoint\n\n**Security considerations:**\n- Passwords: bcrypt, cost 12\n- Rate limiting: 5 attempts per 15 min per IP\n- Token storage: httpOnly cookie (not localStorage)\n\n**Scaling:**\n- Token validation: stateless, no DB hit\n- Refresh: requires DB, but infrequent\n- Logout: blacklist in Redis (if needed) or short expiry\n```\n\n## Common Scenarios\n\n### Scenario 1: \"What does this function do?\"\n\n```markdown\n## Explanation for \"understand this function\" request\n\n**Function:** processUserRegistration\n\n**One-line answer:** Registers a new user in the system.\n\n**What it does (step by step):**\n1. Validates email format and uniqueness\n2. Hashes password with bcrypt\n3. Creates user record in database\n4. Sends welcome email\n5. Returns created user (without password hash)\n\n**Key edge cases handled:**\n- Duplicate email → throws RegistrationError\n- Weak password → validation rejects\n- Email service down → user still created (email is async)\n\n**What it doesn't do:**\n- Log the user in (separate function)\n- Send verification email (separate flow)\n```\n\n### Scenario 2: \"How does this complex algorithm work?\"\n\n```markdown\n## Dijkstra's Algorithm Implementation - Explained\n\n**Purpose:** Find the shortest path between nodes\n\n**The insight:** At each step, the node with the smallest known distance from start is the next one to process.\n\n**How it works:**\n\n1. Start with source node at distance 0, all others at infinity\n2. Pick the unvisited node with smallest distance (source at start)\n3. For each neighbor, calculate distance through current node\n4. If shorter than known, update that neighbor's distance\n5. Mark current node as visited\n6. Repeat 2-5 until destination visited or all distances settled\n\n**Why this works:** Every node's shortest path goes through nodes with smaller distances first (otherwise there'd be a shorter path).\n\n**Time complexity:** O(V²) naive, O(E log V) with priority queue\n```\n\n### Scenario 3: \"Why was this code written this way?\"\n\n```markdown\n## Historical Context: Why the Cache Layer?\n\n**Current implementation:**\nWe have a two-tier cache: in-memory L1, Redis L2.\n\n**Why this design:**\n\nOriginally (2021), we had only Redis. But we noticed:\n- 90% of reads were the same 10% of data\n- Redis latency (2-5ms) was dominating response times\n- Our API was fast but not fast enough for SLA\n\n**What we tried:**\n1. In-memory cache alone → works locally, but 6 app servers have different caches = inconsistency\n2. Redis only → fast enough for some, but P99 was high\n\n**Solution:** Two-tier cache\n- L1 (in-memory): Very fast, but server-specific\n- L2 (Redis): Consistent, shared between servers\n- Cache-aside pattern: check L1 → miss → check L2 → miss → DB\n\n**Trade-offs accepted:**\n- Memory usage increased (L1 caches)\n- Cache invalidation more complex\n- 1-2ms added latency for L1 misses\n\n**This is documented because new team members keep asking \"why not just Redis?\"**\n```\n\n## Key Principles\n\n### 1. Answer the Why First\n\nPeople want to know WHY code exists before they care HOW it works.\n\n### 2. Match the Audience\n\nThe same code explained to a newcomer vs expert should look very different.\n\n### 3. Use Analogies Wisely\n\n\"Good analogy: Authentication is like a hotel key card system\"\n\"Bad analogy: Authentication is like quantum entanglement\"\n\n### 4. Show, Don't Just Tell\n\nCode examples make abstract descriptions concrete.\n\n### 5. Document the Unusual\n\nIf something looks weird but has a reason, explain it. Future readers will wonder.\n\n### 6. Write for Future You\n\nAssume you'll forget everything in 6 months. Write comments that would help you then.\n\n## Anti-Patterns\n\n### 1. Commenting the Obvious\n\n```typescript\n\u002F\u002F BAD: No new information\n\u002F\u002F Loop through array\narray.forEach(item => doSomething(item));\n\n\u002F\u002F GOOD: Adds context\n\u002F\u002F Retry failed items in separate pass to avoid\n\u002F\u002F compounding failures (if A fails, B succeeds, retry A)\n```\n\n### 2. Outdated Comments\n\n```typescript\n\u002F\u002F ❌ OLD: Comment doesn't match code anymore\n\u002F\u002F Max retries is 3 (changed to 5 last sprint)\n\u002F\u002F [but comment still says 3]\n\n\u002F\u002F Keep comments updated OR delete them\nconst MAX_RETRIES = 5;\n```\n\n### 3. Noisy Comments\n\n```typescript\n\u002F\u002F ❌ BAD: Too many comments\n\u002F\u002F Function starts here\nfunction process() {\n  \u002F\u002F If condition\n  if (x) {\n    \u002F\u002F Do thing\n    doThing();\n  }\n}\n\n\u002F\u002F ✅ GOOD: Meaningful comments\nfunction process() {\n  \u002F\u002F Only process active items (inactive filtered at query level)\n  if (x) {\n    doThing();\n  }\n}\n```\n\n## Relationship to Other Skills\n\n- `code-comment-writer` — Writing effective code comments\n- `generate-diagram-from-code` — Visual explanation of code\n- `documentation-writer` — Creating formal documentation\n- `context-learning` — Learning about a new codebase\n- `code-to-documentation` — Full documentation from code\n","# Explain Code — Code Comprehension Framework\n\n## Overview\n\nExplain-code is a **behavioral specification skill** that encapsulates the methodology for **clearly explaining code to humans**, whether that's documenting for future self, teaching teammates, or creating accessible documentation.\n\nThe core judgment it provides: **\"How do I explain this code so that someone can understand what it does and why?\"**\n\n## Core Philosophy\n\n### The Explanation Paradox\n\n> \"Code explains HOW, but not WHY. Comments explain WHY, but not HOW. Good explanation does both — in the right proportion for the audience.\"\n\nThe best code explanation is the one that answers the question behind the question.\n\n### The Three Levels of Code Understanding\n\n```\n┌─────────────────────────────────────────────────────────────┐\n│                 CODE UNDERSTANDING LEVELS                     │\n│                                                               │\n│  LEVEL 1: SYNTAX                                             │\n│  └─ \"I understand the code structure\"                       │\n│                                                               │\n│  LEVEL 2: BEHAVIOR                                           │\n│  └─ \"I understand what the code does\"                       │\n│                                                               │\n│  LEVEL 3: INTENT                                             │\n│  └─ \"I understand WHY the code does this\"                    │\n│                                                               │\n│  Best explanations address LEVEL 3 first,                    │\n│  then fill in levels 1-2 as needed.                          │\n└─────────────────────────────────────────────────────────────┘\n```\n\n## Decision Framework\n\n### Before Explaining: Audience Analysis\n\n| Question | Audience Adjustment |\n|----------|---------------------|\n| Who's reading? | Expert vs novice |\n| What's their goal? | Understand to use vs modify vs review |\n| What do they already know? | Domain concepts, tech stack |\n| What's their time pressure? | Quick summary vs deep dive |\n| Why are they asking? | Debugging vs learning vs reviewing |\n\n### The Audience Spectrum\n\n```\n┌─────────────────────────────────────────────────────────────────┐\n│                     AUDIENCE ADJUSTMENT                          │\n│                                                                   │\n│  NEWCOMER                   COLLEAGUE                   EXPERT   │\n│  ─────────                  ─────────                  ───────  │\n│  Explain basics             Assume some                Just show │\n│  Define terms               knowledge                  the code   │\n│  Show examples              Focus on interesting       Focus on  │\n│  Connect to concepts        parts                      edge cases │\n│                                                                   │\n│  WHY: Learn                  WHY: Collaborate            WHY: Review│\n└─────────────────────────────────────────────────────────────────┘\n```\n\n## Behavioral Specification\n\n### Phase 1: Code Analysis\n\n#### 1.1 First Read: Understanding Structure\n\n```markdown\n## Code Structure Analysis\n\nFile: paymentProcessor.ts\n\nLines 1-20: Imports and types\nLines 21-50: Helper functions\nLines 51-100: Main processor class\nLines 101-150: Error handling\nLines 151-200: Integration points\n\nInitial observations:\n- Uses class-based design\n- Depends on external payment gateway\n- Has significant error handling\n- ~200 lines suggests single responsibility concern\n```\n\n#### 1.2 Second Read: Understanding Flow\n\n```markdown\n## Execution Flow Analysis\n\npaymentProcessor.charge()\n\nEntry: User provides payment details\n    │\n    ▼\nStep 1: Validate payment data\n    │\n    ▼\nStep 2: Format for gateway API\n    │\n    ▼\nStep 3: Call payment gateway\n    │\n    ▼\nStep 4: Map response to internal format\n    │\n    ▼\nExit: Return payment result\n```\n\n#### 1.3 Third Read: Understanding Intent\n\n```markdown\n## Intent Discovery\n\nQuestions to ask:\n- Why was this approach chosen over alternatives?\n- What business rules are encoded here?\n- What constraints shaped the design?\n- What edge cases is this handling?\n\nClues in the code:\n- Comments mentioning business rules\n- Error handling for specific cases\n- Validation of specific formats\n- Comments referencing external systems\n```\n\n### Phase 2: Explanation Structure\n\n#### 2.1 The Intention-First Pattern\n\n**BAD:**\n```markdown\n\"This function takes a user ID, queries the database for the user,\ncreates an order object, saves it to the database, and returns the order.\"\n```\n\n**GOOD:**\n```markdown\n\"Creates an order for a user.\n\nThe function handles the full order creation flow:\n1. Fetches the user to ensure they exist\n2. Creates an order in PENDING state\n3. Saves to database\n4. Returns the created order\n\nWhy this flow matters: This ensures atomic order creation —\nif any step fails, no partial order is created.\"\n```\n\n#### 2.2 The Purpose-Signature-Body Pattern\n\n```markdown\n## FunctionName: What It Does\n\n**Purpose:** [One sentence describing WHY this exists]\n\n**Signature:**\n```typescript\nfunction processPayment(\n  amount: number,\n  paymentMethod: PaymentMethod\n): Promise\u003CPaymentResult>\n```\n\n**Behavior:**\n1. [Step 1]\n2. [Step 2]\n3. [Returns\u002FThrows]\n\n**Key decisions:**\n- [Why approach X over Y]\n- [Edge cases handled]\n- [Business rules enforced]\n```\n\n#### 2.3 The Story Pattern for Complex Logic\n\n```markdown\n## The Story of This Algorithm\n\nOnce upon a time, we needed to [problem].\n\nThe first approach was [naive solution], but it had issues:\n- [Problem with approach 1]\n\nSo we tried [alternative], which [worked because...]\n\nThen we discovered [edge case] which broke [previous approach].\n\nFinally, we settled on [current approach] because:\n- It handles [edge case]\n- It's efficient for [use case]\n- It's simple enough to maintain\n\nThe result is what you see today.\n```\n\n### Phase 3: Documentation Generation\n\n#### 3.1 Code Comment Best Practices\n\n```typescript\n\u002F\u002F ❌ BAD: States the obvious\n\u002F\u002F Increment counter\ncounter++;\n\n\u002F\u002F ❌ BAD: Explains HOW (code already does this)\n\u002F\u002F Loop through users array\nusers.forEach(user => {});\n\n\u002F\u002F ✅ GOOD: Explains WHY\n\u002F\u002F Retry logic needed because payment gateway occasionally\n\u002F\u002F returns 503 due to their own scaling events\nconst retryCount = 3;\n\n\u002F\u002F ✅ GOOD: Explains context\n\u002F\u002F Business rule: Orders over $1000 require manual review\n\u002F\u002F This is enforced by the compliance team (see TICKET-123)\nconst MANUAL_REVIEW_THRESHOLD = 1000;\n```\n\n#### 3.2 JSDoc Pattern for Functions\n\n```typescript\n\u002F**\n * Processes a payment for the given amount.\n *\n * @param amount - The payment amount in cents (integer only)\n * @param paymentMethod - The payment method to charge\n * @returns Promise resolving to payment result\n * @throws {PaymentDeclinedError} When payment is declined\n * @throws {InsufficientFundsError} When balance is too low\n *\n * @example\n * const result = await processPayment(5000, card);\n * if (result.success) {\n *   console.log(`Paid ${result.amount}`);\n * }\n *\u002F\nasync function processPayment(\n  amount: number,\n  paymentMethod: PaymentMethod\n): Promise\u003CPaymentResult> {\n  \u002F\u002F Implementation\n}\n```\n\n### Phase 4: Audience-Tailored Explanation\n\n#### 4.1 For a Newcomer\n\n```markdown\n## Understanding the Authentication Flow\n\n**What is authentication?**\nAuthentication answers: \"Who are you?\"\n\n**How our system does it:**\n\n1. User submits email + password\n2. System checks if credentials match\n3. If yes, system creates a \"session\" (like a temporary ID card)\n4. All future requests include this session\n5. System knows who you are from the session\n\n**Why this design?**\n- Passwords are never stored directly (stored as \"hash\")\n- Sessions expire automatically (security)\n- Separate from login means we can log out without losing your identity\n```\n\n#### 4.2 For a Colleague\n\n```markdown\n## Authentication Flow - Technical Summary\n\n**Login flow:**\n1. POST \u002Fauth\u002Flogin with credentials\n2. Verify password against bcrypt hash\n3. Create JWT with 24h expiry\n4. Return token to client\n\n**Token validation:**\n- Middleware extracts Bearer token\n- JWT verified with server secret\n- User ID extracted, attached to request\n- If invalid\u002Fexpired → 401\n\n**Key decisions:**\n- JWT over sessions (stateless, scalable)\n- 24h expiry (balance security\u002Fusability)\n- bcrypt over MD5\u002FSHA1 (cost factor for brute force)\n```\n\n#### 4.3 For an Expert\n\n```markdown\n## Auth Implementation Notes\n\n**JWT Strategy:**\n- RS256 signed (asymmetric)\n- Claims: sub (userId), iat, exp, roles[]\n- Refresh token rotation in separate endpoint\n\n**Security considerations:**\n- Passwords: bcrypt, cost 12\n- Rate limiting: 5 attempts per 15 min per IP\n- Token storage: httpOnly cookie (not localStorage)\n\n**Scaling:**\n- Token validation: stateless, no DB hit\n- Refresh: requires DB, but infrequent\n- Logout: blacklist in Redis (if needed) or short expiry\n```\n\n## Common Scenarios\n\n### Scenario 1: \"What does this function do?\"\n\n```markdown\n## Explanation for \"understand this function\" request\n\n**Function:** processUserRegistration\n\n**One-line answer:** Registers a new user in the system.\n\n**What it does (step by step):**\n1. Validates email format and uniqueness\n2. Hashes password with bcrypt\n3. Creates user record in database\n4. Sends welcome email\n5. Returns created user (without password hash)\n\n**Key edge cases handled:**\n- Duplicate email → throws RegistrationError\n- Weak password → validation rejects\n- Email service down → user still created (email is async)\n\n**What it doesn't do:**\n- Log the user in (separate function)\n- Send verification email (separate flow)\n```\n\n### Scenario 2: \"How does this complex algorithm work?\"\n\n```markdown\n## Dijkstra's Algorithm Implementation - Explained\n\n**Purpose:** Find the shortest path between nodes\n\n**The insight:** At each step, the node with the smallest known distance from start is the next one to process.\n\n**How it works:**\n\n1. Start with source node at distance 0, all others at infinity\n2. Pick the unvisited node with smallest distance (source at start)\n3. For each neighbor, calculate distance through current node\n4. If shorter than known, update that neighbor's distance\n5. Mark current node as visited\n6. Repeat 2-5 until destination visited or all distances settled\n\n**Why this works:** Every node's shortest path goes through nodes with smaller distances first (otherwise there'd be a shorter path).\n\n**Time complexity:** O(V²) naive, O(E log V) with priority queue\n```\n\n### Scenario 3: \"Why was this code written this way?\"\n\n```markdown\n## Historical Context: Why the Cache Layer?\n\n**Current implementation:**\nWe have a two-tier cache: in-memory L1, Redis L2.\n\n**Why this design:**\n\nOriginally (2021), we had only Redis. But we noticed:\n- 90% of reads were the same 10% of data\n- Redis latency (2-5ms) was dominating response times\n- Our API was fast but not fast enough for SLA\n\n**What we tried:**\n1. In-memory cache alone → works locally, but 6 app servers have different caches = inconsistency\n2. Redis only → fast enough for some, but P99 was high\n\n**Solution:** Two-tier cache\n- L1 (in-memory): Very fast, but server-specific\n- L2 (Redis): Consistent, shared between servers\n- Cache-aside pattern: check L1 → miss → check L2 → miss → DB\n\n**Trade-offs accepted:**\n- Memory usage increased (L1 caches)\n- Cache invalidation more complex\n- 1-2ms added latency for L1 misses\n\n**This is documented because new team members keep asking \"why not just Redis?\"**\n```\n\n## Key Principles\n\n### 1. Answer the Why First\n\nPeople want to know WHY code exists before they care HOW it works.\n\n### 2. Match the Audience\n\nThe same code explained to a newcomer vs expert should look very different.\n\n### 3. Use Analogies Wisely\n\n\"Good analogy: Authentication is like a hotel key card system\"\n\"Bad analogy: Authentication is like quantum entanglement\"\n\n### 4. Show, Don't Just Tell\n\nCode examples make abstract descriptions concrete.\n\n### 5. Document the Unusual\n\nIf something looks weird but has a reason, explain it. Future readers will wonder.\n\n### 6. Write for Future You\n\nAssume you'll forget everything in 6 months. Write comments that would help you then.\n\n## Anti-Patterns\n\n### 1. Commenting the Obvious\n\n```typescript\n\u002F\u002F BAD: No new information\n\u002F\u002F Loop through array\narray.forEach(item => doSomething(item));\n\n\u002F\u002F GOOD: Adds context\n\u002F\u002F Retry failed items in separate pass to avoid\n\u002F\u002F compounding failures (if A fails, B succeeds, retry A)\n```\n\n### 2. Outdated Comments\n\n```typescript\n\u002F\u002F ❌ OLD: Comment doesn't match code anymore\n\u002F\u002F Max retries is 3 (changed to 5 last sprint)\n\u002F\u002F [but comment still says 3]\n\n\u002F\u002F Keep comments updated OR delete them\nconst MAX_RETRIES = 5;\n```\n\n### 3. Noisy Comments\n\n```typescript\n\u002F\u002F ❌ BAD: Too many comments\n\u002F\u002F Function starts here\nfunction process() {\n  \u002F\u002F If condition\n  if (x) {\n    \u002F\u002F Do thing\n    doThing();\n  }\n}\n\n\u002F\u002F ✅ GOOD: Meaningful comments\nfunction process() {\n  \u002F\u002F Only process active items (inactive filtered at query level)\n  if (x) {\n    doThing();\n  }\n}\n```\n\n## Relationship to Other Skills\n\n- `code-comment-writer` — Writing effective code comments\n- `generate-diagram-from-code` — Visual explanation of code\n- `documentation-writer` — Creating formal documentation\n- `context-learning` — Learning about a new codebase\n- `code-to-documentation` — Full documentation from code\n",{"name":5,"category":46,"priority":53,"description":7,"trigger_patterns":54},"P1",[55,56,57,58,59,60,61],"explain this code","what does this do","how does this work","help me understand","explain this function","code explanation","document this code","main","b9a52d8e27455bdad953d64928696d028223ea1b","skills\u002Fcoding\u002Fexplain-code","https:\u002F\u002Fgithub.com\u002FImaginerLabs\u002Fskill-manager","https:\u002F\u002Fgithub.com\u002FImaginerLabs","2026-04-18 16:27:13",{"source":8,"skillName":5,"commands":69,"prompt":79,"zipAvailable":80},[70,73,76],{"tool":71,"command":72},"npx","npx skills add ImaginerLabs\u002Fskill-manager --skill explain-code",{"tool":74,"command":75},"bunx","bunx skills add ImaginerLabs\u002Fskill-manager --skill explain-code",{"tool":77,"command":78},"pnpm","pnpm dlx skills add ImaginerLabs\u002Fskill-manager --skill explain-code","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002FImaginerLabs\u002Fskill-manager\u002Fblob\u002Fmain\u002Fskills\u002Fcoding\u002Fexplain-code\u002FSKILL.md",true,[],[83,113,134,162,195,221],{"skillNo":84,"name":85,"nameZh":6,"description":86,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":87,"categories":88,"keywords":95,"publishedAt":48},"01M6QJCB2SD5KHC41ZDQC0GA1T","meeting-minutes","Generate concise, actionable meeting minutes for internal meetings. Includes metadata, attendees, agenda, decisions, action items (owner + due date), and follow-up steps.","https:\u002F\u002Fgithub.com\u002FImaginerLabs\u002Fskill-manager\u002Fblob\u002Fmain\u002Fskills\u002Fwriting\u002Fmeeting-minutes\u002FSKILL.md",[89,92],{"categoryNo":90,"categoryName":91,"taxonomyType":20,"taxonomyTypeDesc":21},"01JBSEEDCAT000000000000023","Skill与智能体开发",{"categoryNo":93,"categoryName":94,"taxonomyType":25,"taxonomyTypeDesc":26},"01JBSEEDCAT000000000000034","行政与办公人员",[96,97,98,99,100,101,102,103,104,105,85,62,106,107,108,109,110,111,112,32],"meeting minutes","meeting","minutes","writing","github","copilot","generate","decisions","meetings","up","agenda","actionable","concise","follow-up","tree","true","action",{"skillNo":114,"name":115,"nameZh":6,"description":116,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":117,"categories":118,"keywords":119,"publishedAt":48},"01M6QJC71RRGTGNNFEHJG6S20G","documentation-writer","Diátaxis Documentation Expert. An expert technical writer specializing in creating high-quality software documentation, guided by the principles and structure of the Diátaxis technical documentation authoring framework.","https:\u002F\u002Fgithub.com\u002FImaginerLabs\u002Fskill-manager\u002Fblob\u002Fmain\u002Fskills\u002Fwriting\u002Fdocumentation-writer\u002FSKILL.md",[],[120,121,122,99,100,101,123,124,125,126,127,128,62,129,130,131,132,110,111,133],"documentation","documentation writer","writer","https","quality","technical","technical writer","expert","documentation expert","structure","authoring","software","principles","high",{"skillNo":135,"name":136,"nameZh":6,"description":137,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":138,"categories":139,"keywords":147,"publishedAt":48},"01M6QJC0V3C7C4R9768J1AJYWY","doc-coauthoring","Guide users through a structured workflow for co-authoring documentation. Use when user wants to write documentation, proposals, technical specs, decision docs, or similar structured content. This workflow helps users efficiently transfer context, refine content through iteration, and verify the doc works for readers. Trigger when user mentions writing docs, creating proposals, drafting specs, or similar documentation tasks.","https:\u002F\u002Fgithub.com\u002FImaginerLabs\u002Fskill-manager\u002Fblob\u002Fmain\u002Fskills\u002Fwriting\u002Fdoc-coauthoring\u002FSKILL.md",[140,143,144],{"categoryNo":141,"categoryName":142,"taxonomyType":20,"taxonomyTypeDesc":21},"01JBSEEDCAT000000000000018","写作与文案",{"categoryNo":90,"categoryName":91,"taxonomyType":20,"taxonomyTypeDesc":21},{"categoryNo":145,"categoryName":146,"taxonomyType":25,"taxonomyTypeDesc":26},"01JBSEEDCAT000000000000036","内容创作者",[148,149,99,150,151,120,152,153,154,155,156,157,62,158,159,130,160,161,110,32],"doc coauthoring","doc","workflow","official","tasks","decision","write","context","proposals","guide","refine","iteration","trigger","co",{"skillNo":163,"name":164,"nameZh":6,"description":165,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":166,"categories":167,"keywords":176,"publishedAt":48},"01M6QJBJ0YPVEWGEXZH3PJRRTT","code-review-workflow","Executes comprehensive 4-phase code review: basic review, quality check, bundle analysis, and test coverage. Should be used when the user mentions comprehensive code review, checking code quality, or reviewing staged changes with multi-phase analysis. This is the comprehensive review workflow, distinct from focused skills like frontend-code-review, staged-code-review, or code-change-test-designer.","https:\u002F\u002Fgithub.com\u002FImaginerLabs\u002Fskill-manager\u002Fblob\u002Fmain\u002Fskills\u002Ftesting\u002Fcode-review-workflow\u002FSKILL.md",[168,171,174,175],{"categoryNo":169,"categoryName":170,"taxonomyType":20,"taxonomyTypeDesc":21},"01JBSEEDCAT000000000000007","代码审查",{"categoryNo":172,"categoryName":173,"taxonomyType":20,"taxonomyTypeDesc":21},"01JBSEEDCAT000000000000008","测试与质量",{"categoryNo":90,"categoryName":91,"taxonomyType":20,"taxonomyTypeDesc":21},{"categoryNo":23,"categoryName":24,"taxonomyType":25,"taxonomyTypeDesc":26},[177,178,150,29,179,180,181,182,183,184,185,186,187,188,189,190,191,192,193,194],"code review","review","code review workflow","testing","frontend","test","change","code quality","code-review","analysis","check","coverage","quality check","basic","multi","comprehensive code review","with","phase",{"skillNo":196,"name":197,"nameZh":6,"description":198,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":199,"categories":200,"keywords":210,"publishedAt":48},"01M6QJB7XNHV3VEEQF4W7FMWF6","code-change-test-designer","Analyzes code changes and designs comprehensive test cases. Reads diffs, summarizes capability changes, and designs test cases covering main flows and edge cases. Should be used when the user mentions test coverage, designing tests for code changes, or analyzing diff\u002Fcommit for testing purposes. Distinguished from code-review-workflow which provides comprehensive review, this skill focuses on test case design for code changes.","https:\u002F\u002Fgithub.com\u002FImaginerLabs\u002Fskill-manager\u002Fblob\u002Fmain\u002Fskills\u002Ftesting\u002Fcode-change-test-designer\u002FSKILL.md",[201,202,205,206,207],{"categoryNo":172,"categoryName":173,"taxonomyType":20,"taxonomyTypeDesc":21},{"categoryNo":203,"categoryName":204,"taxonomyType":20,"taxonomyTypeDesc":21},"01JBSEEDCAT000000000000015","视觉设计",{"categoryNo":90,"categoryName":91,"taxonomyType":20,"taxonomyTypeDesc":21},{"categoryNo":23,"categoryName":24,"taxonomyType":25,"taxonomyTypeDesc":26},{"categoryNo":208,"categoryName":209,"taxonomyType":25,"taxonomyTypeDesc":26},"01JBSEEDCAT000000000000032","设计师",[182,183,29,211,212,180,213,214,150,215,185,216,188,217,62,218,219,220,32,194],"designer","code change test designer","design","diffs","commit","edge","diff","tests","flows","which",{"skillNo":222,"name":223,"nameZh":6,"description":224,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":225,"categories":226,"keywords":228,"publishedAt":48},"01M6QJB195WD7DCJWDMKWKB29S","skill-creator","Create new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy.","https:\u002F\u002Fgithub.com\u002FImaginerLabs\u002Fskill-manager\u002Fblob\u002Fmain\u002Fskills\u002Fmeta-skills\u002Fskill-creator\u002FSKILL.md",[227],{"categoryNo":90,"categoryName":91,"taxonomyType":20,"taxonomyTypeDesc":21},[229,230,231,232,151,233,234,235,236,237,186,238,239,240,62,241,242,110,32,223],"skill creator","creator","performance","run evals","variance analysis","create","run","benchmark","Meta","improve","edit","evals","optimize","existing skill"]