Positioning: Lightweight routing hub — distributes tutorial creation requests to 8 independent sub-skills Architecture: 8-Entry Router (root → skills/ = Layer 0 → Layer 1) Toolchain: Turborepo | Approach: Approach C (8-Sub Hybrid + Independent Init) Architecture Version: Monorepo-v1(content-format decoupling + three-layer separation)
Goal
Distribute the complete lifecycle of tutorial creation (research planning → writing execution → content management → quality validation → website build → ebook generation → deployment release → decision贯穿) through a unified entry point, with each stage having independent skill files and detailed rules.
What It Can Do:
- Intelligently route user requests to 8 self-contained sub-skills
- Provide a global quick reference (iron rules/classification)
- Show sub-skill overview and interdependencies
- Guide the project initialization process
What It Cannot Do:
- Does not include specific operation steps (each sub-skill is responsible)
- Does not perform validation or build or release (→
/review/web/book/github-pages） - Does not include project initialization logic (→ see the "🚀 Project Initialization" section below)
🏗️ Monorepo Architecture Overview
Design Source: README.md Chapters 4, 5 Core Philosophy: Content is the single source of truth, format is an extensible presentation layer
Architecture Core Concepts
Layer 1: 路由层 (SKILL.md) → 纯请求分发
Layer 2: 技能层 (skills/*) → 每个技能只关注核心职责
Layer 3: 工具层 (scripts+templates) → 初始化、模板、共享工具
apps/ ← 应用层
├── web/ (表示层 A) ← 网站 (Astro + Starlight, 依赖 content)
packages/ ← 库层
├── content/ (数据层) ← 唯一真相源
└── book/ (表示层 B) ← 电子书 (Pandoc + PDF, 依赖 content)
依赖关系: content ← web, content ← book (禁止反向)
Three Major Design Principles
| Principle | Description |
|---|---|
| Single Responsibility | Each sub-skill answers only one question |
| Correct Dependency Direction | content ← depended on by tutorial/book, reverse is prohibited |
| Initialization Decoupling | The init script is responsible for creating the project skeleton; sub-skills assume the package already exists |
Version Compatibility Requirements
| Sub-skill | Minimum Version | Architecture Support |
|---|---|---|
| web (apps/web) | v1.0.0+ | ✅ Monorepo (initialization logic removed) |
| book (packages/book) | v1.0.0+ | ✅ Brand-new ebook generation |
| github-pages | v1.0.0+ | ✅ Deployment only (PDF/EPUB removed) |
This router requires web (apps/web) ≥ v1.0.0, book ≥ v1.0.0, github-pages ≥ v1.0.0. Older sub-skills use the traditional architecture and are incompatible with this version.
🎯 Core Principles (Quick Reference)
┌──────────────────────────────────────────────┐
│ 三大铁律 │
├──────────────────────────────────────────────┤
│ ① 层级 ≤3 层 (references/assets 不算) │
│ ② NO SKILL WITHOUT USE CASE IN AGENTS │
│ ③ description 只写触发条件 (CSO) │
└──────────────────────────────────────────────┘
CSO Rule: description contains "Use when...", max 1024 characters
For details, see references/design-principles.md。
🧭 8-Sub Routing Table
用户说... → 调用
───────────────────────────────── ─────────────────────────────────────
"搜索/调研/规划/找资料/设计章节结构" → 📚 /research (调研与规划)
"写/撰写/创作/编写章节" → ✍️ /writing (撰写执行)
"检查/校对/质量/门禁/评分" → ✅ /review (质量校验)
"内容结构/schema/命名规范/Frontmatter/目录组织" → 📝 /content (内容管理) 🆕
"构建网站/Astro/Starlight/组件/配置" → 🌐 /web (网站构建) ⭐ 高频
"PDF/电子书/Pandoc/排版/EPUB/LaTeX" -> 📖 /book (电子书生成) 🆕
"部署/GitHub Pages/Actions/CI-CD/域名" → 🚀 /github-pages (Pages 部署) 🟢 低频
"配置/决策/改决策/看看决策/冲突" → 📐 /decision (决策系统)
Composite Scenarios
| User Intent | Execution Order |
|---|---|
| Fully create a tutorial (website + ebook) | research → writing → content → review → web + book → github-pages |
| Fully create a tutorial (website only) | research → writing → content → review → web → github-pages |
| Generate ebook PDF | research → writing → content → book |
| Optimize existing chapters | review → writing → content → review → web → github-pages |
| Create a new tutorial project | decision → run init script → research → writing → content → review → web → github-pages |
| Modify configuration only | decision |
| Build/refactor website only | web (can be called independently and repeatedly) |
| Redeploy only | github-pages (can be called independently) |
| Generate ebook only | book (can be called independently) |
Ambiguity Handling
When the user's intent is unclear, provide options:
"Do you want to: a) 📚 Research planning b) ✍️ Write/edit content c) 📝 Content structure management d) ✅ Quality check e) 🌐 Build website f) 📖 Generate ebook g) 🚀 Deploy and publish h) 📐 Management decisions?"
📂 Sub-skill overview
| # | Sub-skill | Version | Change type | Responsibility | Trigger words | Key features | Frequency |
|---|---|---|---|---|---|---|---|
| ① | research | v1.0.0 | ✅ Keep | Research planning | Search/planning/design structure | Search methodology + length planning + standards overview | Low |
| ② | writing | v1.0.0 | ⚠️ Streamline | Writing execution | Write/compose/complete chapters | Writing process + material management + specifications R1-R6 (content management part removed) | Medium |
| ③ | review | v1.0.0 | ✅ Keep | Quality verification | Check/proofread/gatekeeping | 14 quality gates + scorecard | Medium |
| ④ | content | v1.0.0 | 🆕 New | Content management | Content structure/schema/naming conventions | File organization + Frontmatter schema + Content Collections + enhancement pipeline | Medium |
| ⑤ | web | v1.0.0 | ✏️ Rename | Website building | Build/Astro/Starlight/components/configuration | Astro + Starlight configuration + component development + build optimization (initialization removed) | 🔴 High |
| ⑥ | book | v1.0.0 | 🆕 New | Ebook generation | PDF/ebook/Pandoc/typesetting/EPUB | PDF/EPUB generation + Pandoc configuration + LaTeX templates + ebook styles | 🟡 Medium |
| ⑦ | github-pages | v1.0.0 | ✏️ Rename | Pages deployment | Deploy/GitHub Pages/Actions/CI-CD | GitHub Actions + Pages deployment + domain/DNS/SSL + monitoring (PDF/EPUB removed) | 🟢 Low |
| ⑧ | decision | v1.0.0 | ✅ Keep | Decision贯穿 | Configuration/decision | Decision methodology + phase mapping + conflict resolution | Throughout |
8 sub-skills are fully self-contained: independent SKILL.md + references/ + phase-specific decision details
Frequency notes: web is a high-frequency sub-skill (estimated 10-20 calls per project), github-pages is low-frequency (2-3 times), book is medium-frequency (3-5 times)
Change notes:
- ✅ Keep: responsibilities unchanged, only version numbers and references updated
- ⚠️ Streamline: content management-related parts removed (→ content sub-skill)
- 🆕 New: brand-new sub-skill, filling a responsibility gap
- ✏️ Rename: directory rename + responsibility focus (e.g., publish → github-pages retains only deployment)
📂 Project structure
tutorial-writer/
├── SKILL.md ← 本文件 (8-Sub 路由器)
├── references/ ← 全局共享参考
│ ├── design-principles.md ← 铁律+分类+架构说明
│ ├── cross-chapter-rules.md ← R7-R10 跨章一致性规则
│ ├── phase-mapping.md ← 阶段→决策项映射
│ └── monorepo-guide.md ← 🆕 Turborepo 使用指南
├── assets/ ← 全局共享模板
│ ├── decision-record-schema.json
│ └── decision-record-template.json
└── skills/ ← Layer 1: 8个独立子技能
├── ① tutorial-writer-research/ ← 📚 调研规划 (保持)
├── ② tutorial-writer-writing/ ← ✍️ 撰写执行 (精简)
├── ③ tutorial-writer-review/ ← ✅ 质量校验 (保持)
├── 🆕 ④ tutorial-writer-content/ ← 📝 内容管理 (新增)
├── ✏️ ⑤ tutorial-writer-web/ ← 🌐 网站构建 (原 build)
├── 🆕 ⑥ tutorial-writer-book/ ← 📖 电子书生成 (新增)
├── ✏️ ⑦ tutorial-writer-github-pages/← 🚀 Pages 部署 (原 publish)
└── ⑧ tutorial-writer-decision/ ← 📐 决策贯穿 (保持)
🚀 Project initialization
Important: project initialization has been migrated to the official CLI toolchain; see the "🚀 Project Initialization (Official Tools)" section below for details.
⚠️ Notes
- Sub-skill priority: The root file only handles routing; detailed logic resides in each sub-skill
- Each sub-skill can be used independently: Has its own description, the Agent can trigger it directly
- The global references/ only holds content shared across sub-skills: Design principles/cross-chapter rules/stage mapping/Monorepo guide
- Clear functional ownership: Search planning is in research, writing is in writing, content management is in content, validation is in review, website building is in web, e-books are in book, deployment is in github-pages, decisions are in decision
- Decisions run through all stages: Each sub-skill has an independent
decision-record-rules.mdthat defines the decision details for this stage - 🆕 Monorepo architecture constraints:
- The project must be initialized via the init script: Do not manually create the Monorepo structure in sub-skills
- Version requirements: web ≥ v1.0.0, book ≥ v1.0.0, github-pages ≥ v1.0.0
- Dependency direction: The content package is depended on by web and book; reverse dependencies are prohibited
- Single source of content: All Markdown content is placed in
packages/content/src/chapters/ - Initialization order: First initialize the project according to the "🚀 Project Initialization (Official Tools)" section, then use each sub-skill
- If you need to use the legacy architecture: Please downgrade to tutorial-writer v6.1.0
Version history
| Version | Date | Changes |
|---|---|---|
| v1.0.0 | 2026-05-31 | 🔄 Major Monorepo architecture refactor (6→8 Sub): Version reset to v1.0.0; sub-skills expanded from 6 to 8 (added content, book; build→web, publish→github-pages renamed); added meta.architecture_version: "monorepo-v1" and meta.sub_skills_count: 8 metadata; routing table expanded from 6 rows to 8 rows (added content/book trigger paths); sub-skill overview table added two columns "Version Number" and "Change Type"; composite scenarios updated (added e-book generation, parallel build, and other scenarios); added "🚀 Project Initialization (Official Tools)" section (using the official CLI toolchain); notes fully updated to Monorepo architecture constraints; description and tags updated (added monorepo/turborepo/pdf/epub/content-management) |
| v6.1.0 | 2026-05-31 | Content-First v2 architecture alignment (previous version, maintenance discontinued) |
| v6.0.0 | 2026-05-30 | 6-Sub Router refactor (previous version, maintenance discontinued) |
| v4.1.0 | 2026-05-30 | Modular configuration + plugin ecosystem (previous version) |
| v4.0.0 | 2026-05-30 | Astro + Starlight publishing solution (previous version) |
| v3.2.0 | 2026-05-29 | Tag-driven publishing + skill-factory takeover (previous version) |
| v3.1.0 | 2026-05-29 | Web rich interaction enhancements (previous version) |
| v3.0.0 | 2026-05-29 | 5-Sub Router refactor (previous version) |
Last updated: 2026-05-31 | Maintainer: skill-factory + user collaboration
🚀 Project Initialization (Official Tools)
Important: Tutorial Writer uses the official CLI toolchain to create projects, rather than custom scripts. This ensures that the latest versions of templates and best practices are always used.
Initialization process overview
graph LR
A[Step 0: 环境准备] --> B[Step 1: 创建 Monorepo]
B --> C[Step 2: 添加 content 包]
C --> D[Step 3: 创建 web 包]
D --> E[Step 4: 添加 book 包]
E --> F[Step 5: 配置依赖]
F --> G[Step 6: 注入 TW 配置]
style A fill:#e3f2fd,stroke:#1565c0
style G fill:#c8e6c9,stroke:#2e7d32
Step 0: Prerequisite environment check
# 确保 Node.js >= 18
node --version # 需要 v18+
# 确保包管理器可用（任选其一）
bun --version # 推荐（教程项目使用 bun）
# 或 pnpm --version
# 或 npm --version
# 可选：安装 Turborepo CLI（如果需要全局命令）
bun add -D turbo
# 或 npx turbo （推荐，无需安装）
Step 1: Create the Monorepo skeleton
Use the official Turborepo scaffolding:
# 方式 A: 使用 create-turbo（推荐，交互式）
bunx create-turbo@latest <project-name>
# 会提示选择:
# - Package manager: bun (推荐) / pnpm / yarn / npm
# - App type: 根据需求选择
cd <project-name>
bun install
# 方式 B: 手动创建（更可控）
mkdir <project-name> && cd <project-name>
bun init
# 在 package.json 中添加 workspaces: ["apps/*", "packages/*"]
# 创建 turbo.json（详见 Turborepo 官方文档）
Verify:
ls turbo.json package.json
# 然后检查 package.json 包含 workspaces 配置
Step 2: Add the content package (data layer)
# 使用 turbo gen 添加空包
turbo gen workspace \
--name @repo/content \
--type package \
--destination packages/content
# 创建内容目录结构
mkdir -p packages/content/src/chapters
touch packages/content/src/chapters/.gitkeep
Step 3: Create the web app (website layer)
# 在项目根目录运行，自动在 apps/web 下创建 Astro + Starlight 项目
bun create astro apps/web --template starlight --install --yes
Note:
create-astroWill generate the complete Astro project structure. We don't need to manually copy any template files!Turbo conventions: Runnable applications go in the
apps/directory, shared libraries go in thepackages/directory.apps/webis the newly added tutorial site, alongside thecreate-turbogenerated by default byapps/web、apps/docs.
Step 4: Add the book package (ebook layer)
turbo gen workspace \
--name @repo/book \
--type package \
--destination packages/book
Step 5: Configure Workspace dependencies
Edit each package's package.jsonto declare dependency relationships:
// apps/web/package.json
{
"dependencies": {
"@repo/content": "workspace:*"
}
}
// packages/book/package.json
{
"dependencies": {
"@repo/content": "workspace:*"
}
}
Step 6: Inject Tutorial Writer configuration
This is Tutorial Writer'score value-added part：
6.1 Content Schema definition
See the /content sub-skill for details.
Brief steps:
# 创建 Content Collections 配置
cat > packages/content/src/config.ts << 'EOF'
import { defineCollection, z } from 'astro:content';
import { docsLoader, docsSchema } from '@astrojs/starlight/loaders';
const chapters = defineCollection({
loader: docsLoader(),
schema: docsSchema({
schema: z.object({
title: z.string(),
description: z.string().optional(),
draft: z.boolean().default(false),
tags: z.array(z.string()).default([]),
difficulty: z.enum(['beginner', 'intermediate', 'advanced']).optional(),
readingTime: z.number().optional(),
prerequisites: z.array(z.string()).default([]),
hasInteractive: z.boolean().default(false),
hasMermaid: z.boolean().default(false),
hasMath: z.boolean().default(false),
}),
}),
});
export const collections = { chapters };
EOF
6.2 PDF generation configuration (optional)
See the /book sub-skill for details.
Verification checklist
After initialization is complete, confirm that the following files exist:
-
turbo.json(root directory) -
package.jsonincludesworkspaces: ["apps/*", "packages/*"] -
packages/content/package.json -
packages/content/src/config.ts -
apps/web/package.json -
apps/web/astro.config.mjs(Starlight configuration) -
packages/book/package.json
Common questions
Q: Can I use pnpm/npm/yarn?
A: Yes! Turborepo supports all mainstream package managers. This tutorial example uses bun and npm workspaces (the"workspaces" field is configured in package.json ).
Q: Must it be executed in order? A: Steps 2-4 can be executed in parallel (if using multiple terminals), but Step 5 must come after them.
Q: How do I update to the latest template?
A: No manual operation is needed! Each time create-astro@latest is run, it will fetch the latest version.