| name | academic-notes |
| description | Content conventions, examples, and tooling for course notes under special/academia. |
Academic notes — consolidated skill
This skill is the authoritative long-form guide for creating and maintaining
course notes under special/academia/<INSTITUTION>. The matching instruction
file is a quick-reference checklist for agents; this file owns the detailed
policy. The course template owns only scaffold-facing reminders.
Flashcards are generated automatically by the build system; do not run
init generate manually.
Skill folder map
SKILL.md — authoritative workflow and policy reference.
course-template.md — scaffold for new course index.md pages.
check.py — validator entry point. The validator is always at
.agents/skills/academic-notes/check.py; do not recurse through the
repository to find it.
check_mods/* — validator rules and implementation modules.
find_wikipedia.py — helper for discovering canonical general/ article
titles when a course note wants to link outward.
tests_a7392be/* — validator and helper tests for this skill folder.
Source-of-truth split
SKILL.md owns detailed writing, restructuring, validator, and note-family
policy.
.agents/instructions/academic-notes.instructions.md is the short,
agent-facing checklist for quick triage.
course-template.md owns the minimal scaffold and fill-in reminders for new
course indexes.
- Durable lessons belong in these files and, when needed, in validator tests —
not in persistent memory.
Key principles
- Content first. Capture the lecture's actual ideas, formulas,
distinctions, examples, and instructor caveats before polishing structure.
- One durable home per concept. Prefer enhancing an existing topic note and
updating links before creating overlapping pages.
- Prose, flashcards, and navigation move together. When you add, split,
merge, or rename content in a topic note, update the note's flashcards and
every affected
index.md section link in the same task.
- Flashcards are standalone artifacts. Restate local hypotheses, notation,
givens, and conditions needed to answer the card correctly.
- Keep the lecture's mathematical spine. For technical notes, the default
bundle is formula + derivation or proof sketch + intuition + worked
example.
- Preserve teaching detail, not just headlines. Named classifications,
operational distinctions, and memorable examples should survive ingestion.
- Respect metadata and chronology. Keep YAML frontmatter valid, keep
sessions in chronological order, and place exams after regular sessions.
- Keep math validator-friendly. Use
$...$ or $$...$$, keep math on one
source line, and avoid putting LaTeX inside emphasis. Accounting notes should
avoid LaTeX entirely.
- Keep headers and emphasis consistent. Topic-note headers in Latin scripts (English, etc.) should normally be lowercase except for proper nouns. Non-Latin scripts (CJK, Cyrillic, Arabic, etc.) are exempt since they lack uppercase/lowercase distinction. Prefer
_italic_ and __bold__.
- Validate narrowly and immediately. Run the fixed validator path on the
smallest relevant course or file after edits; never aim it at the whole
repo or the entire skill folder.
- Skill files are the durable memory. If a lesson recurs, update this
skill, the template, the instruction file, and tests when appropriate.
- Course-local agent guidance lives in
AGENTS.md. Keep it concise,
course-specific, titled exactly # <course code> agent instructions, and
free of flashcard markup.
- Do not migrate validation metadata into
AGENTS.md. Suppression
comments belong in the content file that needs them.
- Do not create or edit
general/ files automatically. Use the Wikipedia
helper only to discover canonical titles for links; course content still
lives under special/academia/<INSTITUTION>/<COURSE>/.
- Do not put instructor or TA names or email addresses in course notes.
Refer readers to the official syllabus or LMS for contact information.
Authoring workflow
Use this workflow whenever you add or revise course content.
- Start from
course-template.md when creating a new course index.md.
- If agent-specific guidance is needed, add or update
<course folder>/AGENTS.md
with the exact title # <course code> agent instructions.
- Fill frontmatter carefully: aliases, tags, course name, credits, and
description.
- Normalize flashcard activation tags with underscore-separated path fragments,
for example
flashcard/active/special/academia/HKUST/COMP_3031 or
flashcard/active/special/academia/Pusan_National_University/IT3000504.
- Add
logistics with grading and chosen-section metadata.
- Maintain
children: in teaching order and include [AGENTS](AGENTS.md) only
when the file actually exists.
- For course-root
index.md pages, order major top-level sections as
## children, then ## logistics, then ## overview; keep later sections
in functional or chronological order after that.
- Prefer one merged
## overview section in the course root for official scope
bullets, topic-to-file mapping, and other high-value orientation material.
- Write explanatory prose first; add or revise flashcards after the prose is
accurate.
- Update related
index.md anchors and session links in the same pass.
- Run the validator and fix both warnings and errors before moving on.
- Before finishing, review the note once as a reader and once as a flashcard
consumer.
When building scaffolds, keep index.md pages lean. Avoid duplicating long
calendars or schedule prose across course roots, folder indexes, and leaf pages
when a child page can own the details more cleanly. Use a flat leaf file such as
tutorial 1.md when no subpages or local attachments are expected; use a folder
with index.md only when the item is likely to accumulate children of its own.
Course metadata and index structure
Frontmatter and tags
- Keep YAML frontmatter valid and stable.
- Require a flashcard activation tag on academic-note files when flashcards are
desired. Tag segments should be underscore-normalized rather than space-based,
for example
Korea_University/ISC213/questions/quiz_1.
- Course indexes typically also carry
function/index and
language/in/<language>.
- For topic notes, prefer aliases that are genuine synonyms of the concept, not
specific instances of the concept.
Course-root layout
- After the course list (
institution, name, credits), insert --- before
the course description.
- Put
## children first, then ## logistics, then ## overview.
- Place
assignments/ immediately after children and before session entries
when the course has an assignments section.
- Under
sections:, use one key for the chosen stream, then list all stream IDs
and their logistics under that key.
- Weekly session metadata must match the chosen lecture/tutorial/lab stream.
- Use session headings exactly like
## week N lecture, ## week N lecture 2,
## week N tutorial, and ## week N lab.
- If the official schedule exposes a recurring lecture, tutorial, or lab
stream, keep that stream's week headings continuous across the teaching term
even when a given week has no meeting. Mark the gap with
status: metadata
rather than silently skipping the week.
- If a session has no class, omit
topic:. Use status: public holiday: <name>
when known, otherwise status: no class.
- Keep session-level flashcards in the index only when they test a reusable
pattern or concept. Do not use them merely to summarize scope.
- Administrative exam information may be ordinary prose; do not force it into
flashcards or bullets unless the user wants that style.
AGENTS.md in course folders
- Keep course-local agent instructions in
AGENTS.md, not in hidden comments in
index.md.
- The first content heading must be exactly
# <course code> agent instructions.
- Do not put flashcard markup in
AGENTS.md.
Adding new lecture content
Before creating a new topic note, classify the incoming material:
- Duplicate → do not create a new note; add section links to the existing
content.
- Enhancement → deepen the existing note and update its flashcards and
session links.
- New → create a new durable topic note only when no good home exists yet.
Also follow these rules:
- If tutorial sheets, examples, or auxiliary handouts mainly deepen an existing
concept, merge that material into the relevant topic note before inventing a
detached catch-all section.
- Do not flatten dense lecture material into a few broad summaries. Preserve the
explicit distinctions, classifications, formulas, examples, counterexamples,
and teaching caveats that make the lecture memorable.
- Do not use chapter numbers as durable navigation, routing, or flashcard cues.
Source decks,
.tmp extracts, and temporary teaching materials may later
disappear, so durable notes must refer to topic names, canonical note files,
and in-repo section links instead. For the same reason, durable note prose
should not narrate its source context with wording such as "in this
lecture", "the tutorial sheet shows", "the lab manual asks", or other
references to temporary delivery artifacts unless the artifact itself is the
subject of the note.
- When tutorials, exams, or office-hours questions reveal a tricky question,
edge case, or "what if" variant, absorb it into the canonical topic note
under a descriptive subheading instead of leaving it in a detached collector
or as a chapter-based memory cue.
- Keep companion notes at similar rigor when the mathematics genuinely mirrors,
especially for continuous-time versus discrete-time analogues.
- If a general topic note starts accumulating a coherent subcluster — for
example discrete-time representation methods, canonical sequence families, and
periodicity rules — give that cluster one canonical home rather than leaving
overlapping fragments in several files.
- Refresh matching
topic: lines and short lecture-summary prose in
index.md whenever a topic note grows materially deeper, even if its section
anchors stay unchanged.
- If required theory lives only in an appendix or auxiliary PDF, absorb the
content into topic notes and let the index point there. Attachments may remain
as optional archival references, not the sole durable home.
- Lab-preparation decks and lab manuals should be treated as normal lecture
ingestion: centralize definitions, circuit behavior, and worked examples in
topic notes, then route lab or tutorial pages to those sections with
§
links and a small number of workflow or safety flashcards.
Technical and mathematical notes
For mathematically substantive notes, the prose and flashcards should usually
include the governing formula, the derivation or proof sketch, the intuition for
the key step, and a worked example.
Key expectations:
- Explicitly compare related concepts students often confuse, such as message
versus signal, discrete-time versus digital, energy versus power, or vertical
versus horizontal transformations.
- When a note introduces an additive decomposition (DC/AC, even/odd,
real/imaginary, and similar splits), include the decomposition formula, the
derivation showing why the cross term vanishes, the orthogonality or zero-
covariance interpretation, and at least one worked example.
- For finite windows or rectangular sequences, state endpoint conventions
explicitly rather than leaving the reader to infer them from a step-function
expression.
- In discrete-time oscillation notes, state the rational-versus-irrational
periodicity test explicitly and include at least one example where the written
digital angular frequency is not the sequence's fundamental digital frequency
because digital frequency is defined modulo $2\pi$.
- When continuous-time and discrete-time examples are taught as counterparts,
make the parallel explicit: what the impulse does initially, why the later
dynamics become homogeneous, and how geometric versus exponential evolution
line up.
- In ODE-based response notes, map the competing labels directly: homogeneous,
particular, zero-input, zero-state, natural, forced, transient, and steady-
state. Also state the caveat that zero-state response may require a homogeneous
correction in addition to a particular solution.
- For transform and Fourier notes, keep the exact applied rule visible when a
factor or sign matters. Do not write only “by duality” or “apply the
convolution theorem” if the normalization could be forgotten.
- Preserve the practical Fourier-problem workflow the lecture uses: try
linearity, differentiation or integration properties, and partial fractions
before resorting to direct integration.
- In Fourier-series notes, treat the DC term explicitly rather than as “just
another coefficient.” Explain why zero frequency has no positive/negative
partner.
- When converting between cosine-sine and amplitude-phase form, include both the
amplitude and phase formulas and a short geometric interpretation.
- Compare real trigonometric and complex exponential orthogonal-function sets
explicitly when both appear in the lecture. If the lecture reaches that level,
include a short Hilbert-space or Riesz-style interpretation with clear
explanation rather than name-dropping.
- For real signals, note when a one-sided spectrum is valid and why the nonzero
lines double while the DC line does not.
- In Parseval discussions, say explicitly that the exponential form is the most
natural two-sided power sum, and explain the $1/2$ factor in real folded
forms.
- For singular or generalized functions, describe how the graph is drawn, which
parts are symbolic, and how ordinary pulse families approach the generalized
object in the limit.
- For singular-signal notes, include formulas in common equivalent forms and
state relations among nearby signal families such as step, ramp, gate, signum,
impulse, and doublet.
- For doublet and impulse-derivative sampling rules, explain the sign intuition
and contrast direct sampling with convolution.
- When a lecture uses differentiation or integration properties of convolution,
include the higher-order operator view and at least one example where a
differentiated kernel collapses into shifted impulses.
- For time-delay identities, give the formula, the graphical sliding-overlap
intuition, the physical interpretation of delay, and the operator view
$f(t-t_0)=f*\delta(t-t_0)$.
- For discrete-time convolution, connect the sum to continuous-time convolution
of impulse trains and spell out the remaining differences: Kronecker versus
Dirac delta, sum versus integral, stem plots versus impulse arrows, and any
sample-period caveat.
- When presenting delta-sequence families, show the normalization or unit-area
check explicitly.
- Explain test functions as smooth localized probes and say why smoothness and
compact support are useful.
- Verify theorem hypotheses instead of copying a slide or appendix statement
blindly. Prefer the standard theorem statement unless a stronger form is
clearly intended and explained.
- For analysis-style appendix material, add geometric or probabilistic
interpretation as well as formulas: box approximations, slicing intuition,
indicator-function viewpoints, or event-region interpretations.
- When a computation appears in the prose, do not jump from setup to final
answer; show the main intermediate step or strategy in both prose and
flashcards.
Honors and proof-heavy courses
Honors courses deserve more rigor, not merely more words.
- State hypotheses explicitly.
- Prefer short derivation or proof sketches to bare theorem statements.
- Break long arguments into a few logically separate paragraphs instead of one
dense wall of text.
- Keep concrete examples and counterexamples in both prose and flashcards.
- When a theorem has a tempting but false overstatement, repair it in the note
rather than copying the broken version from the source.
- When a concept has several equivalent formulations, list them explicitly and
explain what each one means rather than leaving them as opaque labels.
- For measure-theoretic or probability-heavy notes, keep notation reader-facing:
define the value space, sigma-algebra membership, pushforward notation,
preimage notation, and any hybrid distribution notation before using it in a
proof.
- When a proof naturally has a concrete layer and an abstract layer, teach both:
for example, a direct event-based argument first and then the abstract
pushforward or generator-based argument.
- For random-variable, distribution-function, and measure-equality notes,
explain the criterion being used and why it is enough, rather than citing a
theorem name without the proof idea.
- For auxiliary set systems such as pi-systems and Dynkin systems, compare them
explicitly with sigma-algebras and make the disjointification trick readable.
- When the lecture uses a theorem operationally, also add “how to use it”
guidance in prose and flashcards.
Machine-learning notes
Machine-learning notes should preserve derivations, notation discipline, and the
distinction between modeling, optimization, and decision.
Use these defaults:
- Prefer formula + derivation + intuition + caveat + worked example over a
formula-only summary.
- Make assumptions explicit: IID status, priors, thresholds, intercept
conventions, row/column roles, and whether a quantity is a loss, metric, or
decision rule.
- Separate estimation from decision. For example, distinguish cross-entropy or
likelihood fitting from Bayes-threshold classification.
- Keep true/source distribution $P$ and model/scoring distribution $Q$ distinct
in entropy, cross-entropy, and Kullback-Leibler notes. Write the full formula
triad when relevant.
- When conditional cross entropy or hybrid-joint notation appears, define the
notation before invoking decomposition identities.
- Explain why empirical training loss carries a $1/N$ factor: it is an empirical
expectation, not a decorative constant.
- In logistic-regression notes, explain odds, logit, coefficient interpretation
on the odds scale, and any course-specific threshold convention together with
common tie variants.
- In softmax-regression notes, prefer the general target-distribution form before
the one-hot special case; include the categorical cross-entropy derivation,
the binary $C=2$ reduction, the shared gradient memory rule
prediction minus target, and numerical-stability advice such as logsumexp or max-shift.
- If a course has both
classification.md and logistic regression.md, prefer
putting performance metrics in classification.md, including binary and
multiclass macro, micro, and weighted formulas.
- When a lecture compares surrogate loss with classification error, include a
concrete example where the two move differently.
- For convexity, bias-variance, or generalization notes, keep the target of each
formula explicit and distinguish sample-specific from expected quantities.
- For optimization notes, include a practical by-hand update workflow and at
least one tiny numerical example when appropriate.
- Distinguish per-sample SGD, minibatch SGD, and full-batch gradient descent
explicitly.
- For deep networks, pair the repeated forward layer equation with a composition
interpretation, and pair that with a backward local-error or transposed-
Jacobian view.
- Define “signal” in initialization discussions in terms of activation or
gradient scale, and explain fan-in/fan-out and variance flow.
- When discussing vanishing gradients, include at least a short chain-rule or
norm-product derivation instead of leaving it as a slogan.
- Activation-function sections should compare nearby activations on both
theoretical and empirical axes: boundedness, smoothness, saturation,
monotonicity, zero-centering, dead units, optimization behavior, and compute
cost.
- For backpropagation, define the local error explicitly and show how the same
quantity yields both the incoming weight gradient and the propagated upstream
error.
- For dropout, state clearly that activations are masked, not weights. Explain
both non-inverted and inverted dropout conventions carefully and say which
objects get rescaled and when.
- Distinguish L2 regularization from weight decay explicitly. L2 is an
objective-level penalty; weight decay is an update-level shrinkage. State when
they are equivalent under plain SGD and when they are not, especially for
adaptive optimizers such as Adam. Mention AdamW when relevant.
Physics, electronics, and lab notes
- When introducing notation or jargon such as $V_{CC}$, $V_{CE}$, or “low-side
switch,” add a brief definition near first use so the note is readable without
hidden course context.
- Circuit and electronics calculation cards should state topology, polarity,
loop direction, and node naming if a diagram is not shown.
- Put image markup on the same source line as the end of the preceding
paragraph.
- Add diagram-recall flashcards for key symbols or circuits when the diagram is
itself a learning target.
- For signal-processing block-diagram questions, write the explanation as a
stage-by-stage chain: identify the operation (for example carrier
multiplication or filtering), name the resulting shifted or removed bands
using the actual frequency landmarks from the figure when available, then
state which component the LTI block preserves or rejects.
- If the course keeps diagram-generation scripts, keep docstrings descriptive
enough for future maintainers to reconstruct topology and style.
- For common schemdraw-style circuit scripts, build the main rail first, save
branch points explicitly, and use
.reverse() on diode-like components when
polarity requires it.
- IC power pins such as VCC and GND should be described generically unless the
course fixes a specific supply value.
Topic-specific notes
Create a topic note when a concept deserves a durable, reusable home. Topic
notes should read like compact encyclopedia entries: explanatory prose first,
then flashcards immediately after each section.
Structure and naming
- Use QA cards by default in topic notes. Exception: accounting journal-entry
worked examples embedded in topical notes may use cloze inside quoted
scenarios, tables, calculations, and short explanations.
- Prefer concise, concept-based headings rather than mechanically copying slide
titles.
- Use subsections only when they improve structure; if a subsection is tiny,
consider merging it.
- Prefer lowercase filenames except for genuine proper nouns.
- Prefer the singular canonical concept name unless the concept is inherently
plural by standard usage.
- Keep topic-note aliases to the canonical term and real synonyms; do not treat
specific instances as aliases of the general concept.
- When linking to
general/, use the canonical article title but do not create
or edit the general/ file as part of course-note work.
- In course topic notes, omit redundant filename, title, or delivery-context
text from both prose and flashcard prompts. Do not use source files, slide
decks, tutorial sheets, lab handouts, or temporary course artifacts as prose
scaffolding unless the artifact itself is the subject. Use local prompts such
as
definition or Bayes theorem finite, not probability measure / definition unless nested context requires it.
Section-local flashcards
- Every section in a topic note should have its own
--- and flashcard block.
- If a topic note has an overview section followed by representative example
subsections, keep the detailed flashcards with the matching subsection rather
than concentrating most of the cards at the end.
- When the prose only needs a small clarification or comparison, enhance the
existing flashcards instead of spawning near-duplicates.
- When the prose gains a substantial cluster of distinctions, examples, or
counterexamples, add new flashcards instead of overstuffing one old card.
- Do not insert explanatory prose between a section's horizontal rule (
---)
and Flashcards for this section are as follows:. Place any new prose above
the --- separator, or convert the clarification into flashcards, so the
flashcard heading always remains directly under the separator.
Journal entry examples in accounting topic notes
Accounting courses should place each journal-entry example in the most specific
topical note rather than defaulting to a course-wide journal entries.md
collector.
- Keep the explanatory concept prose and the worked journal-entry examples in
the same topical section whenever practical.
- A worked example should usually live in a single blockquote: scenario,
journal-entry table, then optional explanation or calculation.
- If one concept naturally needs several related entries (for example warranty
provision plus settlement, or bond issue between coupon dates plus first
coupon-date adjustment), keep that cluster together in the same topical
section.
- Keep every journal-entry scenario, Dr/Cr table, and short calculation
explanation above that section's local flashcard block. Once
Flashcards for this section are as follows: begins, the remainder of the section should be
flashcards only until the next header.
- Use markdown tables with right-aligned Dr/Cr columns.
- Wrap the first-column header description and each account name in clozes.
- Mask all debit and credit amounts in the worked example with clozes and use
as the thousands separator.
- Keep punctuation outside the closing cloze token:
{@{text}@}.
- Warranty examples should allow settlement credits such as Cash, Inventory, or
Accrued Payroll when appropriate.
- Service-type warranty examples should reflect revenue recognized over the
service period rather than at the assurance-warranty stage.
- When distributing entries into topic notes, also update the relevant
index.md links so readers are routed directly to the topical home.
Questions pages
Question pages are not topic notes. They usually do not need the “Flashcards for
this section are as follows:” rubric.
Use these rules:
- For repository-authored review prompts, prefer ordinary headings and lists.
- For official course materials, use markdown blockquotes.
- If a page mixes official material with self-authored review prompts, keep the
official content quoted and the self-authored content unquoted.
- If the file becomes too large, split it into
questions/index.md plus smaller
child pages such as tutorial weeks, problem sets, review sets, or exam blocks.
- Keep naturally distinct official families distinct: tutorials, problem sets,
practice exams, solution sheets, and so on.
- In official quoted questions, do not add manual numbering to the question
line. If a question has subparts, use a quoted list inside the same blockquote.
- Use
Solution: instead of Solution sketch: and include concise but complete
solution logic.
- When the question has subparts, mirror that structure in the quoted solution.
- Keep cloze coverage meaningful in official quoted solutions: cover method,
condition, and final result, not only equations.
- Do not hide only a variable name or re-hide a formula already visible in the
prompt when a more explanatory cloze is available.
- When cleaning up low-value clozes, re-audit each quoted solution block so it
still contains meaningful coverage.
- Prefer clozing a reasoning step together with its equation when they form a
single proof step.
- Keep each quoted
Solution: as one source paragraph line; avoid manual soft
wrapping for that style.
- For consecutive quote blocks, prefer local MD028 control comments instead of a
global suppression.
Canvas quiz conversions
When a Canvas quiz is converted into notes, use a paired public/private layout
rather than trying to make one page serve both goals.
- Put the public pedagogical page at
special/academia/<INSTITUTION>/<COURSE>/questions/quiz N.md with an active
flashcard tag and a ## hints section.
- Put the private archival page at the mirrored private path with an archive
flashcard tag and a
## content section.
- Do not keep a parallel
assignments/online quiz N/index.md stub once the
quiz has a home in questions/. Even if the LMS exposes the quiz through an
assignments-style route, the repository should keep quiz families together
under questions/.
- Preserve the common quiz metadata in both pages when it is visible in the
source: due datetime, points, number of questions, availability window, time
limit, and allowed attempts.
- Public quiz pages should transform the official quiz into review material:
recognition rules, conceptual hints, compact worked reminders, and active
recall prompts. Keep the public
## hints in the same order as the
archived/private question order even if individual hints are later rewritten
to be more conceptual. Do not copy the full official question set
verbatim into the public page when a private archival page exists.
- If only quiz timing or schedule metadata is known and the question content has
not been archived yet, keep a minimal placeholder page in
questions/quiz N.md rather than opening a separate assignments stub. Make the placeholder
explicit about the missing archived content.
- Private quiz pages should preserve the official prompt text as faithfully as
practical, usually in blockquotes, together with the archived answer state.
Do not add a stock boilerplate paragraph at the start of
## content; begin
directly with the questions unless the page needs a genuinely specific caveat
about missing source context.
- If the archived source explicitly shows correctness, grading feedback, or an
official solution, label the answer line as
- solution:.
- If the archived source only shows a checked option or stored attempt state,
do not overclaim correctness. Use labels such as
- archived selection:
or - selected answer: instead of asserting a solution.
- If the user later confirms that the archived checked options are indeed
correct, you may promote those answer lines to
- solution: even if the raw
screenshot itself only showed a checked state.
- When a private quiz page records confirmed solutions, add a short explanation
bullet for each question. That explanation should carry meaningful cloze
coverage of the governing method, condition, distinction, or inference step;
do not stop at a bare clozed final option if the reasoning can be stated
concisely.
- Once a private quiz page promotes an archived answer to a confirmed solution,
keep the prompt,
Solution:, and Explanation: inside one continuous quoted
question block rather than placing - solution: or - explanation: bullets
outside the quote. This keeps the archival unit visually intact and matches
the normal quoted-solution style used elsewhere in official question pages.
- Keep the explanatory cloze coverage even for image-based quiz questions.
Embedding the actual figure does not replace the flashcard duty of the text:
the quoted
Explanation: should still cloze the governing method, landmark,
contrast, or decision rule that makes the pictured answer correct.
- If the quoted
Solution: line itself contains an embedded image, keep at
least one cloze on that same Solution: line as well. Cloze the chosen
option number, the correct branch or topology label, or a short structural
descriptor of the pictured answer so the solution is directly reviewable even
before the reader reaches the explanation.
- For image-based quiz questions, prefer extracting the actual figure payloads
from archived HTML snapshots into a local quiz
attachments/ folder and
embedding them with Markdown image syntax inside the private archival page.
Preserve the original Canvas-exported filenames such as Q2_1.jpg when they
are available so the note remains traceable back to the source archive.
Replace placeholder lines like prompt figure: Q2_1.jpg with the real image
embed once extraction succeeds.
- If multiple archived snapshots exist, prefer the one that still contains the
real question-body image payloads rather than a later protected-results shell.
Only fall back to textual figure identifiers when the archive truly lacks an
extractable image payload.
- Keep the public quiz page pedagogical even when the private page embeds the
real figures: preserve conceptual hints and active-recall prompts on the
public side instead of copying the full official image-heavy prompt verbatim.
Keep those hints close enough to the original quiz that a reader can still
recognize the target question: preserve the option family, named theorem,
transform form, timing pattern, or essential band-edge geometry when that
anchor helps. When the user asks for more context, add it mainly on the left-
hand prompt itself: use option-family cues, mutated-but-equivalent givens, or
decisive spectral, timing, or topology landmarks without reproducing the
official choices verbatim. Prefer general reasoning cues first, and use
alternate-number toy equations only when they clarify the same method better
than a direct but still non-verbatim hint would.
- If the validator still expects an activation flashcard tag on a private
archive-only quiz mirror, prefer a local
ignore-file[metadata_flash_tag]: private archival quiz mirror suppression
over adding a fake active tag.
- If a quiz question is image-based and extraction is impossible, preserve the
available figure identifiers or a short description of the figure dependence
so the archival page still records what was shown.
- Keep public and private basenames aligned, for example
quiz 1.md on both
sides.
- When a course accumulates multiple converted quizzes, add a public
questions/index.md collection page that lists the quiz review pages. The
private mirror usually stays as a flat quiz-file collection unless the user
asks for a private index explicitly.
Assignment-style leaf index pages
Some leaf folders represent a single Canvas or LMS assignment-like artifact,
such as a lab round, homework, project milestone, or similar deliverable page
with local attachments. Canvas quizzes are the main exception: keep quiz notes
in questions/quiz N.md (and the mirrored private quiz file when archived)
rather than in assignments/online quiz N/index.md.
Use these rules when the source is a Canvas assignment HTML page:
- Keep the visible Canvas wording verbatim in the description body.
- Preserve color with
<span style> and use Markdown for bold, italics,
links, paragraphing, and line breaks.
- Treat the Canvas title header as metadata inside
## description, not as a
Markdown heading. The first property in that section should be exactly
- title: <Canvas title header verbatim>.
- Normalize any Canvas-derived metadata value that contains a date, datetime,
or duration into ISO 8601. Use timezone-aware ISO datetimes for point events
such as
Due or locked at; use an ISO datetime range and append , <ISO duration> when both endpoints are known; use an ISO duration for pure
durations. If only the closing endpoint is known, prefer a key such as
- Available until: 2026-04-09T13:30:59+08:00 rather than a human-readable
phrase. Canvas start timestamps should use seconds :00; Canvas end
timestamps should use seconds :59.
- Apply that normalization to Canvas metadata fields only, not to the
ordinary prose body of
## description. Keep description prose verbatim even
when it contains human-readable dates or times, such as This assignment was locked Mar 5 at 1:30pm. or colored Due on notice text copied from Canvas.
The normalized metadata bullets should carry the machine-readable timing,
while the surrounding Canvas wording stays as originally shown.
- For these assignment-style leaf indexes, use this section order:
index metadata (with no extra
--- after the parent line), ## children,
## description, ## attachments, ## submission, and ## solution.
- Omit generic
## logistics and ## overview sections on these pages.
- Include an explicit attachments list pointing to the local
attachments/
files.
- Leave
## submission and ## solution empty until actual repository
content is provided.
- If the user wants only the statement or public handouts exposed publicly,
keep those files in the public
attachments/ folder and move only
submission or solution artifacts into the mirrored private/ subtree.
- When a solution artifact exists, format
## solution the same way as
## attachments: use a plain markdown file list such as
- [HW1_Sol.pdf](solution/HW1_Sol.pdf).
- If the submission section needs archived-filename provenance or similar
metadata, keep that extra structure only in
## submission, for example
- file: [submission.pdf](submission.pdf) followed by nested metadata
bullets such as - filename: ....
- When the task still wants the public page to preserve the normal artifact
routes, keep standard relative links in public
## submission /
## solution sections as if the files were colocated, for example
[submission.pdf](submission.pdf) or
[HW1_Sol.pdf](solution/HW1_Sol.pdf). Do not rewrite those links to
private/ paths in the public note.
- Preserve the visible Canvas wording that mentions private-only or missing
artifacts. If a referenced file truly is absent from the archive, keep the
wording as plain text or add a short absence note rather than inventing a
fake file.
When an assignment-style leaf folder also has companion pages such as
lab.md, prelab.md, submission.md, or similar pages:
- Let
index.md own the Canvas wording, logistics, availability, file types,
and attachments list.
- Use the companion pages for new knowledge points, worked cases,
implementation pitfalls, or interpretation habits that are specific to the
assignment family.
- Keep companion-page prose and flashcards about pure knowledge only. Avoid
workflow checklists, student expectations, assessment framing, or other
logistics-like prose in
lab.md, prelab.md, and similar pages.
- Do not embed course-specific file references (filenames, submission scripts,
temporary handout names, or exported worksheet names) in durable companion-
page prose unless the file itself is the subject. Keep those references in
archive metadata,
attachments/, or submission records instead.
- When the source material includes concrete programming work such as MATLAB,
companion pages should also preserve the local implementation knowledge:
short code idioms, function choices, indexing patterns, plotting habits, and
data-representation details that make the assignment's subject matter
operational. Prefer a few concise snippets over full script dumps.
- For code-centered flashcards in companion pages, keep enough local context in
the prompt to make the card standalone: include the relevant MATLAB fragment,
variable roles, or input-output relationship instead of asking only a short
generic question about a function name.
- When a code-centered flashcard still feels too abstract, also put the local
given on the left-hand side: the specific waveform, filter, index formula, or
before/after workflow that the student is supposed to remember.
- When the user asks for “more context,” prefer adding that context to the
left-hand side prompt itself rather than only expanding the answer. The
question should carry the local givens before the separator.
- Avoid meta-summary sections whose main job is to describe what the note
covers. Companion pages should read like normal subject-matter notes: start
with the content itself, and use ordinary reference sentences when routing to
durable topic notes.
- Keep prelab pages restricted to preparation-stage knowledge and setup habits.
Move solved assignment-specific values, extracted peaks, chosen cutoffs,
reconstructed formulas, and post-hoc response interpretation into
lab.md
instead of leaving those results in prelab.md.
- If a concept already has a durable topic note, link to that note instead of
re-teaching the theory in the companion page.
- Do not add flashcards for theory that is already covered in the topic note;
keep companion-page flashcards focused on page-specific knowledge or worked
cases.
Flashcards and markup
The repository supports only three flashcard patterns:
- Cloze:
{@{hidden text}@}
- Two-sided QA:
term ::@:: definition
- One-sided QA:
term :@: answer
Core rules:
- Cloze syntax is strict:
{@{ opens and }@} closes. No nesting, no
multiline clozes, and no }} pseudo-closing token.
- Do not place clozes inside existing math delimiters. If you want to hide
an equation, cloze the entire equation from outside.
- Topic notes should prefer QA cards over cloze in prose, except that embedded
accounting journal-entry worked examples may use cloze in their quoted
scenarios, tables, calculations, and short explanations.
- Flashcards must be self-contained. Repeat givens, hypotheses, notation, and
any relevant diagrams if the card would otherwise be ambiguous.
- For mathematical prompts, LaTeX on the left-hand side is acceptable when it is
the natural statement of the prompt.
- For derivation or approximation clusters, descriptive left-hand prompts are
often better than dumping the whole derivation on the left.
- Use one or two focused ideas per card unless the method is naturally short and
unified.
- Nested flashcard bullets must indent by exactly two spaces per level and
include the full in-file parent path.
- Calculation cards must keep all givens on the left; do not shorten them by
removing data.
- Keep the right-hand side single-line in source and use
<br/> for internal
structure.
- In accounting QA cards, use
<br/> to separate distinct journal entries,
dates, or accounting steps — not every individual Dr/Cr line inside one
journal entry. Keep one entry grouped together with commas or semicolons
unless line-by-line separation is itself the learning target.
- Units should stay inside math delimiters, for example
$5\text{ V}$.
Validation suppressions
Prefer fixing the content over suppressing the validator. When suppression is
truly necessary, use one of these forms with a short rationale:
ignore-line[rule_id]
ignore-next-line[rule_id]
ignore-file[rule1, rule2]
Additional rules:
- Line and next-line suppressions apply only to their local target.
- File-level suppressions are for genuine special cases, such as assignment-style
index pages that intentionally omit the normal
# index / children shell.
- Do not add a file-level suppression for a rule that never fires in the file;
that is redundant.
- Do not place more than one directive of the same type on the same line; merge
rule IDs into one directive when needed.
- If a rule such as
numeric_text_not_latex keeps firing on room identifiers,
percent-encoded link destinations, inline code, or HTML comments, treat that
as a validator bug: mask the non-prose span or refine the rule instead of
scattering repeated suppressions through course notes.
- Conceptual law cards may justify a local suppression when a descriptive prompt
is pedagogically stronger than a formula-heavy calculation prompt.
Filenames, titles, links, and external lookups
- Prefer lowercase filenames unless a proper noun requires capitalization.
- Use
%20 in markdown links but do not percent-escape actual filenames.
- Topic-note filenames should normally follow the singular canonical concept.
- When linking to
general/, prefer the canonical article title and the correct
relative path, but do not create or edit the general/ file automatically.
- Use the Wikipedia helper only to discover canonical titles.
Validator and tooling
Use the validator as the structural authority for this skill.
The validator location is fixed: .agents/skills/academic-notes/check.py.
Do not recurse through .agents/skills/academic-notes/, list the whole
folder, or search the entire workspace just to locate it. Run the fixed path
directly and pass the smallest relevant course-note path.
# POSIX shell
uv run .agents/skills/academic-notes/check.py special/academia/<institution>/ELEC\ 1100
# Windows PowerShell or cmd
uv run .agents/skills/academic-notes/check.py "special/academia/<institution>/ELEC 1100"
# Validate a single file instead of a whole course when possible
uv run .agents/skills/academic-notes/check.py "special/academia/<institution>/ELEC 1100/index.md"
Rules of thumb:
- Validate the smallest relevant scope only.
- Do not run the validator on the repository root, the whole workspace, or
the entire skill folder.
- Common failures include missing tags, missing
datetime, invalid headings,
broken section-card structure, duplicate week numbers, exams placed too early,
and malformed cloze syntax.
- Common index-related rules include
index_children_order,
index_children_missing, and index_children_missing_index.
- Common cloze-related rules include
cloze_open_close_matching,
cloze_wrong_closing_token, cloze_single_line, and cloze_no_nested.
- Common math-layout rules include
latex_block_no_newline,
latex_not_standalone, and no_soft_wrap_paragraph.
Developer tooling and tests
- Validator and helper tests for this skill live in
.agents/skills/academic-notes/tests_a7392be/.
- If you extend validator behavior or helper scripts in this skill folder, add
or update tests there.
- When you change repository-level tooling that processes course notes more
broadly, repository-level tests may still belong under
tests/; choose the
smallest scope that matches the code being changed.
- After structural fixes, run repository formatting, checks, and tests on
explicit paths when practical.
Extending the validator
When prose guidance is not enough, extend the validator instead of relying on
repeated suppressions.
- Add a new pure rule in
check_mods/rules.py and register it with
@RULE_REGISTRY.register().
- Add matching tests in
tests_a7392be/check_mods/test_rules.py or the most
relevant test module in tests_a7392be/.
- Run the validator or tests against representative notes.
- Document the new rule briefly here or in the instruction/template if authors
need guidance when it fires.
Continuous improvement
Keep the skill concise, authoritative, and aligned with the validator.
- If a durable lesson appears, update
SKILL.md, course-template.md, the
instruction file, and tests in the same task when appropriate.
- Do not use persistent memory as a second documentation system for academic-
notes conventions.
- Prefer editing the validator when the issue is structural and recurring.
- Keep changes focused and reviewable; avoid broad mechanical rewrites unless
they clearly improve the guidance structure.
Workflow for agents
- Identify whether the lesson belongs in prose, the template, or the validator.
- Update the authoritative file immediately rather than leaving a side note.
- If the issue is structural, teach the validator and add a test.
- Re-run the relevant validation or tests on the affected scope.