opencode-skills-collection 4.0.52 → 4.0.54

package/bundled-skills/technical-tutorials/SKILL.md

@@ -11,78 +11,17 @@ license_source: https://github.com/jonathimer/devmarketing-skills/blob/main/LICE
 ---
 
 # Technical Tutorials
-## When to Use
-
-Use this skill when you need when the user wants to create step-by-step technical tutorials, quickstarts, or code walkthroughs. Trigger phrases include "tutorial," "quickstart," "getting started guide," "walkthrough," "step by step," "how to guide," "hands-on guide," or "code tutorial.".
-
 
-This skill helps you create step-by-step tutorials that actually work. Covers prerequisite handling, progressive complexity, troubleshooting sections, and creating those satisfying "it works!" moments.
-
----
-
-## Before You Start
-
-**Load your audience context first.** Read `.agents/developer-audience-context.md` to understand:
-
-- Developer skill level (beginner, intermediate, senior)
-- Tech stack familiarity (what can you assume they know?)
-- Environment (macOS, Linux, Windows, cloud)
-- Why they're learning (job, side project, curiosity)
-
-If the context file doesn't exist, run the `developer-audience-context` skill first.
-
----
+## Detailed Guide
 
-## Tutorial Types
+Read [the detailed guide](references/detailed-guide.md) before executing this skill. It retains the complete procedure and reference material. Treat its safety, prerequisites, and validation requirements as mandatory. For focused work, load the relevant sections; for end-to-end work, read the guide completely.
 
-| Type | Length | Purpose | Example |
-|------|--------|---------|---------|
-| **Quickstart** | 5-10 min | First success ASAP | "Make your first API call" |
-| **Tutorial** | 20-45 min | Learn a concept deeply | "Build a REST API with Node.js" |
-| **Workshop** | 1-3 hours | Comprehensive project | "Build a full-stack app" |
-| **Code walkthrough** | Varies | Explain existing code | "Understanding our SDK architecture" |
-
----
+## When to Use
 
-## The Tutorial Structure
+Use this skill when you need when the user wants to create step-by-step technical tutorials, quickstarts, or code walkthroughs. Trigger phrases include "tutorial," "quickstart," "getting started guide," "walkthrough," "step by step," "how to guide," "hands-on guide," or "code tutorial.".
 
-### Anatomy of a Great Tutorial
 
-```
-1. Title & Meta
-   - What you'll build
-   - Time estimate
-   - Prerequisites
-
-2. Overview
-   - What you'll learn
-   - Final result preview
-
-3. Prerequisites Check
-   - Environment setup
-   - Verification commands
-
-4. The Build (Progressive Steps)
-   - Step 1: Simplest foundation
-   - Step 2: Add one concept
-   - Step 3: Add complexity
-   - [Checkpoint: "It works!" moment]
-   - Step 4: Continue building
-   - ...
-   - [Final checkpoint]
-
-5. What You Built
-   - Recap
-   - Complete code
-
-6. Troubleshooting
-   - Common errors
-   - Debugging tips
-
-7. Next Steps
-   - Where to go from here
-   - Related tutorials
-```
+This skill helps you create step-by-step tutorials that actually work. Covers prerequisite handling, progressive complexity, troubleshooting sections, and creating those satisfying "it works!" moments.
 
 ---
 
@@ -157,423 +96,6 @@ Expected output: `Express installed!`
 
 ---
 
-## Progressive Complexity
-
-### The Layer Cake Approach
-
-Build up in understandable layers:
-
-| Layer | What It Does | Example |
-|-------|--------------|---------|
-| **1. Skeleton** | Minimum viable code that runs | "Hello World" server |
-| **2. Core feature** | Primary functionality | Add one API endpoint |
-| **3. Real data** | Replace hardcoded values | Connect to database |
-| **4. Error handling** | Production-ready patterns | Add try/catch, validation |
-| **5. Polish** | Nice-to-haves | Logging, config, tests |
-
-### Show Progress, Not Perfection
-
-**Wrong approach** (overwhelming):
-```javascript
-// Here's the complete file with everything
-const express = require('express');
-const { Pool } = require('pg');
-const helmet = require('helmet');
-const rateLimit = require('express-rate-limit');
-const winston = require('winston');
-// ... 200 more lines
-```
-
-**Right approach** (progressive):
-
-**Step 1: Basic server**
-```javascript
-const express = require('express');
-const app = express();
-
-app.get('/', (req, res) => {
-  res.send('Hello World!');
-});
-
-app.listen(3000, () => {
-  console.log('Server running on http://localhost:3000');
-});
-```
-
-**Step 2: Add your first route**
-```javascript
-// Add this below your existing route
-app.get('/api/users', (req, res) => {
-  res.json([{ id: 1, name: 'Jane' }]);
-});
-```
-
----
-
-## Copy-Paste Friendly Code
-
-### The Copy-Paste Checklist
-
-Every code block must pass these tests:
-
-| Test | How to Verify |
-|------|---------------|
-| **Runs standalone** | Copy into new file, execute, it works |
-| **Imports included** | All `require`/`import` statements present |
-| **No undefined variables** | No references to code from other steps without showing it |
-| **Environment agnostic** | Works on Mac/Linux/Windows |
-| **Comments explain why** | Not what (code shows what), but why |
-
-### Code Block Patterns
-
-**File context is critical:**
-
-```javascript
-// server.js - Add this to your existing file
-const rateLimit = require('express-rate-limit');
-
-// Add this BEFORE your routes
-const limiter = rateLimit({
-  windowMs: 15 * 60 * 1000, // 15 minutes
-  max: 100 // limit each IP to 100 requests per window
-});
-
-app.use(limiter);
-```
-
-**Show file structure:**
-
-```
-my-project/
-├── src/
-│   ├── index.js      ← You're editing this
-│   ├── routes/
-│   │   └── users.js
-│   └── db/
-│       └── connection.js
-├── package.json
-└── .env
-```
-
-**Highlight changes in context:**
-
-```javascript
-// src/index.js
-const express = require('express');
-const app = express();
-
-// ✅ ADD THIS: Import your new route
-const userRoutes = require('./routes/users');
-
-// ✅ ADD THIS: Use the route
-app.use('/api/users', userRoutes);
-
-app.listen(3000);
-```
-
----
-
-## "It Works!" Moments
-
-### Checkpoints Create Motivation
-
-Every 3-5 steps, give developers a win:
-
-```markdown
-## Checkpoint: Test Your API
-
-Let's make sure everything works before continuing.
-
-**Start your server:**
-\`\`\`bash
-node server.js
-\`\`\`
-
-**In a new terminal, test the endpoint:**
-\`\`\`bash
-curl http://localhost:3000/api/users
-\`\`\`
-
-**You should see:**
-\`\`\`json
-[{"id": 1, "name": "Jane"}]
-\`\`\`
-
-🎉 **It works!** Your API is returning data.
-
-If you don't see this output, check the [Troubleshooting](#troubleshooting) section.
-```
-
-### Visual Confirmation
-
-When possible, show what success looks like:
-
-| Output Type | How to Show |
-|-------------|-------------|
-| **Terminal output** | Code block with expected text |
-| **Browser result** | Screenshot or description |
-| **API response** | Formatted JSON |
-| **Logs** | Code block with log output |
-
----
-
-## Troubleshooting Sections
-
-### Common Error Template
-
-```markdown
-## Troubleshooting
-
-### "Error: Cannot find module 'express'"
-
-**Cause:** Dependencies weren't installed.
-
-**Fix:**
-\`\`\`bash
-npm install
-\`\`\`
-
----
-
-### "EADDRINUSE: address already in use :::3000"
-
-**Cause:** Another process is using port 3000.
-
-**Fix (macOS/Linux):**
-\`\`\`bash
-# Find the process
-lsof -i :3000
-
-# Kill it (replace PID with actual number)
-kill -9 PID
-\`\`\`
-
-**Or use a different port:**
-\`\`\`javascript
-app.listen(process.env.PORT || 3001);
-\`\`\`
-
----
-
-### "SyntaxError: Unexpected token"
-
-**Cause:** Likely a typo or missing bracket.
-
-**Debug steps:**
-1. Check the line number in the error
-2. Look for missing `,`, `}`, or `)`
-3. Verify all strings are closed with matching quotes
-```
-
-### Proactive Error Prevention
-
-Add warnings before common pitfalls:
-
-```markdown
-⚠️ **Windows users:** Use `set` instead of `export`:
-\`\`\`bash
-# macOS/Linux
-export API_KEY=your_key
-
-# Windows Command Prompt
-set API_KEY=your_key
-
-# Windows PowerShell
-$env:API_KEY = Read-Host -AsSecureString "API key"
-\`\`\`
-```
-
----
-
-## Tutorial Templates
-
-### Quickstart Template (5-10 minutes)
-
-```markdown
-# [Product] Quickstart: [What You'll Do] in 5 Minutes
-
-Get [specific outcome] in under 5 minutes.
-
-## Prerequisites
-
-- [Requirement 1]
-- [Requirement 2]
-
-## Step 1: Install
-
-\`\`\`bash
-npm install your-package
-\`\`\`
-
-## Step 2: Configure
-
-Create a `.env` file:
-\`\`\`
-API_KEY=your_key_here
-\`\`\`
-
-## Step 3: Write Code
-
-Create `index.js`:
-\`\`\`javascript
-// Complete, working code
-\`\`\`
-
-## Step 4: Run It
-
-\`\`\`bash
-node index.js
-\`\`\`
-
-Expected output:
-\`\`\`
-[Output here]
-\`\`\`
-
-## 🎉 You Did It!
-
-You just [accomplished thing].
-
-**Next steps:**
-- [Link to full tutorial]
-- [Link to API docs]
-- [Link to examples repo]
-```
-
-### Full Tutorial Template (20-45 minutes)
-
-```markdown
-# Build a [Thing] with [Technology]
-
-Learn how to [outcome] by building [specific project].
-
-| | |
-|---|---|
-| **Time** | 30 minutes |
-| **Level** | Intermediate |
-| **Prerequisites** | Node.js 18+, basic JavaScript |
-
-## What You'll Build
-
-[Screenshot or diagram of final result]
-
-By the end, you'll have:
-- ✅ [Capability 1]
-- ✅ [Capability 2]
-- ✅ [Capability 3]
-
-## Prerequisites
-
-### Required Software
-
-| Tool | Version | Verify |
-|------|---------|--------|
-| Node.js | 18+ | `node -v` |
-
-### Required Knowledge
-
-- [Concept 1] — [link to learn]
-- [Concept 2] — [link to learn]
-
-## Step 1: Project Setup
-
-[Setup instructions with verification]
-
-**Checkpoint:** You should see `[expected output]`.
-
-## Step 2: [First Feature]
-
-[Instructions]
-
-**Checkpoint:** Test with `[command]`.
-
-## Step 3: [Second Feature]
-
-[Instructions]
-
-## Step 4: [Third Feature]
-
-[Instructions]
-
-**Checkpoint:** Your app should now [do thing].
-
-## Complete Code
-
-Here's everything together:
-
-\`\`\`javascript
-// Full final code
-\`\`\`
-
-## Troubleshooting
-
-### [Common Error 1]
-[Solution]
-
-### [Common Error 2]
-[Solution]
-
-## What You Learned
-
-- [Key concept 1]
-- [Key concept 2]
-- [Key concept 3]
-
-## Next Steps
-
-- **Go deeper:** [Link to advanced tutorial]
-- **Explore:** [Link to related feature]
-- **Get help:** [Link to Discord/community]
-```
-
----
-
-## Quality Checklist
-
-Before publishing, verify:
-
-### Code Quality
-- [ ] Every code block runs without modification
-- [ ] All imports/requires are included
-- [ ] Expected output is shown
-- [ ] Error handling is included
-- [ ] Environment variables use `.env` pattern
-
-### Structure Quality
-- [ ] Prerequisites are explicit
-- [ ] Time estimate is accurate (test it!)
-- [ ] Checkpoints every 3-5 steps
-- [ ] Final complete code is provided
-- [ ] Troubleshooting covers likely errors
-
-### Accessibility
-- [ ] Works on Mac, Linux, AND Windows
-- [ ] Commands work in bash/zsh/PowerShell
-- [ ] File paths use correct separators
-- [ ] No assumptions about installed tools
-
----
-
-## Tools
-
-| Tool | Use Case |
-|------|----------|
-| **[Octolens](https://octolens.com)** | Find common questions and errors developers encounter. Monitor Stack Overflow and GitHub issues for troubleshooting content. |
-| **Replit/CodeSandbox** | Embed runnable examples |
-| **Carbon/Ray.so** | Beautiful code screenshots |
-| **Excalidraw** | Architecture diagrams |
-| **Terminalizer** | Record terminal sessions |
-| **Loom** | Quick video supplements |
-
----
-
-## Related Skills
-
-- `developer-audience-context` — Understand skill level and environment
-- `devrel-content` — General technical writing principles
-- `developer-onboarding` — Optimize time to first success
-- `developer-seo` — Get tutorials found via search
-
 ## Limitations
 
 - Use this skill only when the task clearly matches its upstream source and local project context.