easysdd-libdoc

guidedoc teaches you "how to use X to do Y", while libdoc tells you "what each part of X looks like and how to configure it". They are completely different in nature, with different writing methods, information sources, and granularities.

A mistake in guidedoc may be unclear expression, but a mistake in libdoc is a factual error — because its information source is the source code itself, and there is a uniquely correct answer for types, default values, and signatures. The core rule of libdoc is no guessing, no copying and renaming, and reading the source code independently for each entry.

Comparison with guidedoc

	guidedoc	libdoc
Nature	Task-oriented (Tutorial / How-to)	Reference-oriented (Reference)
Answer	"How to use X to achieve a certain goal"	"What each part of X looks like and how to configure it"
Granularity	One per feature / scenario	One per entry (component/function/command)
Information Source	Solution docs + user knowledge	Source code itself (type definitions, comments, default values)
Scale	A few to a dozen articles	Dozens to hundreds of articles

Complementary: Guides reference libdoc entries for detailed references ("See xxx for complete props"), and libdoc entries link back to corresponding guides in their "Related Entries" section.

What is an "entry"

An entry is the atomic documentation unit of libdoc, and its granularity is determined by the project type:

Project Type	Entry Granularity
UI Component Library	One component = one entry
Utility Function Library	One module or function family = one entry
API Client	One endpoint family = one entry
CLI Tool	One subcommand = one entry

Confirm the entry granularity during the initialization phase and keep it consistent afterwards — changing granularity will disrupt the manifest and search functionality.

Involved Paths

libdoc outputs are not under
easysdd/
— API references are publishable products for external readers.

Entry documents →
```
docs/api/{slug}.md
```
Entry manifest →
```
docs/api/_manifest.yaml
```

docs/api/

is the default convention; if the project has existing conventions (such as

reference/

components/

), follow the project's rules — confirm this before starting.

manifest / Template / Source Code Extraction

Reference materials have been split into

reference.md

in the same directory:

Complete format and status semantics of
```
_manifest.yaml
```
Frontmatter and body template for entry documents
Source code extraction checklist (interface signatures, default values, export methods, etc.)

This skill's main body only retains process constraints: libdoc takes source code as the source of truth, no guessing, no copying and renaming from the previous entry.

Workflow

Phase 1: Initialization — Scanning and Manifest

Goal: Produce an entry manifest and lock the documentation scope.

Confirm project type and entry granularity — What type of library is this? What is the entry granularity? Is the output path
```
docs/api/
```
or the project's existing convention?
Scan source code directory — Read the file structure under
```
source_root
```
, identify public exports, and group them logically
Generate
_manifest.yaml
— All entries are initially marked
```
status: pending
```
; after saving to disk, validate syntax with
```
validate-yaml.py --file docs/api/_manifest.yaml --yaml-only
```
; show to user for review
User confirms scope — User can mark entries as
```
skipped
```
(internal implementation), adjust categories, merge or split entries; save the manifest to disk after confirmation

Phase 2: Generation — Single-entry or Batch

Mode A: Single-entry Mode

Suitable for 1-3 entries, or initial trial runs to confirm quality.

Select entry → Read source_files → Generate according to template → User review → Save to disk

After saving, validate with

validate-yaml.py --file {entry document path} --require doc_type --require entry --require status

Update corresponding entry's
```
status: current
```
in
```
_manifest.yaml
```

Mode B: Batch Mode

Suitable for a large number of

pending

entries in the manifest.

Create a sample first — Select 2-3 representative entries (different categories) from the manifest, go through "read source code → extract → generate according to template" and save to disk, mark status as
```
draft
```
first (do not directly set to current — in batch mode, the sample serves as a "style reference" and should be switched to current only after overall review)
User confirms quality standards — Review these 2-3 articles, confirm that the template, level of detail, and style meet expectations. This step cannot be skipped — 50 articles will be wasted if the user wants a different style
Batch generation — Process remaining
```
pending
```
entries one by one through "read source code → extract → generate", subagents can be used for parallel processing; mark each generated entry as
```
status: draft
```
Overall review — After batch generation, show an overview (number of entries, number of skipped entries, number of pending confirmation entries); before review, run batch validation with
```
validate-yaml.py --dir docs/api --require doc_type --require entry --require status
```
, fix errors first if any
Confirm and finalize — After user confirmation, batch update the status of both samples and batch-generated entries to
```
status: current
```

Hard rules for batch mode:

Read source code independently for each entry — Even in batch mode, do not copy content from the previous entry and rename it. Two seemingly similar interfaces often have subtle differences, and copying and renaming will definitely miss them
Sample confirmation cannot be skipped — Reason as above
Mark entries with special source code structures (dynamic exports, code generation) as
skipped
with notes temporarily — Documentation guessed by force is more harmful than no documentation

Phase 3: Incremental Update

Synchronize documentation after code changes.

Identify entries to update, choose any of the three entrances:
- Use
```
search-yaml.py
```
  to search for
```
status=outdated
```
  — marked by architecture check or last update
- Compare source files changed after
```
last_scanned
```
  in
```
_manifest.yaml
```
- Use
```
search-yaml.py --sort-by last_reviewed --order asc
```
  to prioritize entries that haven't been reviewed in the longest time, select entries that "should be checked for accuracy" for active review
Re-read source code → Compare with existing documentation → Incrementally update changed parts
Validate with
```
validate-yaml.py
```
to confirm frontmatter is not damaged
Set
```
status: current
```
and fill in
```
last_reviewed
```
with the current date

Relationship with Other Workflows

Source	Relationship
`easysdd-feature-acceptance`	After acceptance, if new/modified public library interfaces are added → Push "Need to update libdoc?"
`easysdd-guidedoc`	Guides reference libdoc for detailed references; libdoc links back to guides in "Related Entries"
`easysdd-architecture-check`	When it detects interface changes but libdoc is not synchronized, it marks the corresponding entries as `outdated` , which is handled in Phase 3 of this skill
`easysdd-feature-design`	Section 2 of the solution can be used as supplementary information source for libdoc (but source code takes precedence)
`easysdd-tricks`	When "Notes" in libdoc overlap with tricks, cross-reference instead of duplicating content

Exit Conditions

Phase 1

```
_manifest.yaml
```
has been saved to disk
User has confirmed entry scope (including skipped reasons)
Entry granularity and output path have been confirmed

Phase 2 Single-entry

Entry document is generated according to the template, including complete frontmatter
API reference section information is extracted from source code (not fabricated)
User confirmation obtained
Corresponding entry's status in
```
_manifest.yaml
```
has been updated

Phase 2 Batch

Samples (2-3 articles) have been confirmed by the user
All pending entries have been generated or marked as skipped
User has conducted overall review
Status of all entries in
```
_manifest.yaml
```
has been synchronized

Phase 3

All outdated entries have been updated or confirmed as not needing updates
No residual outdated entries in
```
_manifest.yaml
```
(unless user explicitly delays)

Common Pitfalls

❌ Writing documentation without scanning the manifest — May miss entries or duplicate content
❌ Writing API references without reading source code — The core value of libdoc is accurately reflecting source code
❌ Copying the previous entry and renaming it for the next — Will definitely miss subtle differences
❌ Skipping sample confirmation in batch mode — 50 articles will be wasted
❌ Writing spec information (invariants, test constraints) into libdoc — Belongs to
```
easysdd/
```
❌ High content overlap between libdoc and guidedoc — Overlap indicates mispositioning of one of them
❌ Deleting lines directly in
```
_manifest.yaml
```
— Change to
```
status: skipped
```
and add a note
❌ Writing non-existent source code interfaces into documentation — Take source code as the source of truth, do not fabricate content

easysdd-libdoc

NPX Install

Tags

SKILL.md Content (Chinese)

easysdd-libdoc

Comparison with guidedoc

What is an "entry"

Involved Paths

manifest / Template / Source Code Extraction

Workflow

Phase 1: Initialization — Scanning and Manifest

Phase 2: Generation — Single-entry or Batch

Mode A: Single-entry Mode

Mode B: Batch Mode

Phase 3: Incremental Update

Relationship with Other Workflows

Exit Conditions

Common Pitfalls