xingcanlee/wisp-writer

wisp-writer: Write Consistent Articles for the Wisp Theme

Wisp's philosophy is quiet, accurate, and restrained. Articles live in src/content/posts/<slug>/index.mdx (or index.md), and frontmatter is validated against src/content.config.ts. This skill provides:

SKILL.md
reference/   frontmatter.md  style-guide.md  elements.md  templates/
scripts/     new_post.py  check_post.py  tests/   (Python + uv, PEP 723 inline dependencies, no installation)

Command Convention

All commands run from the site root, written as uv run skills/wisp-writer/scripts/<script>.py .... When copying this skill to another Wisp site:

• Place in <site>/skills/wisp-writer/: commands remain unchanged.
• Place in <site>/.claude/skills/wisp-writer/ or ~/.claude/skills/wisp-writer/: replace the path with the actual location; the script will walk up from the current directory to find astro.config.* or src/content, or you can use --root <site_root> to specify.
• If the site is not found, the script will prompt and exit with code 2, without writing any files.
• Without uv: python3 <path>/new_post.py ... also works (uses only the standard library, requires Python 3.10+).

Workflow

1. Clarify the reader and key points. Before writing, note three things: who the reader is (what they know, what they don't), what they will take away (one-sentence conclusion), and the article type. If information is insufficient, ask the user first; do not fabricate facts, data, or citations.
2. Create the article. Choose a template by type: tutorial, deep-dive, algorithm (with interactive components), note (short note), paper-reading (paper interpretation).

   uv run skills/wisp-writer/scripts/new_post.py attention-explained \
     --title "Understanding Self-Attention" --template deep-dive \
     --tags "LLM,Transformer" --category Machine Learning \
     --description "From intuition to formulas, explains the computation of self-attention."
   

   Slug uses kebab-case; an existing slug will cause an error. The script lists existing tags and categories—reuse them if possible. Parameters: --draft, --md/--mdx, --date, --list-templates.
3. Write. Follow the style-guide, element syntax in elements, and fields in frontmatter. Replace all TODOs in the template.
4. Images and interactions. When images are needed, use the wisp-diagram skill to produce source files and .wisp.svg, then reference the chart using chart reference syntax; simple flows can use Mermaid directly. For interactive demonstrations, use existing explainer components (currently MatMul); other algorithms require new components—see docs/guide/explainers.md, which is a code change and should be discussed and approved separately. Do not modify code while writing the article.
5. Check and fix.

   uv run skills/wisp-writer/scripts/check_post.py attention-explained --strict
   

   Output format: file:line level rule description. Errors must be fixed; warnings should be evaluated case by case and fixed if possible; info is just a hint. --json for programmatic reading, --all to check all articles.
6. Preview. pnpm build must pass (validates frontmatter and Mermaid); use pnpm dev to preview. Optionally: use Playwright to take two screenshots of the article page (light and dark themes) and verify that formulas, charts, and code blocks don't overflow and are readable in dark mode.

Hard Rules

1. Content starts from h2; do not write h1. Headings do not skip levels. h2 uses noun phrases.
2. title ≤ 80 characters, description ≤ 200 characters; description clearly states what problem the article solves.
3. Reuse existing tags and categories with consistent casing (do not have both llm and LLM).
4. Chinese paragraphs use full-width punctuation. No manual spaces between Chinese and English. Use **bold** for emphasis in Chinese, not italics.
5. For terminology, mark the English term on first occurrence, e.g., "自注意力（self-attention）".
6. Every code block has a language identifier. Long code blocks can optionally be collapsed; leave them as-is by default.
7. Every image has alt text describing the conclusion the image conveys. Captions use "Figure N: description".
8. Do not hardcode colors, write style=, or use Tailwind color scales; colors must only come from theme variables.
9. Articles using components must be .mdx and import the component; interactive components must use client:visible.
10. Do not fabricate facts, data, citations, or links. Clearly mark or remove content you are unsure about.
11. Do not modify existing articles unless the user requests it; work only within src/content/posts/<slug>/.

Example Snippet

Below is a snippet that matches the tone (explains one thing, no fluff, no exaggeration):

## Why Divide by √d

Suppose each component of $q$ and $k$ is an independent random variable with variance 1. Then the variance of the dot product $q \cdot k$ is $d_k$. The larger the dimension, the larger the dot product, and softmax becomes closer to one-hot, making gradients very small.

After dividing by $\sqrt{d_k}$, the variance returns to around 1, and softmax output stays within a moderate range. Without this step, deep networks are difficult to train.

Compare with: "As everyone knows, this super-simple yet extremely important little trick can greatly improve performance!" — Empty, overemphasized, and uninformative.

Common Mistakes

• Beginning with "This article will introduce..." or "With the development of..." — instead, directly state the conclusion or problem.
• Writing # Heading in the body, or jumping from h2 to h4.
• Using sentence headings ("Let's see how to implement", should be "Implementation").
• Mixing half-width commas and parentheses in Chinese; using italics for emphasis in Chinese.
• Writing components in .md files, or forgetting import in .mdx files; forgetting client:visible for interactive components.
• Images without alt text; referencing .excalidraw files that haven't been generated (draw first, then reference); referencing .wisp.svg instead of source files.
• Using a new tag for the same concept (e.g., Llm, 大模型 vs. existing LLM).
• Mermaid nodes with text that is too long, causing overlap in rendered output; keep text to about 12 Chinese characters or less.
• Leaving TODO placeholders before delivery; check_post.py --strict can catch these.
• Writing code without explanation: state the purpose before the code, and explain key points or expected output after the code.