Illustrated Knowledge Learning Skill
Given a topic, deliver a knowledge article in Chinese that explains the principles, complete with generated and embedded explanatory diagrams, traceable sources, and prompts, and save it to the user's Obsidian vault.
Prerequisites
The host environment must be able to load the skill or execute these instructions, with internet access, file read/write capabilities, and a callable image generation model. A Codex / ChatGPT environment with these capabilities is recommended; other Agents can use configured image generation tools. Directly writing to the local Obsidian vault also requires local file access. If only export is possible, deliver the article and images and explain the archiving gap. First check the actual available tools; do not assume full capabilities based solely on product names.
Choose Output Format
- Knowledge Article: Complete steps 1–6 below for fact-checking, illustrated explanation, and Obsidian archiving.
- Project Illustrated README: First read the README Workflow. Organize illustrated content around "what it does, what the output looks like, how to install, and how to use it for the first time," and save it within the project. This format does not require Obsidian configuration, nor does it follow the article length, image count, YAML, or summary diagram requirements of a knowledge article. Fact-checking, writing, and diagram generation principles continue to apply.
Scope and Default Results
- A complete article is typically about 3000–6000 Chinese characters with 3–5 explanatory diagrams; the image count includes a comprehensive summary diagram at the end, adjusted per topic.
- Start with a concept introduction on a light background that explains "what it is, how it works, and what problem it solves," including the full definition; then introduce necessary background, motivation, and origin.
- Images default to the Jiale AI Studio Style. The main text and figure captions explain conditions that affect understanding, and the images directly illustrate the knowledge.
- For revision tasks, only modify the parts specified by the user. When only adjusting the opening card, preserve the main text, figures, captions, and figure style; only regenerate figures when the user explicitly requests redrawing.
- Perform fact-checking, writing, generation, and archiving within the authorized scope. If configuration is missing and affects the result, ask in a focused manner; do not turn basic layout choices into approvals.
1. Determine Notes Vault and Dependencies
Read the config.local.json file in the skill root directory (if it exists). Current explicit instructions take precedence over configuration; if configuration is missing, fall back to the user's environment or knowledge base guidelines. See Archiving Rules for fields. If the target vault is missing and cannot be determined from context, only ask for the target vault path, then complete independent research and draft work.
After entering the target vault, read the existing AGENTS.md, usage guide, and home page; refer to similar notes to determine directory structure, metadata, and link format. When relying on wikilink content, open the actual file.
Use the following capabilities as needed at this stage, locating them from the current environment's skill directory to avoid hardcoded installation paths:
| Capability | Prioritize Reuse | If Not Installed |
|---|---|---|
| Platform search and reading | agent-reach; first read its instructions, use actual available channels | Use the host's available read-only search, and explain the channels used this time |
| General web and paper fact-checking | Host internet tool; can be supplemented with research-workflow | Read primary sources directly |
| Writing and diagram planning | Rules in this package; can be supplemented with content-research-writer, baoyu-article-illustrator | Follow this package's workflow |
| Bitmap generation or editing | Host's callable image generation tool; use native Image / imagegen if available | Keep completed drafts and diagram plans, clearly note image gaps |
| Local archiving | Python 3.10+, this package's archive script | Clearly note missing environment, keep transferable working files |
These external skills are not distributed with this package. Steps already authorized should continue; adhere to the actual capabilities and limitations of the host tools.
2. Fact-Check and Build Source Notes
Save sources.md in the current working directory: record the actual materials opened, URLs, versions or dates, supported conclusions, and unresolved issues. First consult official documentation, papers, source code, and original publications; platform posts are used to find clues, practical experiences, or controversies. Preferred platform materials should be obtained via Agent Reach.
Important numbers, dates, architectures, and performance conclusions in the article must correspond to the original texts actually read. Use search summaries only as clues; distinguish between facts, inferences, teaching examples, and measured results. When involving origins and evolution, verify against original sources. Read existing notes as needed, reuse concepts, and verify link targets.
Completion condition: Core mechanisms and background are supported by evidence; key disagreements are explained; the sources are sufficient to support specific examples in the article.
3. Write the Learning Narrative
Read the Writing Rules. Create a Markdown draft with YAML frontmatter. Begin with a complete definition, and organize content in the sequence: "Background and Motivation → Overall Process → Key Mechanisms → Specific Examples → Engineering Trade-offs → Learning Conclusion," adjusting the order per topic.
Place unique markers at positions worth illustrating, e.g., <!-- figure:01 -->. The main text explains reasons and intermediate reasoning; figures show structure, processes, or differences; cite sources near corresponding conclusions. The final comprehensive summary diagram comes after the main explanation but before the list of original sources.
Completion condition: Readers can explain causal processes, repeat an example, and judge applicable conditions; the opening definition, background, and concluding summary are connected; key conclusions align with the source notes.
4. Plan and Generate Diagrams
Read the Visual Style Guide. Save illustration-plan.md, listing for each diagram: the question it answers, corresponding paragraphs, nodes, edges, values, and captions. If reusing Baoyu diagrams, copy that visual style guide to this directory's .baoyu-skills/baoyu-article-illustrator/EXTEND.md.
Save the complete final prompt for each diagram as files like prompts/01-flow.md. Organize positive descriptions by: "explanation purpose, specific objects and relationships, layout, visual style, verbatim labels, and canvas format." Use the host's callable image generation tool; prefer native Image / imagegen when available; follow current tool rules for parameters and invocation, typically generating two images per batch.
Locate the actual files from the tool's output, copy them to the current working directory. Open each image to check terminology, Chinese characters, numbers, arrows, comparison scales, and readability. When clear errors are found, save revised prompts and make targeted corrections; keep usable versions, and honestly record any remaining gaps. Do not claim a complete illustrated result if images are missing or unverified.
5. Save to Obsidian
Read the Archiving Rules. Save images.json. First run the archiving script's --dry-run on the actual draft, images, prompts, and source notes; confirm the results before archiving. Resolve the skill directory to an actual path, then call scripts/archive_note.py, explicitly passing the target vault, note directory, and attachment directory.
The archiving script only adds new notes; if a note with the same name exists, it creates a version suffix. When modifying an existing article, first back it up, then make in-place changes as authorized; do not create a second duplicate archive, and do not regenerate unchanged images.
If a card style needs to be defined, use assets/jiale-knowledge.css; on first installation, only append this snippet, preserving the user's existing settings and customizations. If a suitable index exists in the knowledge base, add one link to it, avoiding duplicates.
6. Final Verification
Verify that the final article, images, and files actually exist; that all figure markers have been replaced; and that embedded content and wikilinks can be resolved. Report the actual verification scope for file checks, in-image text review, and UI preview separately.
When delivering, briefly describe what was completed, the save location, and any actual gaps; provide openable notes or exported files. A knowledge article is only marked as complete when sources, main text, real diagrams, and archiving are all finished. For project READMEs, verify according to the corresponding workflow's completion conditions.