scaffold-exercises

Name: scaffold-exercises
Author: stevesolun

560stars68forks

How to install scaffold-exercises?

stevesolun/ctx/scaffold-exercises

$npx -y skills add stevesolun/ctx --skill scaffold-exercises

Installs into the current project.

Summary

Create exercise directory structures with sections, problems, solutions, and explainers that pass linting. Use when user wants to scaffold exercises, create exercise stubs, or set up a new course section.

Files · 1

View on GitHub

SKILL.md

1	# Scaffold Exercises
2
3	Create exercise directory structures that pass `pnpm ai-hero-cli internal lint`, then commit with `git commit`.
4
5	## Directory naming
6
7	- Sections: `XX-section-name/` inside `exercises/` (e.g., `01-retrieval-skill-building`)
8	- Exercises: `XX.YY-exercise-name/` inside a section (e.g., `01.03-retrieval-with-bm25`)
9	- Section number = `XX`, exercise number = `XX.YY`
10	- Names are dash-case (lowercase, hyphens)
11
12	## Exercise variants
13
14	Each exercise needs at least one of these subfolders:
15
16	- `problem/` - student workspace with TODOs
17	- `solution/` - reference implementation
18	- `explainer/` - conceptual material, no TODOs
19
20	When stubbing, default to `explainer/` unless the plan specifies otherwise.
21
22	## Required files
23
24	Each subfolder (`problem/`, `solution/`, `explainer/`) needs a `readme.md` that:
25
26	- Is not empty (must have real content, even a single title line works)
27	- Has no broken links
28
29	When stubbing, create a minimal readme with a title and a description:
30
31	```md
32	# Exercise Title
33
34	Description here
35	```
36
37	If the subfolder has code, it also needs a `main.ts` (>1 line). But for stubs, a readme-only exercise is fine.
38
39	## Workflow
40
41	1. Parse the plan - extract section names, exercise names, and variant types
42	2. Create directories - `mkdir -p` for each path
43	3. Create stub readmes - one `readme.md` per variant folder with a title
44	4. Run lint - `pnpm ai-hero-cli internal lint` to validate
45	5. Fix any errors - iterate until lint passes
46
47	## Lint rules summary
48
49	The linter (`pnpm ai-hero-cli internal lint`) checks:
50
51	- Each exercise has subfolders (`problem/`, `solution/`, `explainer/`)
52	- At least one of `problem/`, `explainer/`, or `explainer.1/` exists
53	- `readme.md` exists and is non-empty in the primary subfolder
54	- No `.gitkeep` files
55	- No `speaker-notes.md` files
56	- No broken links in readmes
57	- No `pnpm run exercise` commands in readmes
58	- `main.ts` required per subfolder unless it's readme-only
59
60	## Moving/renaming exercises
61
62	When renumbering or moving exercises:
63
64	1. Use `git mv` (not `mv`) to rename directories - preserves git history
65	2. Update the numeric prefix to maintain order
66	3. Re-run lint after moves
67
68	Example:
69
70	```bash
71	git mv exercises/01-retrieval/01.03-embeddings exercises/01-retrieval/01.04-embeddings
72	```
73
74	## Example: stubbing from a plan
75
76	Given a plan like:
77
78	```
79	Section 05: Memory Skill Building
80	- 05.01 Introduction to Memory
81	- 05.02 Short-term Memory (explainer + problem + solution)
82	- 05.03 Long-term Memory
83	```
84
85	Create:
86
87	```bash
88	mkdir -p exercises/05-memory-skill-building/05.01-introduction-to-memory/explainer
89	mkdir -p exercises/05-memory-skill-building/05.02-short-term-memory/{explainer,problem,solution}
90	mkdir -p exercises/05-memory-skill-building/05.03-long-term-memory/explainer
91	```
92
93	Then create readme stubs:
94
95	```
96	exercises/05-memory-skill-building/05.01-introduction-to-memory/explainer/readme.md -> "# Introduction to Memory"
97	exercises/05-memory-skill-building/05.02-short-term-memory/explainer/readme.md -> "# Short-term Memory"
98	exercises/05-memory-skill-building/05.02-short-term-memory/problem/readme.md -> "# Short-term Memory"
99	exercises/05-memory-skill-building/05.02-short-term-memory/solution/readme.md -> "# Short-term Memory"
100	exercises/05-memory-skill-building/05.03-long-term-memory/explainer/readme.md -> "# Long-term Memory"
101	```

People who liked this also viewed

6 picks

Type

scaffold-exercises

560stars68forks

View on GitHub

How to install scaffold-exercises?

stevesolun/ctx/scaffold-exercises

$npx -y skills add stevesolun/ctx --skill scaffold-exercises

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# Scaffold Exercises
2
3	Create exercise directory structures that pass `pnpm ai-hero-cli internal lint`, then commit with `git commit`.
4
5	## Directory naming
6
7	- Sections: `XX-section-name/` inside `exercises/` (e.g., `01-retrieval-skill-building`)
8	- Exercises: `XX.YY-exercise-name/` inside a section (e.g., `01.03-retrieval-with-bm25`)
9	- Section number = `XX`, exercise number = `XX.YY`
10	- Names are dash-case (lowercase, hyphens)
11
12	## Exercise variants
13
14	Each exercise needs at least one of these subfolders:
15
16	- `problem/` - student workspace with TODOs
17	- `solution/` - reference implementation
18	- `explainer/` - conceptual material, no TODOs
19
20	When stubbing, default to `explainer/` unless the plan specifies otherwise.
21
22	## Required files
23
24	Each subfolder (`problem/`, `solution/`, `explainer/`) needs a `readme.md` that:
25
26	- Is not empty (must have real content, even a single title line works)
27	- Has no broken links
28
29	When stubbing, create a minimal readme with a title and a description:
30
31	```md
32	# Exercise Title
33
34	Description here
35	```
36
37	If the subfolder has code, it also needs a `main.ts` (>1 line). But for stubs, a readme-only exercise is fine.
38
39	## Workflow
40
41	1. Parse the plan - extract section names, exercise names, and variant types
42	2. Create directories - `mkdir -p` for each path
43	3. Create stub readmes - one `readme.md` per variant folder with a title
44	4. Run lint - `pnpm ai-hero-cli internal lint` to validate
45	5. Fix any errors - iterate until lint passes
46
47	## Lint rules summary
48
49	The linter (`pnpm ai-hero-cli internal lint`) checks:
50
51	- Each exercise has subfolders (`problem/`, `solution/`, `explainer/`)
52	- At least one of `problem/`, `explainer/`, or `explainer.1/` exists
53	- `readme.md` exists and is non-empty in the primary subfolder
54	- No `.gitkeep` files
55	- No `speaker-notes.md` files
56	- No broken links in readmes
57	- No `pnpm run exercise` commands in readmes
58	- `main.ts` required per subfolder unless it's readme-only
59
60	## Moving/renaming exercises
61
62	When renumbering or moving exercises:
63
64	1. Use `git mv` (not `mv`) to rename directories - preserves git history
65	2. Update the numeric prefix to maintain order
66	3. Re-run lint after moves
67
68	Example:
69
70	```bash
71	git mv exercises/01-retrieval/01.03-embeddings exercises/01-retrieval/01.04-embeddings
72	```
73
74	## Example: stubbing from a plan
75
76	Given a plan like:
77
78	```
79	Section 05: Memory Skill Building
80	- 05.01 Introduction to Memory
81	- 05.02 Short-term Memory (explainer + problem + solution)
82	- 05.03 Long-term Memory
83	```
84
85	Create:
86
87	```bash
88	mkdir -p exercises/05-memory-skill-building/05.01-introduction-to-memory/explainer
89	mkdir -p exercises/05-memory-skill-building/05.02-short-term-memory/{explainer,problem,solution}
90	mkdir -p exercises/05-memory-skill-building/05.03-long-term-memory/explainer
91	```
92
93	Then create readme stubs:
94
95	```
96	exercises/05-memory-skill-building/05.01-introduction-to-memory/explainer/readme.md -> "# Introduction to Memory"
97	exercises/05-memory-skill-building/05.02-short-term-memory/explainer/readme.md -> "# Short-term Memory"
98	exercises/05-memory-skill-building/05.02-short-term-memory/problem/readme.md -> "# Short-term Memory"
99	exercises/05-memory-skill-building/05.02-short-term-memory/solution/readme.md -> "# Short-term Memory"
100	exercises/05-memory-skill-building/05.03-long-term-memory/explainer/readme.md -> "# Long-term Memory"
101	```

People who liked this also viewed

6 picks

Type