cheyuriycheyuriy/codelabgen/skills/site-assembly/SKILL.md

site-assembly

Skill1 starsChanged 24 days agoMITView on GitHub

How a codelabgen course is assembled into its readable form — generated READMEs and table of contents, run.sh, the glossary, the MkDocs site and its GitHub-compatible rendering rules, the final checks and the commit. Load for the assembly phase and /codelabgen:build.

Reads credentials

In this repository24 other files it gives its agents.
- code-authoringSkill
- codelabgen-orchestratorSkill
- course-extensionSkill
- curriculum-designSkill
- diagrammingSkill
- example-designSkill
- lesson-reviewSkill
- notes-writingSkill
- readalong-writingSkill
- runtime-strategySkill
- source-articlesSkill
- source-books-coursesSkill
- source-digestSkill
- source-evaluationSkill
- source-github-reposSkill
- source-official-blogSkill
- source-official-docsSkill
- source-package-internalsSkill
- source-papers-specsSkill
- source-qaSkill
- source-talks-workshopsSkill
- source-universitySkill
- state-protocolSkill
- topic-extractionSkill

The file

We split this skill into the rules it gives an agent

2 rules. About 0 are common, 0 are distinctive, and 2 are very specific to this project.

≈0
Common · estimate
Many files like this have a rule of this kind.
≈0
Distinctive · estimate
This author's own choices. Worth a look.
2
Very specific
Tied to their project's names, files or tools. Probably skip.

Common
Distinctive
Very specific

Very specific:
Not allowed, because GitHub shows them as broken text: !!!
line 41
Very specific:
Run from the main session, with --course <dir> on every command:
line 51

≈ “Common” is an estimate: at least 1 in 5 of the 350,495 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.

Files

SKILL.md

Assembling the course

A course is read in two places: on GitHub (or in an IDE) as plain Markdown, and as an MkDocs Material website. Both must look good. Assembly generates the pages that tie the lessons together, checks everything, builds the site and commits.

What is generated (never edit by hand)

codelabgen toc writes, from the curriculum and lesson specs:

File	Content
`README.md`	Course title, description, getting started (`.env`, `./run.sh`, the site), contents with summaries, the sources the course is built on (kept or added by the user; titles and links by type)
`<module>/README.md`, section READMEs	Title, summary, objectives, lesson list
`<lesson>/README.md`	Summary, "continues lesson X" note, objectives, links to notes / read-along / code, how to run and test, previous/next
`mkdocs.yml`	Site config and nav (only pages that exist)
`run.sh`	`./run.sh <id>`, `./run.sh test <id>`, `./run.sh list`, `./run.sh site serve`
`assets/`	MathJax setup, asciinema player hook and script
`GLOSSARY.md`, `assets/glossary-abbr.md`	From `.codelabgen/glossary.yaml` (`codelabgen glossary build`)

Labels in these files follow the course language. To change their wording, change the generator, not the files.

How Markdown features render

Feature	Written as	GitHub	Site
Code shown in the notes	`<!-- snippet: path#region -->` markers, filled by `codelabgen snippets sync`	Code block	Code block with highlighting and a copy button
Links into the code (read-along)	`[name](../src/…/file.py#L12)`, `#L12-L20` for a range	Opens the file, highlights the line	Opens the source file
Callouts	`> [!NOTE]`, `> [!TIP]`, `> [!WARNING]`, `> [!IMPORTANT]`	Native alerts	Admonitions (mkdocs-callouts)
Mermaid	```mermaid	Native	Native (Material)
Math	$…$ , `$$…$$`	Native	MathJax (arithmatex)
Glossary terms	A link on first use; definition in `GLOSSARY.md`	Link	Link, plus a tooltip on every use of the term or an alias
D2 / Graphviz	`![…](diagrams/x.svg)`	Image	Image
Recordings	`![…](generated/x.gif)`	Animated GIF	Interactive asciinema player
Hidden answers	`<details><summary>…</summary>…</details>`	Native	Native

Not allowed, because GitHub shows them as broken text: !!! / ??? admonitions, === content tabs, (1)! code annotations, --8<-- includes. codelabgen check render finds them.

Site details:

use_directory_urls: false, so relative links and paths work the same as on GitHub.
Heading anchors use GitHub's rules, including Cyrillic text (#граф-состояний).
Code files are part of the site, so links to ../src/<package>/graph.py work there too.
strict: true: any broken link or missing page fails the build.

The assembly procedure

Run from the main session, with --course <dir> on every command:

All lessons done: codelabgen state show shows every lesson done, then codelabgen state phase assembly.
Generate: codelabgen glossary build, then codelabgen toc.
Check: codelabgen check all. Fix every problem in the page that has it. For problems in a lesson's docs, send that lesson back (codelabgen state set <id> verified or readalong with a note) and let its writer fix it, then return here. Problems in generated files mean a generator bug: report it to the user.
Build the site: codelabgen site build must succeed (strict mode).
Commit: codelabgen commit -m "<message>", for example "Course: LangGraph на практике, lessons 1.1–1.3".
Stop the services: codelabgen services down (data volumes stay; ./run.sh <id> starts them again).
Done: codelabgen state phase done. Tell the user how to read the course: the course README.md, ./run.sh site serve, and ./run.sh <id> to run a lesson.

codelabgen site serve starts a local preview at http://127.0.0.1:8000 with live reload. It runs until stopped, so start it in the background only when the user asks for a preview.

Optional tools

codelabgen doctor lists them. Without d2 or dot, diagrams in those formats can't be rendered, so lessons should use Mermaid. Without asciinema and agg, recordings are skipped (verify logs "skipped"), and lessons must not link to recordings that don't exist.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

It worked
Partly
It didn't

What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

Check your setup, free