to-syllabus
Turns a topic, a fixed experienced-developer audience, and a domain into a learning syllabus and a companion technical guide. Use when someone says "syllabus this" or asks to create a learning path framed inside a domain.
- License 许可
- MIT
- 最近更新
- 2026-11-07
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- to-syllabus
- description
- Turns a topic, a fixed experienced-developer audience, and a domain into a learning syllabus and a companion technical guide. Use when someone says "syllabus this" or asks to create a learning path framed inside a domain.
02 资源文件 4
- 资产文件assets/syllabus-template.md2.3 KB
- 资产文件assets/technical-guide-template.md1.5 KB
- 参考文档references/example-syllabus-week.md4.0 KB
- 参考文档references/example-technical-guide-patterns.md5.1 KB
03 SKILL.md 正文
To Syllabus Skill
Converts three inputs — (a) a topic to learn, (b) a domain to frame it in, (c) a fixed audience (experienced developer) — into two documents that serve two different jobs:
- The Learning Syllabus — the journey. A sequence of features ("we build X, then Y, then Z"), each with an outcome, the concepts it requires, the requirements, and acceptance criteria. Zero code. STE prose. Tables for density.
- The Technical Guide — the vocabulary. Named, general coding patterns the journey requires, each explained with a minimal illustrative shape. Code is allowed here; it is the code reference.
The domain is a thin wrapper. Its only jobs are to make the topic fun and give the learner a finish line. It must never become the subject. If a domain would distract more than it frames, simplify it.
Fixed Audience
The learner is an experienced developer. The syllabus never teaches programming basics: what types are, what a function is, how loops work, and so on. The learner is trusted to work through complex requests. Modern techniques are presented as canonical — no comparisons to other languages, no "unlearn X" framing. Side research by the learner is their own business, not this skill's concern.
Transformation Workflow
- Read all input first. Absorb the topic and the domain. Do not write until both are framed. If the domain was not given, propose a top-3 bulleted list of candidate domains suited to the topic (game-related hints are encouraged) and use the learner's pick.
- Determine the finish line. State, in one to three STE sentences, the finished artifact and what the learner will be able to do. No stretch goals. No deferred ideas.
- Decompose the topic into techniques. List the modern techniques an experienced developer must know to do this topic. Order them by dependency, but keep them as techniques — not micro-lessons. These become the technical guide's pattern inventory.
- Decompose the domain into features. List the concrete things to build ("we build X, then Y, then Z"). Keep the list short. Every feature must clearly exist to serve one or more techniques; a feature that exists only to be game-like is scope creep.
- Map features to techniques; run the prerequisite check. Order the features so that each feature requires only techniques whose patterns already exist in the guide at that point. If a feature secretly needs a technique not yet introduced, reorder the features, simplify the feature, or move the technique earlier. If a technique cannot attach to any feature, drop it from the journey. This is the safety valve — keep it light, do not fragment features.
- Draft the Technical Guide. Build the named pattern inventory the journey needs. Each pattern: What it is / Why you use it / The shape / Watch out for. General and illustrative; never the assembled solution.
- Draft the Learning Syllabus. One section per feature, in order. Each feature gets: Outcome, Concepts (mapped to guide sections), Requirements, Acceptance Criteria. Zero code, STE prose, tables for density. Reference guide sections by stable name.
- Run the reference check. Every concept named in the syllabus exists as a section in the guide. Every guide section is either referenced by the syllabus or marked as optional reference. Renumber or rename anything unstable.
- Output the documents. Write the syllabus and the guide to disk using the
assetstemplates. No preamble, no explanation — just the documents.
Syllabus Rules
Lift-out test. Every requirement must still make sense when read alone in a ticket or a note without its surrounding week. If a line depends on hidden context, rewrite it until it stands alone.
Single-claim rule. Each requirement carries one behavior. Split combined ideas unless they are inseparable parts of one behavior.
No-Code Rule (structural)
The syllabus never contains code fences — not even one-liners. The assets/syllabus-template.md has no code slot, so there is nowhere for code to go. Behavior is described in STE prose and in tables, exactly enough to act as a contract.
Allowed inside the syllabus (prose only):
- Function and type names, referenced as named things, e.g. "a function named
renderBoardthat takes theGameStateand returns a string." - Body-level behavior details in prose, e.g. "the function loops over the map's
ythenx, and in the inner loop it emits the entity glyph at that coordinate if one exists, otherwise the tile glyph."
Function-Contract Rule
A requirement for a function states, in prose: what it takes, what it returns, and what happens inside it. It must rely only on types and functions that already exist from earlier features — never on a type or function that has not been introduced. If a requirement needs something new, that something belongs in an earlier feature or a new Concepts row.
Acceptance-Criteria Rule
Every week ends with an acceptance-criteria table. The table is the contract: it must be specific enough that a developer can verify the week without asking a human. Vague phrases such as "print the tiles to the screen" are rejected; they are replaced with the full behavior. See the example in references/example-syllabus-week.md.
Reference-Named Rule
When a requirement depends on a coding pattern, it names the pattern and the technical guide section, e.g. "model the action as a Discriminated Union (Technical Guide → Discriminated Union)." If a pattern is complex, the syllabus points at the guide section rather than explaining the pattern itself — the guide is where code belongs.
Technical Guide Rules
Pattern, not implementation. The guide contains named, general patterns — vocabulary. It never contains the assembled solution to the journey (no working reduce, no finished loop, no assembled engine). Assembly is the learner's job, done against the syllabus requirements. The line is: patterns and their minimal illustrative shapes yes; the project's assembled code no.
Illustration may use the domain. A pattern's minimal example may use domain-shaped data (e.g. a tileKinds literal union) to make the pattern concrete. It must still read as the general technique, not as a project file.
Stable names. Every pattern gets a short, stable name that the syllabus references verbatim. Keep section headings stable; the syllabus links to them by name.
Per-pattern structure
- What it is: one to two sentences.
- Why you use it: the situation it solves.
- The shape: a minimal, general code example.
- Watch out for: the common mistakes.
STE is looser here than in the syllabus. Richer prose and code are expected. Plain-English clarity still trumps cleverness.
STE (Simplified Technical English) Rules
Applies most strictly to the syllabus.
- Use short sentences and imperative constructions where natural.
- Use the same word for the same thing; do not rename a concept mid-document.
- Remove vague adjectives (
big,nice,easy,simple). Say what is observable instead. - Prefer concrete verbs: build, returns, loops, rejects, increments.
- Type names, function names, and section names are technical names — they are allowed and must be written exactly.
- If a sentence can be read two ways, split or reword it until it cannot.
Omission Rules
| Section | Omit When... |
|---|---|
| Journey Goal | Never omit — the finish line is required. |
| A weekly Concepts table | A feature genuinely introduces no new concept (rare; the guide reference is still expected). |
| A weekly Verification line | The Acceptance Criteria already fully covers verification (prefer omitting over repeating). |
| Technical Guide optional-reference marks | No pattern is purely optional context. |
Output Behavior
- Use the formats in
assets/syllabus-template.mdandassets/technical-guide-template.md. - Preserve Markdown heading levels and section ordering.
- Omit empty optional sections instead of leaving placeholder text behind.
- Do not include analysis, rationale, or meta commentary about how the documents were produced.
- When the topic or domain is contradictory, choose the most constrained reading that still fits the repeated signals.
- The syllabus and technical guide are two separate documents. Do not merge them.
File Output
Write both finished documents to disk rather than printing them to the conversation.
Default output paths:
- Syllabus:
docs/<topic-slug>-syllabus.md - Technical guide:
docs/<topic-slug>-technical-guide.md
Filename derivation: the topic, lowercased, spaces replaced with hyphens, special characters stripped.
If a destination folder does not exist: create it before writing the documents.
04 同仓库更多 Skills
to-icebox
Transforms a stream of thoughts, rough conversation, or scattered ideas into a structured feature request document. Use when someone says "icebox this".
righting-software
Juval Löwy's "The Method" (Righting Software, 2019) as an operating procedure. Decompose a system by axes of volatility, never by functionality; classify components into the fixed taxonomy (Client, Manager, Engine, ResourceAccess, Resource, Utilities); validate by call chains; then design the project that builds it. Use when the user asks for system design, architecture review, service decomposition, "The Method", volatility-based decomposition, or asks how long/costly a build will be.
documentation-writer
Diátaxis Documentation Expert. An expert technical writer specializing in creating high-quality software documentation, guided by the principles and structure of the Diátaxis technical documentation authoring framework.
defensive-architecture-pr-review
Reviews pull request diffs against a legacy codebase using Juval Löwys Volatility-Based Decomposition (The Method). Detects architectural decay, leakage of business-rule volatility, and boundary infractions