detailed-explanation

SKILL.md

---
name: detailed-explanation
description: Provide comprehensive, in-depth explanations with code references, examples, and step-by-step analysis. Use when user asks for "detailed explanation", "详细解释", "explain in depth", "tell me everything about", or wants thorough understanding of a topic, code, or process. Also use when user requests to create a skill based on a detailed answer style.
---

# Detailed Explanation Skill

This skill provides comprehensive, in-depth explanations with code references, examples, and step-by-step analysis.

## When to Use This Skill

Use this skill when:
- User asks for "详细解释", "detailed explanation", "explain in depth"
- User wants thorough understanding of a topic, code, or process
- User requests "像刚才那样解释" (explain like you just did)
- User wants to convert an explanation style into a skill
- Complex technical concepts need thorough breakdown

## Response Style Guide

### 1. Code Reference with Line Numbers

Always reference code locations using markdown link format:
- Single file: `[filename.ts](src/filename.ts)`
- Specific line: `[filename.ts:123](src/filename.ts#L123)`
- Line range: `[filename.ts:100-150](src/filename.ts#L100-L150)`

Example:
```
The key logic is in [workspace.ts:293](src/agents/skills/workspace.ts#L293):
```

### 2. Code Snippet Analysis

Break down code into understandable parts:
```typescript
// Explain what each section does
function loadSkillEntries(workspaceDir: string, opts?: Options): SkillEntry[] {
  // Part 1: Get configuration limits
  const limits = resolveSkillsLimits(opts?.config);

  // Part 2: Load skills from different sources
  const loadSkills = (params: { dir: string; source: string }): Skill[] => {
    // ...
  };
}
```

### 3. Flow Diagram / Step Breakdown

Use ASCII art or bullet points to show flow:
```
Step 1: Message arrives
    ↓
Step 2: handleOpenAiHttpRequest
    ↓
Step 3: agentCommandFromIngress
    ↓
Step 4: loadSkillEntries ← [you are here]
```

Or use table format:
| Step | Function | Description |
|------|----------|-------------|
| 1 | handleOpenAiHttpRequest | Entry point |
| 2 | agentCommandFromIngress | Process command |
| 3 | loadSkillEntries | Load skills |

### 4. Example-Driven Explanation

Always include concrete examples:
- Before explaining abstract concept, show a real example
- Use "假设用户输入..." to set scenario
- Show actual input/output

Example:
```
User input: "帮我创建一个管理 GitHub Issues 的 skill"

Step 1: AI analyzes requirements
Step 2: Plan resources:
  - scripts/: create_issue.py, update_issue.py
  - references/: labels.md, workflows.md
Step 3: Run init_skill.py
```

### 5. Table Comparison

Use tables for comparisons:
| Aspect | Old Approach | New Approach |
|--------|-------------|--------------|
| Format | Plain text | Markdown with links |
| Code ref | Line number only | Clickable links |
| Examples | Missing | Always included |

### 6. Background & Rationale

Explain "why" not just "what":
- Why is this design chosen?
- What problems does it solve?
- What are the trade-offs?

### 7. Edge Cases & Boundaries

Always mention:
- What are the limits?
- What happens at boundaries?
- Error conditions?
- Security considerations?

Example:
```
Note: The validation has these limits:
- name: max 64 characters
- description: max 1024 characters
- No symlinks allowed in packaged skill
```

### 8. Real-World Application

Show practical scenarios:
- How is this used in production?
- Common use cases
- Debugging tips

### 9. Follow-up Questions

End with offers to go deeper:
- "需要我深入解释某个具体方面吗？"
- "你想了解这个流程中的哪一部分更详细？"
- "需要我举一个具体的例子吗？"

### 10. Summary Points

End with key takeaways:
```
## 总结

- loadSkillEntries 从 6 个来源加载 skills
- 优先级: extra < bundled < managed < personal < project < workspace
- 验证通过 quick_validate.py 进行
- 最终打包成 .skill (zip) 文件
```

## Skill Creation Template

When user wants to convert an explanation into a skill, follow this template:

### 1. Analyze the Explanation Style

Identify key characteristics:
- Code reference pattern
- Example usage
- Flow breakdown method
- Table usage
- Summary approach

### 2. Structure the Skill

```
skill-name/
├── SKILL.md           # Main skill definition
├── scripts/           # Helper scripts if needed
└── references/        # Additional docs
```

### 3. Write SKILL.md

Include:
- Frontmatter (name, description)
- Core principles
- Step-by-step process
- Code examples
- Edge cases
- Common patterns

## Quality Checklist

Before responding, verify:
- [ ] Code references include line numbers with links
- [ ] Complex code has inline comments
- [ ] Flow is visualized (table or ASCII)
- [ ] Real examples are included
- [ ] Background/rationale is explained
- [ ] Edge cases are covered
- [ ] Summary is provided
- [ ] Follow-up offer is made

## Trigger Keywords

Chinese:
- 详细解释
- 详细说说
- 深入解释
- 完整流程
- 怎么运行的
- 帮我写成 skill

English:
- detailed explanation
- explain in depth
- tell me everything about
- how does it work
- walk me through
- create a skill from this

## Response Language

Match the user's language:
- If user writes in Chinese, respond in Chinese
- If user writes in English, respond in English
- Use consistent terminology throughout