Skill: doctorfff/skills-of-algorithm-learning-platform-builder (version 1.0.1)

--- name: algorithm-learning-platform-builder description: build interactive algorithm learning pages, comparison pages, and reusable teaching platforms for algorithms. use when chatgpt needs to plan, route, structure, explain, compare, or generate educational algorithm content with formulas, derivations, numerical substitution, step-by-step calculations, charts, interaction controls, family-aware teaching patterns, upgrade guidance, or complete runnable html demos. especially useful for turning algorithm explanations into interactive course pages, visualization-heavy study tools, or extensible algorithm learning platforms. --- # Core behavior Use this skill when the user wants to: - turn an algorithm explanation into an interactive teaching page - generate a runnable html algorithm demo - build a dynamic algorithm learning platform - compare multiple algorithms in one teaching page - create formula-driven, chart-rich, step-by-step educational content for any algorithm - upgrade an existing algorithm page into a stronger teaching platform - generalize a one-off algorithm page into a reusable platform structure This skill is for educational page generation, not production deployment. Default output should be structured, interactive, browser-runnable, and teaching-oriented. # Workflow Follow this order unless the user explicitly asks to skip planning: 1. identify the request type 2. identify the algorithm scope 3. identify the intended audience 4. decide the page type 5. design the teaching structure 6. identify formulas that must be explained 7. identify steps that must include numerical substitution 8. identify interaction controls 9. identify charts and visual components 10. generate structured content 11. generate runnable html if requested 12. run final quality checks ## 1. Identify the request type Classify the request into one of these types: - single algorithm teaching page - multi-algorithm comparison page - reusable algorithm learning platform - planning-only request - full runnable html request - upgrade request for an existing page or platform If the request is broad or ambitious, plan first. If the user explicitly asks for complete code, provide complete runnable html after planning. If the request mixes planning, comparison, and generation, use `references/request-routing-rules.md` to decide the best output mode. ## 2. Identify the algorithm scope Determine whether the requested content is about: - one specific algorithm - a family of related algorithms - a comparison between multiple algorithms - a generic reusable platform that should work for many algorithms If the user names a specific algorithm, preserve algorithm-specific formulas and workflow. If the user asks for a reusable platform, make the page architecture modular and extensible. Then map the request to an algorithm family using `references/algorithm-family-maps.md`. Use that mapping to decide: - what the page should emphasize - what formulas are central - what numerical substitution is required - what interactions are most useful - what charts best fit the algorithm family - whether the request should become a single page, a comparison page, or a reusable platform page ## 3. Identify the intended audience Adapt the output to the user's level. For beginners: - use simpler language - reduce jargon - explain intuition before formulas - always include more numerical substitution - prefer more visible step-by-step interaction For advanced users: - allow more mathematical detail - include formula comparisons - include parameter interpretation - include stronger theoretical distinctions ## 4. Decide the page type Use one of these page structures: - single algorithm page - comparison page - algorithm learning platform Use the references in: - `references/page-architecture.md` - `references/algorithm-page-template.md` - `references/comparison-page-template.md` - `references/request-routing-rules.md` If the request is ambiguous, mixed, or overly broad, prefer the page type recommended by `references/request-routing-rules.md`. ## 5. Design the teaching structure Every algorithm page should combine: - intuition - formulas - symbol explanation - why the formula is used - numerical substitution - dynamic interaction - charts - results and summary Do not produce concept-only pages unless the user explicitly asks for conceptual explanation only. ## 6. Identify formulas that must be explained For each important formula, explain it in four layers: 1. write the formula 2. explain each symbol 3. explain why the formula is used 4. substitute concrete numbers whenever possible This is a required output pattern for any algorithm teaching page. ## 7. Identify steps that must include numerical substitution Whenever the algorithm has a real computation flow, include numerical substitution for at least these stages when possible: - initialization - key update rule - scoring or loss calculation - iteration result - final conclusion or ranking If exact numbers are not provided by the user, create a small teaching example dataset. ## 8. Identify interaction controls Use interaction when it materially improves understanding. Good candidates for interaction: - parameter sliders - dropdowns for task switching - stepper buttons for multi-stage computation - algorithm toggles for comparison pages - chart updates linked to user input Do not add interaction just for decoration. Use it where the algorithm changes across steps, parameters, or variants. ## 9. Identify charts and visual components Charts should reinforce the mathematics. Prefer clear, educational visualizations. Examples: - loss curves - score comparison bars - probability curves - radar charts - residual charts - cumulative update charts - comparison tables ## 10. Generate structured content When the user asks for planning only: - provide a structured plan - explain the page architecture - explain how to upgrade it further - identify the current maturity level if the user is improving an existing page - identify the best next upgrade When the user asks for content: - produce structured, teaching-oriented content - keep sections modular - ensure mathematical consistency across sections Before finalizing a plan or page, use `references/platform-upgrade-rules.md` to determine: - the current maturity level of the output - the most valuable next upgrade - whether the page should remain single-algorithm or evolve into comparison/platform mode - which improvements add teaching value first ## 11. Generate runnable html if requested When generating html: - prefer a single-file html page - keep the output directly runnable in a browser - use chart.js and mathjax when helpful - keep the layout presentation-ready - keep interaction smooth and beginner-friendly - ensure the final output is complete and internally consistent - do not omit required closing tags or script blocks Use the html starter file in `assets/html-starter-template.html` when building a new single-file page. ## 12. Run final quality checks Before returning any major output, validate it against `references/output-quality-checklist.md`. Check: - structural clarity - educational value - formula explanation quality - numerical substitution completeness - interaction usefulness - chart relevance - html completeness - reusability when platform mode is requested If several of these are weak, improve the output before finalizing. # Design rules Use the guidance from these references: - `references/page-architecture.md` - `references/explanation-patterns.md` - `references/interaction-patterns.md` - `references/algorithm-page-template.md` - `references/comparison-page-template.md` - `references/writing-rules.md` - `references/algorithm-family-maps.md` - `references/platform-upgrade-rules.md` - `references/request-routing-rules.md` - `references/output-quality-checklist.md` # Output rules ## For planning requests Output should include: - page goal - page type - teaching structure - formulas to explain - numerical substitution points - interactive controls - chart list - current maturity level if relevant - best next upgrade - upgrade path ## For html requests Output should include: - complete runnable html - all required sections - formulas and numerical explanation - interaction controls if useful - charts if useful - a coherent teaching flow - internal consistency between formulas, data, controls, charts, and results ## For upgrade requests Output should include: - what the current page already does - what it is missing - the current maturity level - the most valuable upgrades in order - the recommended target structure - updated content or updated html if requested # Important boundaries - This skill is for learning pages, demos, course pages, algorithm explainers, and study tools. - This skill is not for production-grade model training infrastructure. - This skill should favor clarity, structure, and educational value over engineering complexity. - If a request is better handled as a static outline rather than a full page, provide the outline first. - If the request is ambiguous, broad, or mixes several goals, route it using `references/request-routing-rules.md` before generating output. # Quality standard A good output from this skill should make the user feel: - the algorithm is understandable - the formulas are not abstract anymore - the numerical process is visible - the page is runnable and presentable - the structure is reusable for future algorithms - the upgrade path is clear when the user wants to improve the platform

path: README.md
content: # skills-of-algorithm-learning-platform-builder

---

# 🧠 skills-of-algorithm-learning-platform-builder

<div style="background-color:#f8f4eb; padding: 16px 20px; border-radius:12px; border: 1px solid #e8dfcf;">
<strong>algorithm-learning-platform-builder</strong> 是一套面向 AI 智能体的结构化技能规范，
让 AI 自动生成 <span style="color:#a98345;">可交互、可视化、可直接运行</span> 的算法教学网页，
帮助零基础小白直观理解机器学习、优化算法、统计聚类等原理，
告别抽象公式，用 <span style="color:#a98345;">可操作、可计算、可看图</span> 的方式学习算法。
</div>

---

## 📁 项目架构

```text
algorithm-learning-platform-builder/
├── SKILL.md                   # 🧩 技能总入口：AI 执行工作流与规则
├── agents/
│   └── openai.yaml            # 🤖 智能体配置：名称、图标、主题色
├── references/                # 📚 全套教学规范与模板
│   ├── page-architecture.md           # 🏛️ 页面结构规范
│   ├── explanation-patterns.md        # 📐 公式与步骤讲解规范
│   ├── interaction-patterns.md        # 🎛️ 交互控件设计规则
│   ├── algorithm-page-template.md     # 🧾 单算法页面模板
│   ├── comparison-page-template.md    # 📊 多算法对比模板
│   ├── writing-rules.md              # ✍️ 教学文案规范
│   ├── algorithm-family-maps.md      # 🌱 算法家族分类
│   ├── platform-upgrade-rules.md      # 🚀 平台升级规则
│   ├── request-routing-rules.md       # 🧭 请求路由规则
|   ├──request-routing-rules.md
│   └── output-quality-checklist.md    # ✅ 输出质量检查清单
└── assets/
    └── html-starter-template.html     # 🧪 可直接运行 HTML 模板
```

---

## 🎯 解决的痛点

- 📉 **算法公式太抽象**
  → 强制 **公式四步讲解 + 数值代入计算**
- 🧠 **新手看不懂推导**
  → 固定教学流：**直觉 → 公式 → 步骤 → 图表**
- 📝 **纯文字记不住**
  → 自动生成 **滑块、步进器、下拉切换** 交互
- 🔀 **多个算法易混淆**
  → 一键生成 **对比页 + 对比图表 + 场景建议**
- 🧱 **自建学习平台麻烦**
  → 提供 **模块化、可扩展** 架构，开箱即用

---

## ✨ 主要生成能力

### 1. 📘 单算法教学页面
完整讲解单个算法，包含：直觉、公式、分步计算、交互控制、可视化图表、结果总结。

### 2. 📊 多算法对比教学页面
同一任务下横向对比：公式、参数、流程、效果、优缺点，并给出使用建议。

### 3. 🧩 可复用算法学习平台
稳定外壳 + 可切换算法模块，支持无限扩展，形成通用交互式学习平台。


---------------
1.Topsis单算法页面教学
<img width="2013" height="990" alt="image" src="https://github.com/user-attachments/assets/69eca7ca-e43f-4e70-97b1-49aa25668fab" />
<img width="2190" height="1071" alt="image" src="https://github.com/user-attachments/assets/46f1ca15-5c6c-421a-acf1-6633ea4e3664" />
<img width="2091" height="1370" alt="image" src="https://github.com/user-attachments/assets/2773f0a0-c677-4a32-b8ad-71a5160e064c" />
<img width="2265" height="1377" alt="image" src="https://github.com/user-attachments/assets/2eb7e17a-7d16-4745-90b0-d2d9527ca8f7" />
-----------------
2.梯度树多算法对比教学
<img width="2177" height="1352" alt="image" src="https://github.com/user-attachments/assets/15b8b221-15a8-4444-8f23-52033470e78b" />
<img width="2277" height="1329" alt="image" src="https://github.com/user-attachments/assets/77a962e0-1bad-4014-a252-a5779053f08f" />
<img width="2328" height="1290" alt="image" src="https://github.com/user-attachments/assets/bc93eebf-86e6-4d3d-8c82-2d02a49594ed" />
<img width="2421" height="1410" alt="image" src="https://github.com/user-attachments/assets/579510f1-af48-4de9-87af-5e4952f3fe6a" />
------------------
样例结果下载
[sample.zip](https://github.com/user-attachments/files/26608090/sample.zip)








path: references/algorithm-family-maps.md
content: # Algorithm Family Maps

This file defines reusable family-level patterns for algorithm teaching pages and algorithm learning platforms.

Its purpose is to help the skill quickly determine:
- what kind of algorithm the user is asking about
- what page structure fits that family
- which formulas must be explained
- which interactions are most useful
- which charts are most educational
- how to scale from a single page to a family comparison page

---

# Table of Contents

1. Purpose
2. General family classification rules
3. Multi-criteria decision-making algorithms
4. Classical machine learning algorithms
5. Optimization algorithms
6. Statistical and dimensionality-reduction algorithms
7. Clustering and unsupervised learning algorithms
8. Tree and ensemble algorithms
9. Time-series and forecasting algorithms
10. Graph and network algorithms
11. Numerical methods algorithms
12. Deep learning related algorithms
13. How to use this file

---

# 1. Purpose

When the user asks for an algorithm page, first map the request into an algorithm family.

This family mapping helps determine:
- what the page should emphasize
- what formulas are central
- what numerical substitution is necessary
- what visual interaction is most useful
- whether the request should become:
  - a single algorithm page
  - a comparison page
  - a reusable platform page

This file is not an exhaustive taxonomy of all algorithms.
It is a practical design map for teaching-page generation.

---

# 2. General Family Classification Rules

## 2.1 First decide whether the algorithm is mainly about:
- scoring or evaluation
- prediction
- classification
- optimization
- decomposition
- clustering
- iteration
- search
- approximation
- graph structure
- representation learning

## 2.2 Then identify the family

### Common family types
- multi-criteria decision-making
- classical supervised learning
- optimization
- statistical / dimensionality reduction
- clustering / unsupervised learning
- tree ensembles
- time-series / forecasting
- graph algorithms
- numerical methods
- deep learning

## 2.3 Then decide the page type

### Use a single algorithm page when:
- the user wants one algorithm explained deeply
- the workflow is already rich enough by itself
- the educational goal is understanding one method clearly

### Use a comparison page when:
- the user names two or more algorithms
- the user asks for advantages, differences, or “which is better”
- the family naturally contains closely related methods

### Use a reusable platform page when:
- the user wants a general tool for many algorithms
- the request mentions “platform”, “switch”, “toggle”, “generalize”, “for any algorithm”
- the user wants modular extension

---

# 3. Multi-Criteria Decision-Making Algorithms

Examples:
- AHP
- entropy weight method
- TOPSIS
- CRITIC
- fuzzy comprehensive evaluation
- grey relational analysis
- combination weighting
- VIKOR

## 3.1 Core teaching goal
Help the learner understand:
- how indicators are weighted
- how scores are computed
- how ranking is generated
- why one weighting or scoring formula is chosen over another

## 3.2 Best page type
- single algorithm page for one method
- comparison page for weighting-method comparisons
- platform page for “evaluation-method toolkit” requests

## 3.3 Must-explain formulas
Usually include:
- normalization formula
- weight calculation formula
- score / closeness / distance formula
- ranking formula
- consistency formula if relevant
- objective function if relevant

## 3.4 Must-show numerical substitution
Usually show:
- original matrix
- normalized matrix
- weight derivation
- score derivation
- ranking result

## 3.5 Useful interactions
- matrix editing
- indicator direction switching
- parameter sliders
- weighting method toggles
- ranking recomputation
- step navigation

## 3.6 Useful charts
- weight bar chart
- score bar chart
- radar chart
- sensitivity analysis chart
- rank comparison chart

## 3.7 Good comparison dimensions
- subjective vs objective weighting
- interpretability
- sensitivity to data
- suitability for small samples
- ranking stability

---

# 4. Classical Machine Learning Algorithms

Examples:
- linear regression
- logistic regression
- k-nearest neighbors
- naive bayes
- support vector machine
- decision tree

## 4.1 Core teaching goal
Help the learner understand:
- what prediction target is being learned
- what function or rule maps input to output
- how the model parameters or decision logic are obtained
- how predictions are made

## 4.2 Best page type
- single algorithm page for one learner-facing explanation
- comparison page for model comparison
- platform page for “classical ML study tool” requests

## 4.3 Must-explain formulas
Usually include:
- hypothesis / prediction function
- loss function or decision rule
- parameter update or fitting rule
- classification boundary or probability formula

## 4.4 Must-show numerical substitution
Usually show:
- one sample prediction
- one loss or score computation
- one update step if iterative
- one boundary or decision example

## 4.5 Useful interactions
- sample editing
- parameter sliders
- feature toggles
- task switching between regression and classification
- prediction buttons

## 4.6 Useful charts
- regression fit plot
- decision boundary plot
- probability curve
- confusion-style summary
- parameter sensitivity curve

## 4.7 Good comparison dimensions
- interpretability
- training cost
- nonlinear capability
- probability output
- robustness

---

# 5. Optimization Algorithms

Examples:
- gradient descent
- stochastic gradient descent
- Newton method
- simulated annealing
- genetic algorithm
- particle swarm optimization
- Lagrange multiplier methods

## 5.1 Core teaching goal
Help the learner understand:
- what objective is being minimized or maximized
- how the update rule moves the solution
- why convergence behavior changes with parameters
- how iteration affects results

## 5.2 Best page type
- single algorithm page for one optimization method
- comparison page for multiple optimizers
- platform page for “optimization visualizer” requests

## 5.3 Must-explain formulas
Usually include:
- objective function
- gradient or search direction
- update rule
- convergence criterion
- step-size rule if relevant

## 5.4 Must-show numerical substitution
Usually show:
- initial point
- first gradient
- first update
- later update comparison
- objective value change

## 5.5 Useful interactions
- learning rate slider
- iteration count
- initialization control
- optimizer switch
- convergence threshold control

## 5.6 Useful charts
- objective curve
- parameter trajectory
- contour path
- convergence comparison chart

## 5.7 Good comparison dimensions
- convergence speed
- stability
- sensitivity to initialization
- computational cost
- local vs global search

---

# 6. Statistical and Dimensionality-Reduction Algorithms

Examples:
- PCA
- factor analysis
- LDA
- ICA
- SVD-based methods

## 6.1 Core teaching goal
Help the learner understand:
- how high-dimensional information is transformed
- what variance, covariance, or projection means
- how components are extracted
- how much information is preserved

## 6.2 Best page type
- single algorithm page for PCA or FA
- comparison page for PCA vs FA vs LDA
- platform page for dimensionality reduction modules

## 6.3 Must-explain formulas
Usually include:
- covariance matrix
- eigenvalue / eigenvector relationship
- projection formula
- explained variance ratio
- loading matrix if relevant

## 6.4 Must-show numerical substitution
Usually show:
- input matrix
- covariance matrix
- eigenvalues
- selected components
- projected coordinates

## 6.5 Useful interactions
- number of components selector
- sample matrix editing
- standardized vs non-standardized toggle
- variance threshold slider

## 6.6 Useful charts
- scree plot
- explained variance bar chart
- projected scatter plot
- loading heatmap
- component contribution chart

## 6.7 Good comparison dimensions
- interpretability
- supervision or unsupervision
- dimensionality reduction quality
- variance explanation
- factor meaning

---

# 7. Clustering and Unsupervised Learning Algorithms

Examples:
- KMeans
- hierarchical clustering
- DBSCAN
- Gaussian mixture model
- spectral clustering

## 7.1 Core teaching goal
Help the learner understand:
- how samples are grouped
- how cluster centers or cluster rules are formed
- how the algorithm updates cluster assignments
- what parameters affect cluster quality

## 7.2 Best page type
- single algorithm page for one clustering method
- comparison page for clustering methods
- platform page for clustering visualizer requests

## 7.3 Must-explain formulas
Usually include:
- distance function
- objective function
- assignment rule
- update rule
- density condition if relevant

## 7.4 Must-show numerical substitution
Usually show:
- sample coordinates
- initial cluster state
- one reassignment step
- one centroid update
- final cluster grouping

## 7.5 Useful interactions
- cluster count slider
- epsilon / minPts controls
- initialization switch
- dataset selector

## 7.6 Useful charts
- scatter plot
- centroid movement plot
- cluster comparison chart
- silhouette or compactness summary

## 7.7 Good comparison dimensions
- need for predefined cluster count
- sensitivity to noise
- shape flexibility
- scalability
- interpretability

---

# 8. Tree and Ensemble Algorithms

Examples:
- decision tree
- random forest
- GBDT
- XGBoost
- LightGBM
- AdaBoost

## 8.1 Core teaching goal
Help the learner understand:
- how tree structure is built
- how split criteria are chosen
- how ensemble methods combine weak learners
- how different boosting or bagging methods differ

## 8.2 Best page type
- single algorithm page for one tree algorithm
- comparison page for tree-family comparison
- platform page for tree-learning platform requests

## 8.3 Must-explain formulas
Usually include:
- split criterion
- impurity or gain formula
- update rule for boosting
- weighting rule
- regularization terms for advanced boosting

## 8.4 Must-show numerical substitution
Usually show:
- first split
- leaf value calculation
- one iteration update
- final prediction calculation

## 8.5 Useful interactions
- depth control
- tree count control
- learning rate slider
- algorithm switch
- task switch
- iteration stepper

## 8.6 Useful charts
- loss curve
- prediction comparison chart
- residual chart
- feature importance chart
- split gain chart
- multi-model comparison chart

## 8.7 Good comparison dimensions
- one-stage vs iterative learning
- first-order vs second-order optimization
- regularization
- engineering speed
- interpretability

---

# 9. Time-Series and Forecasting Algorithms

Examples:
- moving average
- exponential smoothing
- ARIMA
- Holt-Winters
- simple forecasting baselines

## 9.1 Core teaching goal
Help the learner understand:
- what the algorithm assumes about temporal dependence
- how the forecast is updated over time
- how trend and seasonality are handled
- how future values are generated

## 9.2 Best page type
- single algorithm page for a forecasting method
- comparison page for forecasting methods
- platform page for time-series learning tools

## 9.3 Must-explain formulas
Usually include:
- forecast update formula
- smoothing formula
- trend or seasonal update if relevant
- error measure

## 9.4 Must-show numerical substitution
Usually show:
- a short time series
- one forecast step
- one update step
- error calculation

## 9.5 Useful interactions
- smoothing parameter slider
- forecast horizon control
- seasonality toggle
- model switch

## 9.6 Useful charts
- time-series line chart
- forecast vs actual chart
- residual chart
- rolling error chart

## 9.7 Good comparison dimensions
- interpretability
- trend handling
- seasonality handling
- data requirement
- forecasting horizon suitability

---

# 10. Graph and Network Algorithms

Examples:
- shortest path
- PageRank
- minimum spanning tree
- max flow
- graph traversal
- community detection basics

## 10.1 Core teaching goal
Help the learner understand:
- what structure the algorithm operates on
- how updates travel through the graph
- how node or edge values are computed
- how the final graph-level or node-level result is determined

## 10.2 Best page type
- single algorithm page for one graph method
- comparison page for related graph methods
- platform page for graph algorithm visualizer requests

## 10.3 Must-explain formulas
Usually include:
- update or propagation rule
- path cost formula
- centrality or score update formula
- stopping condition

## 10.4 Must-show numerical substitution
Usually show:
- a small graph
- one iteration or traversal step
- one cost or score update
- final result

## 10.5 Useful interactions
- edge editing
- node weight editing
- source/target selection
- step traversal buttons

## 10.6 Useful charts
- graph visualization
- cost evolution chart
- node score chart
- path summary table

## 10.7 Good comparison dimensions
- exactness
- efficiency
- static vs dynamic graph suitability
- weighted vs unweighted applicability

---

# 11. Numerical Methods Algorithms

Examples:
- Newton interpolation
- Lagrange interpolation
- least squares approximation
- best approximation
- numerical integration
- root-finding methods

## 11.1 Core teaching goal
Help the learner understand:
- what numerical problem is being solved
- how approximations are constructed
- how formulas are built from known points
- how error behaves

## 11.2 Best page type
- single algorithm page for one numerical method
- comparison page for related numerical methods
- platform page for numerical methods teaching toolkit

## 11.3 Must-explain formulas
Usually include:
- interpolation or approximation formula
- basis function definition
- update or recursive form
- error term if appropriate

## 11.4 Must-show numerical substitution
Usually show:
- sample points
- basis construction
- one interpolated value
- one error comparison

## 11.5 Useful interactions
- point editing
- polynomial degree selector
- function selector
- error chart toggle

## 11.6 Useful charts
- curve plot
- interpolation vs true function chart
- error curve
- node distribution chart

## 11.7 Good comparison dimensions
- stability
- approximation quality
- error sensitivity
- computational complexity
- interpretability

---

# 12. Deep Learning Related Algorithms

Examples:
- perceptron
- backpropagation demo
- simple neural network
- attention basics
- convolution basics

## 12.1 Core teaching goal
Help the learner understand:
- layered transformation
- forward computation
- loss computation
- gradient-based update
- role of parameters

## 12.2 Best page type
- single algorithm page for one concept
- comparison page for architecture comparison
- platform page for neural network teaching tool requests

## 12.3 Must-explain formulas
Usually include:
- forward pass
- activation function
- loss function
- gradient or update rule

## 12.4 Must-show numerical substitution
Usually show:
- one forward pass
- one loss value
- one gradient example
- one parameter update

## 12.5 Useful interactions
- weight editing
- learning rate slider
- epoch slider
- architecture toggle
- activation selector

## 12.6 Useful charts
- loss curve
- activation curve
- parameter update chart
- prediction comparison chart

## 12.7 Good comparison dimensions
- expressiveness
- interpretability
- training cost
- data requirement
- optimization difficulty

---

# 13. How to Use This File

When a new user request arrives:

1. identify the algorithm family
2. choose the corresponding teaching pattern
3. choose the page type
4. determine the formulas that must be explained
5. determine the numerical substitutions that must appear
6. determine the interactions that are actually useful
7. determine the charts that best fit that family

This file should guide structure and emphasis.
It should not force every page into the same exact visual output.

The main goal is:
- preserve educational clarity
- preserve family-specific teaching logic
- make the generated page feel natural for that algorithm family

path: references/algorithm-page-template.md
content: # Algorithm Page Template

Use this template when generating a single algorithm teaching page.

## Table of Contents
1. Goal
2. Section structure
3. Required content
4. Output checklist

---

## 1. Goal

A single algorithm page should help the learner:
- understand what the algorithm does
- understand why its formulas are used
- see how values are computed
- interact with the algorithm where useful
- interpret the result clearly

---

## 2. Section Structure

### Standard structure
1. hero intro
2. algorithm overview
3. problem definition
4. input and parameter area
5. core formulas
6. step-by-step derivation or computation
7. numerical example
8. interactive controls
9. charts
10. result summary
11. auto-generated explanation or conclusion

---

## 3. Required Content

A strong algorithm page should include:
- at least one intuition section
- at least one formula explanation block
- at least one numerical substitution block
- at least one result interpretation section
- charts if the algorithm output is numeric or iterative

### For dynamic pages
Include at least one of:
- slider
- stepper
- dropdown
- algorithm mode toggle

---

## 4. Output Checklist

Before finalizing the page, verify:
- the formulas match the narrative
- the numerical example matches the data shown
- the interactions update meaningful content
- the charts reflect the algorithm's behavior
- the html is complete and runnable

path: references/comparison-page-template.md
content: # Comparison Page Template

Use this template when the user wants to compare multiple algorithms in one page.

## Table of Contents
1. Goal
2. Section structure
3. Required comparison dimensions
4. Output checklist

---

## 1. Goal

A comparison page should help the learner understand:
- what the algorithms have in common
- where they differ mathematically
- where they differ operationally
- how their outputs differ on the same setup
- when each algorithm is more suitable

---

## 2. Section Structure

### Recommended structure
1. hero intro
2. shared task definition
3. algorithm summary cards
4. shared data and assumptions
5. formula comparison section
6. parameter comparison section
7. chart comparison section
8. result comparison table
9. final recommendation section

---

## 3. Required Comparison Dimensions

When possible, compare:
- core intuition
- target function or objective
- update rule
- parameters
- computational structure
- output behavior
- strengths and limitations

If the algorithms are in the same family, explicitly show:
- what is inherited
- what is newly added
- what is optimized or changed

---

## 4. Output Checklist

Before finalizing a comparison page, verify:
- the comparison uses a shared setup where possible
- formulas are not presented as isolated fragments
- differences are visible, not implied
- tables and charts reinforce the comparison
- the final recommendation is grounded in the content shown earlier

path: references/explanation-patterns.md
content: # Explanation Patterns

This file defines how algorithm explanations should be written.

## Table of Contents
1. Formula explanation pattern
2. Algorithm explanation order
3. Numerical substitution pattern
4. Beginner adaptation
5. Advanced adaptation

---

## 1. Formula Explanation Pattern

For each important formula, explain it in four layers.

### Required pattern
1. write the formula
2. explain each symbol
3. explain why this formula is used
4. substitute concrete numbers whenever possible

### Example structure
- Formula:
  $$y = ax + b$$
- Symbol meaning:
  - y: output
  - x: input
  - a: slope
  - b: intercept
- Why it is used:
  This formula describes a linear relation between input and output.
- Numerical substitution:
  If x = 2, a = 3, b = 1, then y = 3×2 + 1 = 7.

This pattern should be reused for algorithm updates, loss functions, scoring rules, probability formulas, decomposition formulas, and optimization targets.

---

## 2. Algorithm Explanation Order

Prefer this order for a single algorithm:
1. what problem it solves
2. intuition
3. mathematical formulation
4. key formulas
5. step-by-step process
6. numerical example
7. interactive controls
8. charts
9. result interpretation

This order makes the page readable for both beginners and intermediate learners.

---

## 3. Numerical Substitution Pattern

Whenever the algorithm includes a real computation chain, show numerical substitution in at least these places when possible:
- initialization
- first major formula
- intermediate update
- final score or result

Good numerical substitution is:
- short
- local to the formula
- clearly linked to symbols
- consistent with the data shown elsewhere on the page

Avoid symbolic-only explanation when the user clearly wants a teaching page.

---

## 4. Beginner Adaptation

For beginners:
- explain intuition before notation
- do not overload sections with too many formulas at once
- add small examples
- explain what changes after each step
- prefer simple language

Typical signs a beginner page needs:
- more substitution
- more small notes
- more visible process
- fewer compressed theoretical statements

---

## 5. Advanced Adaptation

For advanced users:
- allow denser mathematical detail
- compare variants of formulas
- discuss parameter meaning more deeply
- include complexity or optimization interpretation where relevant

Even for advanced outputs, keep the structure readable.
Do not turn the page into a raw note dump.

path: references/interaction-patterns.md
content: # Interaction Patterns

This file defines common interaction patterns for algorithm teaching pages.

## Table of Contents
1. When to add interaction
2. Common controls
3. Good interaction use cases
4. Bad interaction use cases
5. Comparison mode interaction

---

## 1. When to Add Interaction

Add interaction when it improves understanding of:
- parameter sensitivity
- multi-step iteration
- stage-by-stage updates
- algorithm switching
- task switching
- output changes caused by user input

Do not add interaction purely for visual decoration.

---

## 2. Common Controls

### Sliders
Use for:
- learning rate
- iteration count
- regularization strength
- threshold values
- sample size or ratio parameters

### Dropdowns
Use for:
- task type
- algorithm selection
- loss function selection
- mode switching

### Step buttons / steppers
Use for:
- multi-step algorithms
- iterative updates
- stage-by-stage derivation walkthroughs

### Toggle switches
Use for:
- optional features
- comparison mode
- display mode changes

---

## 3. Good Interaction Use Cases

### Good examples
- changing alpha in a weighted scoring model
- changing the number of iterations in gradient descent
- switching between regression and classification views
- switching between GBDT, XGBoost, and LightGBM in one platform
- stepping through each iteration of an algorithm

---

## 4. Bad Interaction Use Cases

Avoid interaction when:
- the algorithm is static and no concept changes with input
- the control does not change any meaningful output
- the page becomes more confusing than helpful
- the controls outnumber the actual teaching content

---

## 5. Comparison Mode Interaction

For comparison pages, useful controls include:
- algorithm selector
- compare-all toggle
- shared parameter panel
- task selector

Comparison mode should emphasize:
- shared inputs
- different outputs
- visible differences in formulas, charts, or results

path: references/page-architecture.md
content: # Page Architecture

This file defines reusable structures for algorithm teaching pages.

## Table of Contents
1. Single Algorithm Page
2. Comparison Page
3. Reusable Platform Page
4. Section Ordering Rules
5. Page Construction Notes

---

## 1. Single Algorithm Page

Use this structure when the user wants to explain one algorithm clearly.

### Recommended section order
1. hero / page intro
2. algorithm overview
3. input data and parameters
4. formula core
5. step-by-step calculation
6. interactive controls
7. charts and visualization
8. results and conclusion
9. auto-generated summary text

### Purpose of each section
- hero: define what the page is about
- overview: explain intuition and use case
- input section: show what the algorithm consumes
- formula core: present mathematical basis
- step-by-step section: make computation visible
- interaction: allow parameter or step changes
- charts: visualize behavior and outcomes
- results: summarize what happened

---

## 2. Comparison Page

Use this when the user wants to compare multiple algorithms.

### Recommended section order
1. hero / comparison goal
2. shared problem setup
3. comparison summary table
4. per-algorithm intuition cards
5. formula comparison section
6. parameter comparison section
7. chart comparison section
8. result comparison table
9. conclusion and recommendation

### Key rule
A comparison page must show both:
- shared structure
- meaningful differences

It should never present multiple algorithms as if they are only name variations.

---

## 3. Reusable Platform Page

Use this when the user wants a general platform that can be extended to many algorithms.

### Recommended section order
1. hero / platform intro
2. algorithm selector
3. task selector
4. shared data input area
5. shared parameter area
6. algorithm-specific formula area
7. algorithm-specific step area
8. shared chart area
9. shared result area
10. comparison mode or extension area

### Platform principles
- keep the outer structure stable
- make the inner algorithm modules switchable
- separate common sections from algorithm-specific sections
- design for extensibility

---

## 4. Section Ordering Rules

General rule:
- intuition before abstraction
- formulas before detailed computation
- detailed computation before charts
- charts before final conclusion

Avoid this order:
- large code first
- charts before formulas
- final results without showing how they were obtained

---

## 5. Page Construction Notes

### Always include
- a clear learning objective
- visible formulas
- visible numerical process when applicable
- a structured section flow

### Prefer
- card-based layout
- one main idea per section
- one chart per visual purpose
- modular design for extension

### Avoid
- overly dense concept dumps
- giant unbroken code blocks before explanation
- formula-only pages without narrative explanation

path: references/platform-upgrade-rules.md
content: # Platform Upgrade Rules

This file defines how to evolve a generated algorithm teaching page into a stronger, more reusable, more complete learning platform.

Its purpose is to help the skill answer questions like:
- how should this page be upgraded
- what should be added next
- what is the best version of this platform
- how do we generalize from one algorithm to many algorithms
- how do we move from a single demo to a reusable educational system

---

# Table of Contents

1. Purpose
2. General upgrade principle
3. Upgrade ladder
4. What to upgrade first
5. Single algorithm page upgrade rules
6. Comparison page upgrade rules
7. Reusable platform upgrade rules
8. Interaction upgrade rules
9. Visualization upgrade rules
10. Writing and explanation upgrade rules
11. Architecture upgrade rules
12. Reusability upgrade rules
13. Quality checkpoints
14. Final standard

---

# 1. Purpose

Not every user request should produce the biggest possible platform immediately.

This file helps determine:
- what the current version already does
- what its current limitations are
- what the next most valuable upgrade is
- what the “best version” should look like

The skill should use these rules to avoid:
- overbuilding too early
- adding features without teaching value
- creating pages that are flashy but structurally weak

---

# 2. General Upgrade Principle

Always upgrade in this order:

1. structure
2. explanation
3. interaction
4. visualization
5. comparison
6. reusability
7. export or platform convenience features

In other words:
- first make the page understandable
- then make the formulas visible
- then make the computation visible
- then make it dynamic
- then make it extensible

Do not start by adding decorative features.

---

# 3. Upgrade Ladder

Use this ladder to determine the maturity level of the current page.

## Level 1 — Static Explanation Page
Characteristics:
- concept explanation
- little or no interaction
- formulas may exist
- weak numerical process

Good for:
- quick notes
- simple overviews

Limitations:
- low teaching depth
- weak retention
- weak reuse

## Level 2 — Structured Teaching Page
Characteristics:
- clear section flow
- formulas explained
- visible numerical substitution
- result interpretation

Good for:
- coursework
- presentations
- readable algorithm study notes

Limitations:
- limited interactivity
- weak parameter sensitivity exploration

## Level 3 — Interactive Algorithm Page
Characteristics:
- parameters can be changed
- charts update
- steps are visible
- some dynamic recomputation

Good for:
- learning through experimentation
- algorithm demos
- class explanation

Limitations:
- still centered on one algorithm
- limited comparison power

## Level 4 — Comparison Page
Characteristics:
- multiple algorithms can be compared
- shared task setup
- shared result comparison
- visible formula and workflow differences

Good for:
- understanding families of methods
- choosing between methods
- high teaching value

Limitations:
- may still be hard to extend
- often still page-specific

## Level 5 — Reusable Learning Platform
Characteristics:
- shared outer structure
- switchable algorithm modules
- scalable architecture
- reusable templates
- supports future algorithm expansion

Good for:
- long-term project reuse
- publishing a family-level teaching tool
- general educational product design

---

# 4. What to Upgrade First

When deciding upgrades, prefer the smallest change that creates the largest teaching value.

## Upgrade priority order
1. add missing formula explanation
2. add numerical substitution
3. add visible step-by-step process
4. add meaningful controls
5. add charts that reinforce the math
6. add result interpretation
7. add comparison capability
8. add export or polish features

## Never prioritize first
- decorative animation
- complex framework migration without need
- too many controls with little educational purpose
- excessive styling before content quality is stable

---

# 5. Single Algorithm Page Upgrade Rules

If the current page explains only one algorithm, evaluate it with these questions:

## 5.1 Structure check
Does it already include:
- algorithm goal
- intuition
- formulas
- numerical substitution
- result explanation

If not, upgrade structure first.

## 5.2 Formula check
If formulas are present but unexplained:
- add symbol explanation
- add why-this-formula explanation
- add substitution examples

## 5.3 Process check
If the page has formulas but no visible computation flow:
- add stepper
- add iteration breakdown
- add row-by-row or stage-by-stage tables

## 5.4 Interaction check
If the algorithm changes under parameters:
- add sliders
- add dropdowns
- add toggles
- add recalculation buttons or live updates

## 5.5 Visualization check
If the output is numeric or iterative:
- add at least one chart
- ensure chart meaning is explained
- avoid unmotivated visuals

## 5.6 Result upgrade
If the page calculates something important:
- add summary cards
- add auto-generated conclusion text
- add final result table

---

# 6. Comparison Page Upgrade Rules

If the page already compares multiple algorithms, ask:

## 6.1 Are the shared assumptions visible?
A good comparison page should clearly show:
- same data
- same task
- same output target
- same or intentionally different parameters

If not, add a shared setup section.

## 6.2 Are differences explicit?
A comparison page must explicitly compare:
- formulas
- workflow
- parameters
- results
- strengths and limitations

If differences are only implied, add tables and aligned sections.

## 6.3 Is the comparison visual enough?
Upgrade by adding:
- side-by-side formula cards
- side-by-side result cards
- comparison charts
- algorithm difference summary table

## 6.4 Is there a recommendation section?
A good comparison page should end with:
- when to use algorithm A
- when to use algorithm B
- what tradeoff matters most

If missing, add a final recommendation section.

---

# 7. Reusable Platform Upgrade Rules

If the page should become a reusable platform, move from page logic to modular logic.

## 7.1 Separate common from algorithm-specific
Create two layers:

### Shared layer
- page shell
- input section
- parameter section
- chart containers
- result containers

### Algorithm-specific layer
- formulas
- step logic
- algorithm-specific parameters
- algorithm-specific charts

This separation is the main structural upgrade.

## 7.2 Add a mode selector
A reusable platform should usually have at least one of:
- algorithm selector
- compare mode
- task type selector

## 7.3 Add extension points
Design the page so new algorithms can be inserted without redesigning the entire layout.

Useful extension points:
- formula panel slot
- step panel slot
- chart panel slot
- result summary slot

## 7.4 Preserve stable outer architecture
Do not rebuild the whole page every time a new algorithm is added.
Keep the outer learning structure stable.

---

# 8. Interaction Upgrade Rules

Upgrade interaction only when it deepens understanding.

## 8.1 Good interaction upgrades
- expose parameters that visibly affect results
- show changes across iterations
- allow algorithm switching
- allow step navigation
- allow different tasks or datasets

## 8.2 Weak interaction upgrades
Avoid adding:
- controls that do not change outputs
- too many sliders at once
- controls without visible explanation
- hidden interactions the learner cannot understand

## 8.3 Best interaction sequence
When upgrading interaction, do it in this order:
1. algorithm or task switching
2. step-by-step navigation
3. one or two critical parameter sliders
4. advanced parameter block
5. optional expert mode

---

# 9. Visualization Upgrade Rules

Visualization should make the mathematics easier to understand.

## 9.1 Upgrade path for charts
### Basic
- one result chart

### Better
- one process chart + one result chart

### Strong
- one process chart + one comparison chart + one summary chart

## 9.2 Good chart roles
- process chart: shows iteration or transformation
- result chart: shows final output
- comparison chart: shows differences across methods
- sensitivity chart: shows parameter effects

## 9.3 Do not add charts without purpose
A chart should answer at least one of these:
- how is the algorithm changing
- what is the final result
- how do methods differ
- what parameter matters most

---

# 10. Writing and Explanation Upgrade Rules

A platform becomes better not only by adding features, but by improving explanation quality.

## 10.1 Upgrade weak explanation by adding:
- clearer section labels
- shorter conceptual paragraphs
- stronger formula explanation blocks
- more local numerical substitution
- direct interpretation after each important result

## 10.2 Formula writing upgrade
A formula section becomes stronger when it moves from:
- formula only
to:
- formula
- symbol explanation
- why it is used
- numeric substitution
- interpretation

## 10.3 Result writing upgrade
A result section becomes stronger when it includes:
- what changed
- what the final value means
- what conclusion the learner should remember

---

# 11. Architecture Upgrade Rules

Use these rules when evolving code structure.

## 11.1 First stabilize the single-file version
Before moving to a more modular or framework-based version:
- ensure the page logic is correct
- ensure the teaching structure is strong
- ensure interactions are meaningful

## 11.2 Modularize only after the logic is stable
When modularizing:
- separate shared layout logic
- separate algorithm logic
- separate chart rendering logic
- separate data examples if useful

## 11.3 Preserve direct-run usability when possible
For educational demos, browser-runnable single-file html is often a feature, not a limitation.

Do not force framework complexity unless the user explicitly needs it.

---

# 12. Reusability Upgrade Rules

A reusable educational platform should be able to support more algorithms later.

## 12.1 Signs a page is not reusable enough
- algorithm name is hard-coded everywhere
- formulas are mixed into global layout logic
- charts cannot switch datasets or algorithms
- results assume one fixed task type
- parameters are not modular

## 12.2 Upgrade toward reusability by adding
- algorithm selectors
- algorithm configuration objects
- page templates
- family-based structure mapping
- reusable formula cards
- reusable chart containers

## 12.3 Best reusable pattern
A strong pattern is:
- one stable page shell
- one algorithm registry
- one family-aware rendering flow

Even if the implementation remains simple, the structure should think in these terms.

---

# 13. Quality Checkpoints

Before considering a page “upgraded”, check:

## Structure
- Is the page easier to follow than before?

## Explanation
- Are formulas more understandable?

## Computation
- Is the numerical process more visible?

## Interaction
- Do controls change meaningful outputs?

## Visualization
- Do charts reinforce the explanation?

## Comparison
- If multiple algorithms exist, are differences visible?

## Reusability
- Could this structure support another algorithm later?

If the answer is “no” to several of these, the platform still needs structural improvement.

---

# 14. Final Standard

The best version of an algorithm learning platform should feel like:

- a structured course page
- a dynamic calculator
- a visual explainer
- a comparison tool
- a reusable template for future algorithms

It should not feel like:
- a random collection of widgets
- a concept dump
- a code dump
- a one-off page that cannot be extended

Final goal:
- clarity
- mathematical visibility
- dynamic understanding
- reusable architecture
- strong teaching value

path: references/request-routing-rules.md
content: # Request Routing Rules

This file defines how to route user requests into the correct output mode for the algorithm-learning-platform-builder skill.

Its purpose is to help the skill decide:
- what the user is really asking for
- whether the result should be planning-only or full generation
- whether the request is best handled as a single algorithm page, comparison page, or reusable platform
- whether html should be generated immediately or after planning
- how to handle ambiguous, mixed, or overly broad requests

---

# Table of Contents

1. Purpose
2. Core routing principle
3. Step-by-step routing order
4. Request type routing
5. Scope routing
6. Audience routing
7. Output mode routing
8. Ambiguous request routing
9. Upgrade request routing
10. Html generation routing
11. Comparison routing
12. Reusable platform routing
13. Final routing checklist

---

# 1. Purpose

Not every request should be handled the same way.

Some users want:
- a simple explanation
- a structured plan
- a single teaching page
- a comparison page
- a reusable learning platform
- complete runnable html
- an upgrade path for an existing page

This file helps the skill choose the correct response mode before generating output.

---

# 2. Core Routing Principle

Always route in this order:

1. identify what the user wants now
2. identify how broad the algorithm scope is
3. identify whether the user wants explanation, planning, generation, or upgrading
4. identify whether the request should stay focused or become modular
5. choose the smallest correct output that still has strong teaching value

General rule:
- do not overbuild
- do not under-explain
- do not generate full html too early when planning is clearly needed
- do not return planning only when the user explicitly asks for complete runnable code

---

# 3. Step-by-Step Routing Order

When a request arrives, decide in this sequence:

## Step 1
Determine whether the request is mainly:
- explanation
- planning
- generation
- comparison
- upgrade

## Step 2
Determine whether the algorithm scope is:
- one algorithm
- several algorithms
- one family of algorithms
- a general reusable platform

## Step 3
Determine whether the expected output is:
- structured outline
- teaching page content
- complete runnable html
- architecture or upgrade advice

## Step 4
Determine whether the user level suggests:
- beginner-first explanation
- advanced mathematical detail
- mixed teaching + implementation output

Then choose the final route.

---

# 4. Request Type Routing

## 4.1 Planning-only requests

Use planning mode when the user asks for:
- a design plan
- a page structure
- a section arrangement
- what should be included
- how to improve a page
- how to build a platform before code generation

Typical signals:
- “帮我规划”
- “给我一个结构”
- “先设计一下”
- “先不要代码”
- “先给我方案”
- “how should I build this”
- “what should this page include”

### Output mode
Return:
- page goal
- page type
- teaching structure
- formulas to explain
- numerical substitution points
- interactions
- charts
- upgrade path

Do not jump straight to full html unless the user also clearly requests it.

---

## 4.2 Direct generation requests

Use generation mode when the user clearly asks for:
- a complete page
- page content
- full html
- a runnable demo
- directly usable code

Typical signals:
- “直接给我 html”
- “生成完整页面”
- “给我完整代码”
- “做一个可运行 demo”
- “build the page”
- “generate runnable html”

### Output mode
Return:
- structured teaching content first if needed
- then full runnable html if requested

If the scope is complex, planning can still be brief, but do not refuse the full generation request.

---

## 4.3 Explanation-first requests

Use explanation mode when the user mainly wants:
- algorithm understanding
- formula explanation
- derivation explanation
- intuition and computation explanation

Typical signals:
- “讲清楚这个算法”
- “解释公式”
- “推导一下”
- “一步一步讲”

### Output mode
Return:
- concept explanation
- formula explanation
- numerical substitution
- optional page proposal if useful

Do not force html generation unless the user wants a page or demo.

---

## 4.4 Upgrade requests

Use upgrade mode when the user asks:
- how to improve an existing page
- what is missing
- how to make it more reusable
- how to evolve from one page to a platform
- what should be modified in the current design

Typical signals:
- “怎么升级”
- “哪里要改”
- “帮我增强”
- “怎么改成平台”
- “如何泛化”
- “what should I improve”

### Output mode
Return:
- current strengths
- missing pieces
- maturity level
- upgrade priorities
- recommended target structure
- updated version if requested

---

# 5. Scope Routing

## 5.1 Single algorithm route

Use a single algorithm page when:
- the user names one algorithm
- the user wants one method explained deeply
- the algorithm already has enough teaching depth by itself

Examples:
- TOPSIS
- PCA
- KMeans
- gradient descent
- Newton interpolation

### Default output
- one algorithm page
- one set of formulas
- one computation flow
- one focused interaction set

---

## 5.2 Comparison route

Use a comparison page when:
- the user names two or more algorithms
- the user asks for differences
- the user asks which algorithm is better
- the teaching value comes from contrast

Typical signals:
- “比较”
- “区别”
- “优缺点”
- “哪个更好”
- “vs”
- “compare”

### Default output
- shared problem setup
- visible formula differences
- visible workflow differences
- parameter comparison
- chart comparison
- recommendation section

---

## 5.3 Reusable platform route

Use platform mode when:
- the user wants a general platform
- the user wants one structure for many algorithms
- the user wants extension, switching, or modularity

Typical signals:
- “平台”
- “通用”
- “可扩展”
- “支持多个算法”
- “切换算法”
- “algorithm selector”
- “reusable”

### Default output
- stable page shell
- shared input area
- shared parameter area
- switchable algorithm module area
- reusable chart and result area

---

# 6. Audience Routing

## 6.1 Beginner route

Use beginner-first teaching when the user appears to need:
- lower jargon
- clearer intuition
- more visible examples
- more step-by-step substitution

Beginner outputs should:
- explain intuition before formulas
- reduce symbolic density
- show more local numerical substitution
- keep interactions simple and visible

---

## 6.2 Advanced route

Use advanced teaching when the user clearly wants:
- derivations
- detailed formulas
- parameter interpretation
- theory comparison
- stronger mathematical structure

Advanced outputs should:
- include more formula detail
- compare variants where relevant
- explain deeper tradeoffs
- remain structured and readable

---

# 7. Output Mode Routing

Choose among these output modes:

## Mode A — Concept Explanation
Use when the user mainly wants understanding.

## Mode B — Structured Plan
Use when the user mainly wants design, architecture, or preparation.

## Mode C — Teaching Page Content
Use when the user wants a page structure and educational content, but not necessarily full html yet.

## Mode D — Complete Runnable Html
Use when the user explicitly wants directly runnable output.

## Mode E — Upgrade Analysis
Use when the user wants to improve an existing page or platform.

---

# 8. Ambiguous Request Routing

When a request is ambiguous, apply these rules:

## 8.1 If the user asks broadly for a “page” or “platform”
Default to:
- a structured plan first
- then html if explicitly requested

## 8.2 If the user asks for “完整代码” or “直接可运行”
Return runnable html after a brief structural setup.

## 8.3 If the user asks for “讲解 + 页面 + 对比” all at once
Use:
- comparison page plan first
- then structured content
- then html if requested

## 8.4 If the request is too broad to implement cleanly in one step
Prefer:
- reusable platform plan
instead of
- prematurely generating a weak all-in-one page

---

# 9. Upgrade Request Routing

If the user is improving something that already exists, do not treat it as a blank-page request.

Instead:
1. identify the current page type
2. identify current maturity level
3. identify missing teaching value
4. identify best next upgrade
5. propose or generate the upgraded version

Use `platform-upgrade-rules.md` for upgrade prioritization.

---

# 10. Html Generation Routing

Generate html immediately when:
- the user explicitly asks for html
- the user asks for runnable code
- the user asks for a browser demo
- the page scope is already clear

Do not generate html immediately when:
- the request is mostly architectural
- the user explicitly wants planning only
- the request is highly ambiguous and would likely produce poor code without routing first

When html is generated:
- use a single-file page by default
- keep the output runnable in a browser
- preserve teaching structure
- ensure formulas, interactions, and charts are coherent

---

# 11. Comparison Routing

If the request includes multiple algorithms, decide whether the output should be:
- multiple isolated single pages
or
- one true comparison page

Default rule:
If the user is trying to understand differences, choose one comparison page.

Only separate them into isolated pages when:
- the user explicitly asks for separate pages
- each algorithm requires a very deep standalone treatment

---

# 12. Reusable Platform Routing

If the request contains both:
- multiple algorithms
- desire for extension or switching

Then default to reusable platform mode instead of a one-time comparison page.

A reusable platform should:
- keep the shell stable
- allow algorithm switching
- separate common and algorithm-specific logic
- support future expansion

---

# 13. Final Routing Checklist

Before generating output, confirm:

- Is the selected mode correct for the user’s actual request?
- Is the scope correct: single page, comparison page, or platform?
- Is the output level correct: explanation, plan, content, html, or upgrade?
- Is the audience level reflected correctly?
- Is the response too broad or too narrow?
- Would a smaller but stronger output serve the user better?

If several answers are uncertain, prefer:
- planning before code
- comparison before scattered summaries
- reusable platform before hard-coded overgrowth
- educational clarity over feature quantity

path: references/writing-rules.md
content: # Writing Rules

This file defines writing and output standards for the skill.

## Table of Contents
1. General writing rules
2. Teaching rules
3. Html output rules
4. Things to avoid

---

## 1. General Writing Rules

Always write in a way that is:
- structured
- readable
- explanation-first
- suitable for teaching

Use short sections and visible section purposes.
Prefer concrete explanation over abstract compression.

---

## 2. Teaching Rules

Always prefer pages that combine:
- intuition
- formulas
- numerical substitution
- interaction
- charts
- summary

Do not stop at concept explanation when the user's request clearly asks for a learning page or dynamic demo.

When writing formula explanations:
- explain symbols
- explain why the formula is used
- show a concrete substitution when possible

When the user is a beginner:
- simplify wording
- add more examples
- keep the visual structure obvious

---

## 3. Html Output Rules

When generating html:
- prefer a single-file html page
- keep it directly runnable in a browser
- include complete html structure
- include script and style blocks when needed
- keep mathjax and chart.js configuration consistent
- keep the code internally consistent
- do not leave placeholders like TODO in final output unless the user asked for a scaffold

Prefer a polished teaching layout over a raw utility layout.

---

## 4. Things to Avoid

Avoid:
- static concept dumps without visible structure
- formula-only pages without narrative
- code-only outputs without explanation when the task is educational
- disconnected charts that are not explained
- interactions that do not change anything meaningful
- incomplete html output

path: assets/html-starter-template.html
content: <!DOCTYPE html>
<html lang="zh-CN">
<head>
  <meta charset="UTF-8" />
  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
  <title>Algorithm Learning Page</title>

  <script src="https://cdn.jsdelivr.net/npm/chart.js"></script>
  <script>
    window.MathJax = {
      tex: {
        inlineMath: [['$', '$'], ['\\(', '\\)']],
        displayMath: [['$$', '$$']]
      },
      svg: { fontCache: 'global' },
      startup: { typeset: false }
    };
  </script>
  <script src="https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-svg.js"></script>

  <style>
    :root{
      --bg:#faf8f3;
      --card:#fffdf9;
      --gold:#c6a66b;
      --gold-deep:#a98345;
      --text:#2d2a25;
      --muted:#736a60;
      --line:#e8dfcf;
      --shadow:0 14px 40px rgba(112,92,63,.08);
      --radius:24px;
      --max:1320px;
    }
    *{box-sizing:border-box}
    body{
      margin:0;
      font-family:"PingFang SC","Microsoft YaHei","Noto Sans SC",Arial,sans-serif;
      background:linear-gradient(180deg,#fcfbf8 0%, #f8f4eb 100%);
      color:var(--text);
      line-height:1.7;
    }
    .container{width:min(var(--max), calc(100% - 40px));margin:0 auto}
    .section{padding:84px 0}
    .card{
      background:rgba(255,255,255,.92);
      border:1px solid var(--line);
      border-radius:var(--radius);
      box-shadow:var(--shadow);
      padding:24px;
    }
    .grid-2{display:grid;grid-template-columns:1fr 1fr;gap:22px}
    .section-title{font-size:38px;line-height:1.2;margin:0}
    .section-kicker{font-size:13px;letter-spacing:3px;color:var(--gold-deep);text-transform:uppercase;margin-bottom:10px}
    .section-desc{margin:12px 0 0;color:var(--muted);max-width:900px}
    .equation-block{
      margin-top:16px;padding:16px 18px;border-radius:18px;
      background:rgba(249,245,237,.92);border:1px solid var(--line);overflow:auto;
    }
    .table-wrap{overflow:auto;margin-top:14px}
    table{
      width:100%;min-width:720px;border-collapse:collapse;
      background:#fff;border-radius:16px;overflow:hidden;font-size:14px;
    }
    th,td{border:1px solid #eadfcb;padding:10px 12px;text-align:center;vertical-align:middle}
    th{background:#fbf7ee;color:#4f473d;font-weight:700}
    .chart-box{
      background:rgba(255,255,255,.9);border:1px solid var(--line);border-radius:24px;
      box-shadow:var(--shadow);padding:18px;min-height:360px;
    }
    .chart-box canvas{width:100% !important;height:300px !important}
    @media (max-width:900px){
      .grid-2{grid-template-columns:1fr}
      .container{width:min(var(--max), calc(100% - 24px))}
    }
  </style>
</head>
<body>
  <main>
    <section class="section">
      <div class="container">
        <div class="section-kicker">Algorithm Demo</div>
        <h1 class="section-title">Algorithm Learning Page</h1>
        <p class="section-desc">Replace this scaffold with algorithm-specific teaching content.</p>
      </div>
    </section>

    <section class="section">
      <div class="container grid-2">
        <div class="card">
          <h3>Formula Block</h3>
          <div class="equation-block">
            $$y = ax + b$$
          </div>
        </div>
        <div class="card">
          <h3>Chart Block</h3>
          <div class="chart-box">
            <canvas id="demoChart"></canvas>
          </div>
        </div>
      </div>
    </section>
  </main>

  <script>
    const ctx = document.getElementById('demoChart').getContext('2d');
    new Chart(ctx, {
      type: 'bar',
      data: {
        labels: ['A', 'B', 'C'],
        datasets: [{
          label: 'Demo',
          data: [1, 2, 3]
        }]
      },
      options: {
        responsive: true,
        maintainAspectRatio: false
      }
    });

    if(window.MathJax && window.MathJax.typesetPromise){
      window.MathJax.typesetPromise();
    }
  </script>
</body>
</html>

path: agents/openai.yaml
content: interface:
  display_name: Algorithm Learning Platform Builder
  short_description: Build interactive algorithm teaching pages and reusable learning platforms
  icon: function
  color: "#A98345"

Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: suspicious (MEDIUM)