{"id":50519366,"url":"https://github.com/sshaaf/tutorial-skill","last_synced_at":"2026-06-03T02:32:00.234Z","repository":{"id":356489997,"uuid":"1228957483","full_name":"sshaaf/tutorial-skill","owner":"sshaaf","description":"This skill generates code tutorials from source code using Large Language Models (LLMs). It analyzes the source code, identifies abstractions and relationships, and generates a structured tutorial with chapters. It has various commands such as analysis, build and preview.","archived":false,"fork":false,"pushed_at":"2026-05-10T07:46:36.000Z","size":703,"stargazers_count":4,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-03T02:31:57.858Z","etag":null,"topics":["claude-code","skill"],"latest_commit_sha":null,"homepage":"https://shaaf.dev/post/2026-05-05-lessons-from-building-my-first-claude-skill-a-code-tutorial-generator/","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/sshaaf.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-04T14:52:56.000Z","updated_at":"2026-05-20T00:49:10.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/sshaaf/tutorial-skill","commit_stats":null,"previous_names":["sshaaf/tutorial-skill"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/sshaaf/tutorial-skill","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sshaaf%2Ftutorial-skill","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sshaaf%2Ftutorial-skill/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sshaaf%2Ftutorial-skill/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sshaaf%2Ftutorial-skill/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sshaaf","download_url":"https://codeload.github.com/sshaaf/tutorial-skill/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sshaaf%2Ftutorial-skill/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33845770,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-03T02:00:06.370Z","response_time":59,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["claude-code","skill"],"created_at":"2026-06-03T02:31:59.722Z","updated_at":"2026-06-03T02:32:00.227Z","avatar_url":"https://github.com/sshaaf.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Tutorial Skill\n\nThis skill generates code tutorials from source code using Large Language Models (LLMs). It analyzes the source code, identifies abstractions and relationships, and generates a structured tutorial with chapters.\n\n**Features**:\n- 🎨 **Professional output**: HonKit (Markdown) or Antora (AsciiDoc) compatible with diagrams, practice exercises, and custom styling\n- 📝 **Multiple formats**: Generate Markdown for HonKit or AsciiDoc for Antora with `--engine` flag\n- 🏗️ **Architecture analysis**: Automatically identifies code abstractions and relationships\n- 📚 **Comprehensive content**: Practice exercises, flow diagrams, and beginner-friendly explanations\n \n\n### Quick start\n```bash\n# 1. Navigate to your project\ncd /path/to/your/project\n\n# 2. Install the skill locally \"install -g\" for global install.\nnpx @sshaaf/tutorial-skill install\n\n# 3. Reload your coding agent (e.g., restart Claude Code CLI or reload IDE)\n\n# 4. Generate tutorial (in Claude Code)\n/tutorial build\n# Or for Antora: /tutorial build --engine antora\n\n# 5. Preview the tutorial (optional)\n# Option A: View markdown/AsciiDoc files directly (VS Code, etc.)\n# Option B: Preview as HTML with HonKit (for Markdown output)\nnpm install -g honkit\ncd ./docs/tutorial\nhonkit serve\n# Option C: Preview as HTML with Antora (for AsciiDoc output)\nnpm install -g @antora/cli @antora/site-generator-default\n# Create playbook (configure url, start_path, supplemental_files), then: antora antora-playbook.yml\n```\n\n**What happens**:\n- Step 2 creates `.claude/tutorial/` in your project with both HonKit and Antora templates\n- Step 4 generates tutorial files in `./docs/tutorial/` (Markdown for HonKit or AsciiDoc for Antora)\n- Step 5 (optional) serves an interactive HTML site\n\n![Example](.github/assets/images/example-preview.jpg)\n\n\n## Pipeline Overview\n\n### Build Mode (6 stages)\n1. **Code Discovery**: Find and read source files\n2. **Identify Abstractions**: Extract core concepts\n3. **Analyze Relationships**: Map component interactions\n4. **Organize Chapters**: Determine pedagogical order\n5. **Generate Metadata**: Create tutorial info\n6. **Write Content**: Generate introduction + chapters\n\n## Language Support\n\nWorks with any programming language:\n- Java, Python, JavaScript/TypeScript, Go, C#, Ruby, PHP, Rust, Kotlin etc.\n\n## Commands\n\n### `/tutorial build`\nComplete tutorial generation with chapters\n- **Time**: 10-30 minutes\n- **Output**: Documentation files (Markdown for HonKit or AsciiDoc for Antora)\n- **Use for**: Creating learning materials, documentation, training resources\n- **Engines**:\n  - `--engine honkit` (default): Generates Markdown files for HonKit static site generator\n  - `--engine antora`: Generates AsciiDoc files for Antora documentation system\n\n## Installation\n\n### Local Installation (per-project)\n\n```bash\n# Navigate to your project directory\ncd /path/to/your/project\n\n# Install via NPM (recommended)\nnpx @sshaaf/tutorial-skill install\n```\n\nThis creates `.claude/tutorial/` in your project directory with:\n- Skill definition (SKILL.md) - enables `/tutorial build` command\n- Templates for tutorial generation (HonKit-compatible markdown)\n\n**Benefits of local installation**:\n- ✅ Version control templates with your project\n- ✅ Customize templates per project\n- ✅ Multiple projects can have different versions\n- ✅ No global state - everything is project-local\n\n### Global Installation (system-wide)\n\n```bash\n# Install globally (available in all projects)\nnpx @sshaaf/tutorial-skill install -g\n```\n\nThis creates `~/.claude/skills/tutorial/` with:\n- Skill definition (SKILL.md) - enables `/tutorial build` in any project\n- Templates for tutorial generation (HonKit-compatible markdown)\n\n**Benefits of global installation**:\n- ✅ One installation works everywhere\n- ✅ No per-project setup needed\n- ✅ Consistent templates across all projects\n- ✅ Simpler for single-user environments\n\n**Preview generated tutorials**:\nThe skill generates HonKit-compatible markdown. To preview as HTML:\n```bash\n# Install HonKit globally (one-time)\nnpm install -g honkit\n\n# Preview any generated tutorial\ncd ./docs/tutorial\nhonkit serve\n# Opens at http://localhost:4000\n```\n\n### Updating\n\n**Local installation:**\n```bash\n# Navigate to the project directory where you installed the skill\ncd /path/to/your/project\n\n# Check for updates\nnpx @sshaaf/tutorial-skill update --check\n\n# Update to latest version (with automatic backup)\nnpx @sshaaf/tutorial-skill update\n\n# Update without backup\nnpx @sshaaf/tutorial-skill update --no-backup\n\n# Force update even if on latest version\nnpx @sshaaf/tutorial-skill update --force\n```\n\n**Global installation:**\n```bash\n# Can run from any directory\n\n# Check for updates\nnpx @sshaaf/tutorial-skill update -g --check\n\n# Update to latest version (with automatic backup)\nnpx @sshaaf/tutorial-skill update -g\n\n# Update without backup\nnpx @sshaaf/tutorial-skill update -g --no-backup\n\n# Force update even if on latest version\nnpx @sshaaf/tutorial-skill update -g --force\n```\n\n**Important notes about updates**:\n- ⚠️ Updates **overwrite** files in `.claude/tutorial/` (local) or `~/.claude/skills/tutorial/` (global) including templates\n- ✅ Automatic backup created at `.backup/` subdirectory before update\n- ✅ Rolls back automatically if update fails\n- 💡 If you customized templates, backup is your safety net\n\n**Workflow for customized templates**:\n```bash\n# Before update - manually save your customizations\ncp -r .claude/tutorial/templates .claude/tutorial/templates.custom\n\n# Run update\nnpx @sshaaf/tutorial-skill update\n\n# After update - restore specific customizations\n# (merge changes as needed)\ndiff -r .claude/tutorial/templates .claude/tutorial/templates.custom\n```\n\n**Alternative methods:**\n```bash\n# Manual install from source (run from project directory)\ncp -r /path/to/tutorial-skill .claude/tutorial\n\n# Or clone directly\ngit clone https://github.com/sshaaf/tutorial-skill .claude/tutorial\n```\n\n**Version control (local installation only)**:\n```bash\n# Option 1: Exclude from git (recommended for most users)\necho \".claude/\" \u003e\u003e .gitignore\n\n# Option 2: Commit templates for team customization\ngit add .claude/tutorial/templates/\ngit add .claude/tutorial/SKILL.md\ngit commit -m \"Add customized tutorial templates\"\n```\n\n**Note**: Global installations (`~/.claude/skills/tutorial/`) are in your home directory and not part of any project repository.\n\n**Managing multiple projects**:\n```bash\n# Each project has its own local installation\ncd ~/projects/app-A\nnpx @sshaaf/tutorial-skill install  # Creates app-A/.claude/tutorial/\n\ncd ~/projects/app-B\nnpx @sshaaf/tutorial-skill install  # Creates app-B/.claude/tutorial/\n\n# Customize templates differently per project\nvim ~/projects/app-A/.claude/tutorial/templates/honkit/index.md\nvim ~/projects/app-B/.claude/tutorial/templates/honkit/index.md\n\n# Updates are per-project\ncd ~/projects/app-A\nnpx @sshaaf/tutorial-skill update  # Updates only app-A\n\ncd ~/projects/app-B\nnpx @sshaaf/tutorial-skill update  # Updates only app-B\n```\n\n### Usage\n\n**Generate tutorial** (in Claude Code):\n\n```bash\n# Default (HonKit/Markdown)\n/tutorial build .\n\n# With Antora (AsciiDoc)\n/tutorial build --engine antora\n\n# With output directory\n/tutorial build --output ./docs/tutorial\n\n# Combine options\n/tutorial build --engine antora --output ./docs/tutorial\n```\n\n**Preview generated tutorials**:\n\nHonKit (Markdown):\n```bash\nnpm install -g honkit\ncd ./docs/tutorial\nhonkit serve\n# Opens at http://localhost:4000\n```\n\nAntora (AsciiDoc):\n```bash\nnpm install -g @antora/cli @antora/site-generator-default\n# Create antora-playbook.yml (see template README for configuration)\nantora antora-playbook.yml\nnpx http-server build/site -p 8080\n# Opens at http://localhost:8080\n# Note: Mermaid diagrams render client-side via supplemental-ui\n```\n\n**Output formats**:\n- **HonKit**: Generates `README.md`, `SUMMARY.md`, `book.json`, `*.md` chapters\n- **Antora**: Generates `antora.yml`, `modules/ROOT/nav.adoc`, `modules/ROOT/pages/*.adoc` chapters\n\n### Developer Notes\n\nIf you are testing changes **before publishing** to npm:\n\nSee `DEV_TESTING.md` for the testing checklist.\n\n## Tips\n\n### For Best Analysis\n- Focus on specific directories for large projects\n- Exclude test files (done automatically)\n- Ask follow-up questions after analysis\n\n### For Best Tutorials\n- Specify target audience (beginner/intermediate/advanced)\n- Review chapter order before generation\n- Regenerate specific chapters if needed\n\n## Documentation\n\n- **SKILL.md**: Complete skill implementation\n- **DEV_TESTING.md**: Local testing checklist for maintainers\n- **Installation**: See parent directory QUICK-START.md\n- **Comparison**: See parent directory SKILLS-README.md\n\n## Based On\n\nExtracted from [Waver LLM](https://github.com/sshaaf/waver-llm) by Shaaf Syed.\n\n## License\n\nMIT License (same as Waver LLM)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsshaaf%2Ftutorial-skill","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsshaaf%2Ftutorial-skill","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsshaaf%2Ftutorial-skill/lists"}