Knowledge HTML Learning Page Skill

Create source-grounded Chinese HTML learning pages from PDFs, Office files, Markdown, codebases, and web research. The skill is optimized for course notes, tutorials, formula-heavy lessons, code walkthroughs, and multi-file static learning sites.

The core workflow is: collect evidence, write draft.md, promote it to plan.md, get human review through review-gate.md, then generate HTML chapter by chapter with validation evidence.

Install with npx skills

Install from the public GitHub shorthand:

npx skills add MoveCloudROY/knowledge-html-learning-page

From another project, install a local checkout by path:

npx skills add /path/to/knowledge-html-learning-page --skill knowledge-html-learning-page

When working inside the skill directory, verify discovery before installing:

npx skills add . --list

No npm package.json or custom binary is required. The npx command runs the external skills CLI; this repository only needs a root SKILL.md and its referenced files to be discoverable.

Avoid installing the current .agents/skills/knowledge-html-learning-page directory into the same project that already contains it. Use --list for same-directory verification, or run the install command from a separate project so source and destination are different.

When to use

Use this skill when an agent needs to turn source material into Chinese learning pages with traceable evidence and review gates. Typical prompts include:

• 把这些课件整理成中文 HTML 学习页面。
• 根据这个代码库写一套教程页面。
• 先规划课程结构，再逐章生成可发布的 HTML。

Do not use it for quick summaries, one-off Markdown notes, or immediate HTML generation without a planning/review phase.

Required review gate

Do not generate final HTML before the human reviews the learning plan.

Before review, the agent may create source notes, extraction notes, draft.md, plan.md, and review-gate.md. It must not create final.html, dist/, full chapter HTML files, or claim a page is ready.

After review approval, each chapter is generated through the chapter loop: implement one chapter, validate it, evaluate it, record evidence, then decide keep, revise, or reject. Rejected chapters must be recorded in promotion-log.md.

Output structure

The skill writes intermediate work under .learning-pages/<topic>/. Common files include:

• source-index.md
• extracted-notes.md
• formula-notes.md
• image-inventory.md
• visual-extraction-notes.md when visual extraction is needed
• draft.md
• plan.md
• review-gate.md
• promotion-log.md after approved chapter generation begins

Generated pages should be document-style HTML: readable light theme, semantic sections, clear math rendering, accessible images, collapsed exercise answers, and separate chapter files when that improves review or search.

Local development and verification

Run the release-surface tests from the skill directory:

python3 -m pytest -q

Verify npx discovery from the skill directory:

npx skills add . --list

The test scenarios in references/skill-test-scenarios.md capture pressure cases that previously caused shallow plans or skipped chapter evidence. The final quality pass is defined in references/quality-checklist.md.

Risks and limitations

• Remote install depends on GitHub and the skills CLI being reachable from the current environment.
• The skill depends on agents actually following the review gate. Keep draft.md, plan.md, and review-gate.md explicit in prompts and audits.
• For PDFs, slides, scanned pages, complex formulas, and tables, pair this skill with the mineru skill and record visual extraction uncertainty when MinerU output is incomplete.
• Avoid duplicating the full workflow in this README. SKILL.md and the files in references/ are the source of truth.