Initial commit

2025-11-30 09:05:19 +08:00
commit 09fec2555b
96 changed files with 24269 additions and 0 deletions
--- a/skills/documentation-tutorial/SKILL.md
+++ b/skills/documentation-tutorial/SKILL.md
@@ -0,0 +1,378 @@
+---
+name: documentation-tutorial
+description: Build hands-on, code-first tutorials from any primary source - technical documentation, codebases, APIs, tools, or other complex material. Extract real examples, working code, and concrete scenarios. Create tutorials using markdown (text-heavy summaries) or React artifacts (complex interactive workflows). Keywords - tutorial, codebase, API, hands-on, code-first, copy-paste, interactive, real examples, primary source
+---
+
+# Tutorial Developer from Primary Sources
+
+Transform any primary source into hands-on, practical tutorials that prioritize real, working examples over conceptual explanations. Focus on what users need to *do*, not what they need to understand.
+
+## Quick Decision Guide
+
+**Step 1: Choose format**
+- Text-heavy summary or CLI reference → Markdown
+- Complex workflow with multiple steps → React Artifact
+
+**Step 2: Follow the three pillars**
+1. Real code/commands (not pseudocode)
+2. Real use cases (concrete scenarios)
+3. Mental model (one-sentence explanation)
+
+## Core Principles
+
+### The Three Pillars
+
+Every tutorial must clearly answer:
+
+1. **Real Code**: What's the actual code or command I run? (Copy-paste executable, no pseudocode)
+2. **Real Use Cases**: When would I actually use this? (Concrete scenarios like "healthcare bot", not vague descriptions)
+3. **Mental Model**: How does this work? (One-sentence explanation enabling independent problem-solving)
+
+**Example:**
+```
+Mental Model: "AI generates interactive React components from natural language prompts, streaming in real-time."
+
+Code:
+curl -X POST https://api.thesys.dev/v1/ui/generate \
+  -H "Authorization: Bearer sk-thesys-key" \
+  -d '{"prompt": "Create a booking form", "model": "gpt-4"}'
+
+Use Case: When you want users to book appointments without writing React,
+send a prompt and stream the form directly into the page.
+```
+
+### Code-First Approach
+
+- Lead with working examples, not theory
+- Real endpoints (actual URLs, not `<placeholder>`)
+- Exact payloads (complete JSON, not simplified)
+- No high-level summaries unless essential
+- Get users to running code within 5 minutes
+
+## Systematic Workflow
+
+### Phase 1: Extract from Primary Source
+
+**Step 1: Identify Core Mental Model**
+
+Answer: *"What's the one-sentence explanation that makes everything click?"*
+
+Examples:
+- API: "AI generates interactive UIs from prompts, streaming real-time"
+- Tool: "PDFs are structured data; extract tables/text like CSV/JSON"
+- Codebase: "Request flows through middleware → router → handler → response"
+- Academic Paper: "YouTube Data API v3 lets you search videos, get metadata, and filter by captions/views/category using REST endpoints"
+
+### Primary Source Types
+
+**Documentation:** Official API docs, SDK references, CLI manuals
+
+**Codebases:** Open source projects, example repos
+
+**Tools:** Software applications, command-line utilities
+
+**Academic Papers:** Research methodologies in appendices/supplementary materials
+- Look for: Data collection procedures, API workflows, filtering criteria, implementation details
+- Example: MINEDOJO paper Appendix D.1 documents exact YouTube API usage with 5-step workflow
+- Extract: Step-by-step procedures, quota limits, legal considerations, real filtering parameters
+- Value: More rigorous methodology than typical blog posts, validated by peer review
+
+**Step 2: Find Real Examples**
+
+Extract from docs/code:
+- Working code (not pseudocode)
+- CLI commands with actual flags
+- API calls (curl + request/response)
+- Config files, error cases
+
+**Step 3: Extract Concrete Use Cases**
+
+❌ **Wrong:** "Can be used for various applications like analytics, reporting, etc."
+
+✅ **Right:**
+1. **Analytics Dashboard**: User asks "show me sales by region" → AI generates chart
+2. **Booking Flow**: Customer books appointment → form auto-generates with calendar
+3. **Support Tickets**: Agent asks "show ticket queue" → interactive table generates
+
+For each: What triggers it, what code is needed, what user sees, why it matters.
+
+### Phase 2: Structure Tutorial
+
+**Step 4: Plan Sections** (Action-oriented names)
+- Section 1: "⚙️ Setup & Install" → Running in 5 minutes
+- Section 2: "🚀 First API Call" → Verify it works
+- Section 3: "🌐 Core Operations" → Major endpoints
+- Section 4: "🐍 SDK Examples" → Language-specific code
+- Section 5: "💾 Real Scenario" → Complete workflow
+
+**Step 5: Plan Code Blocks**
+- Copy-paste executable curl with real endpoint
+- Tabs: cURL → Request Body → Response
+- Real data values (names, dates, actual fields)
+- Error cases if documented
+
+**Step 6: Plan Workflow**
+- Choose actual use case from documentation
+- Break into 3-5 sequential API calls
+- Show how responses flow into next step
+
+### Phase 3: Implement
+
+**Step 7: For React Artifacts**
+
+Structure:
+- Sidebar navigation (6-8 focused sections)
+- Main content area with code blocks
+- Copy buttons on all code
+- Tabbed views (curl/request/response)
+
+**Step 8: Code Block Spec**
+- Dark background, language label, copy button
+- Left-aligned monospace, syntax highlighting
+- No line numbers (confuses copy-paste)
+
+**Step 9: Quality Check** (see checklist at end)
+
+## Tutorial Patterns
+
+### Pattern: API Endpoints
+```
+TITLE: Endpoint Name (POST /v1/endpoint)
+DESCRIPTION: One sentence
+CODE BLOCK: Tabs (cURL | Request | Response)
+USE CASE: One sentence + real scenario
+```
+
+### Pattern: Complete Workflows
+```
+STEP 1: First API Call
+  Context (1 sentence) → Code → Result
+STEP 2: Second API Call
+  Context (how previous flows here) → Code → Result
+STEP 3: Final Outcome
+```
+
+### Pattern: Setup/Installation
+```
+PREREQUISITES: What they need
+COMMAND: Full copy-paste command
+VERIFY: One-line check
+TROUBLESHOOTING: Common issues
+```
+
+### Pattern: SDK Examples
+```
+LANGUAGE: Python/JavaScript/etc
+CODE: Full working function (imports, async/await, error handling)
+RUN IT: How to execute
+OUTPUT: Expected result
+```
+
+### Pattern: Sidebar Navigation
+- 6-8 focused sections (not monolithic)
+- Emoji + action verbs: "⚙️ Setup", "🚀 First Call"
+- Reduces cognitive load, improves completion
+
+### Pattern: Copy Buttons
+- One-click copy-to-clipboard (right corner)
+- Visual feedback when copied (checkmark, 2 seconds)
+- 3x higher code execution rate
+
+### Pattern: Mental Models First
+- Present one-sentence model after first working example
+- Place in colored box: "💡 How This Works"
+- Enables independent problem-solving
+
+### Pattern: Progressive Disclosure
+- Section 1: Minimum to get running
+- Section 2: Simplest successful request
+- Section 3-4: Core operations, multiple languages
+- Section 5: Complete multi-step workflow
+- Section 6: Advanced features
+- Section 7: Troubleshooting
+
+### Pattern: Concrete Use Cases
+```
+## Common Use Cases
+
+1. **Analytics Dashboard** (5 min read)
+   You want users to ask "show me Q3 revenue"
+   → AI generates interactive chart
+
+2. **Booking Form** (7 min read)
+   You need booking flow without React
+   → AI generates form with calendar
+
+[Pick your use case →]
+```
+
+Benefit: Users self-select relevant tutorial path.
+
+### Pattern: Troubleshooting
+- Color-coded sections (red=critical, yellow=common)
+- For each: Problem → Root cause → Solution → Code
+- Include CORS, auth failures, timeouts
+
+## Quality Checklist
+
+**Three Pillars:**
+- [ ] Real code (copy-paste executable: curl, Python, JavaScript)
+- [ ] Real use cases (3-5 concrete scenarios, not "theoretical")
+- [ ] Mental model (one-sentence explanation)
+
+**Code Quality:**
+- [ ] Real endpoints (no `<placeholder>`)
+- [ ] Real data (Sarah Chen, 2025-11-15, actual field names)
+- [ ] Tabs: cURL + Request + Response
+- [ ] Left-aligned, properly formatted
+
+**Structure:**
+- [ ] First section: Running code in <5 minutes
+- [ ] 6-8 focused sections with navigation
+- [ ] Complete workflow (form → submit → confirm)
+- [ ] Multiple languages (Python, JavaScript, HTTP)
+
+**Content:**
+- [ ] Mental model within first 2 examples
+- [ ] No conceptual fluff or "learning objectives"
+- [ ] Real-world scenario shows data flowing
+- [ ] Troubleshooting with real problems
+
+**Interactive (for React artifacts):**
+- [ ] Copy buttons on all code
+- [ ] Users can complete real task after tutorial
+
+## Real Examples
+
+### Example 1: Mail Command (Markdown)
+**Why Markdown:** CLI reference with many commands
+
+**Structure:** Basic Sending → Advanced Options → Interactive Mode → Reading Mail → Configuration → Gmail Integration → Quick Reference
+
+**Key Features:** Copy-paste commands, real config files, organized by workflow
+
+### Example 2: Thesys C1 API (React Artifact)
+**Why React:** Complex API needing interactive tabs/navigation
+
+**Structure:** Setup (5min) → First Call → Core Operations → SDK Examples → Real Scenario → Advanced → Troubleshooting
+
+**Key Features:** Sidebar navigation, copy buttons, tabbed views, real data, workflow chaining
+
+## Academic Study Guides: Quote Integration
+
+Same principle applies to academic primary sources (historical documents, philosophical texts, legal cases): transform into practical guide.
+
+### Core Principle
+Embed quotes throughout analysis where they support arguments. NOT collected at end.
+
+### Pattern
+```
+Question → Quote → Interpretation → Quote → Synthesis
+
+NOT: Question → Summary → All Quotes at End
+```
+
+### Example
+```markdown
+## Was Qianlong's Response Wise?
+
+Qianlong defended sovereignty. He explained:
+
+> "If other nations imitate your evil example... how could I possibly comply?"
+
+His reasoning was sound: granting Britain privileges would force him to grant all nations the same.
+
+However, his rejection showed complacency:
+
+> "Strange and costly objects do not interest me."
+
+By dismissing British technology, he missed intelligence-gathering opportunities.
+```
+
+### Debate Format
+1. Clear position
+2. 8-10 numbered arguments (each with quote evidence)
+3. Rebuttals section
+4. Conclusion
+
+**Each argument:** Claim → Quote → Interpret → Connect to thesis
+
+### Checklist
+- [ ] Quotes embedded at point of analysis
+- [ ] Every claim supported by quote
+- [ ] Each quote followed by interpretation
+- [ ] Creates "guide through sources"
+
+## File Organization
+
+**CRITICAL:** All tutorials follow this organization pattern:
+
+### 1. Markdown Tutorials → claude_files/tutorial/
+
+```bash
+# Create in project's claude_files/tutorial directory
+mkdir -p claude_files/tutorial
+
+# Create tutorial file there
+# Example: claude_files/tutorial/youtube-data-api.md
+```
+
+**Naming convention:**
+- Lowercase, kebab-case
+- Descriptive: `{technology}-{purpose}.md`
+- Examples: `youtube-data-api.md`, `python-cli-tutorial.md`, `docker-compose-guide.md`
+
+### 2. HTML Tutorials → claude_files/html/
+
+```bash
+# Create in project's claude_files/html directory
+mkdir -p claude_files/html
+
+# Create HTML file there
+# Example: claude_files/html/youtube-data-tutorial.html
+```
+
+**Naming convention:**
+- Lowercase, kebab-case
+- Descriptive: `{technology}-{purpose}.html`
+- Examples: `youtube-data-tutorial.html`, `api-comparison.html`
+
+### 3. Why This Pattern?
+
+1. **Project-specific** - Tutorials live with the code they document
+2. **Version controlled** - Part of the project, tracked in git
+3. **Self-contained** - Everything in `claude_files/` for easy cleanup
+4. **Consistent location** - Always `claude_files/tutorial/` or `claude_files/html/`
+5. **No symlinks** - Direct files, no complicated linking
+
+### Workflow
+
+When creating a tutorial:
+
+**Markdown:**
+1. Run: `mkdir -p claude_files/tutorial`
+2. Create: `claude_files/tutorial/{name}.md`
+3. Preview: `nvim -c "MarkdownPreview" claude_files/tutorial/{name}.md`
+
+**HTML:**
+1. Run: `mkdir -p claude_files/html`
+2. Create: `claude_files/html/{name}.html`
+3. Open: `open claude_files/html/{name}.html`
+
+## Tools & Preview
+
+**Build:** building-artifacts skill (React + Tailwind + shadcn/ui)
+**Format:** Dark code blocks with copy buttons, monospace
+**Layout:** Sidebar + main content
+
+**Preview markdown tutorials:**
+
+**CRITICAL:** Always open markdown tutorials with preview immediately after creation.
+
+```bash
+nvim -c "MarkdownPreview" /path/to/tutorial.md
+```
+
+This provides instant visual feedback and allows the user to review formatting, code blocks, and overall structure in the rendered view.
+
+Use direct commands (no aliases) for reproducibility.