soia-pkm-extract-vault-knowledge

Distill material carrying timestamps, task status, or source noise into Zone 20 long-term knowledge. Create new knowledge; do not move the evidence away; the original reports, articles, logs, and historical import corpora remain in their respective evidence layers.

Client-readable description

What this skill can do

Check for duplicates first, then distill concepts, guides, references, checklists, or general patterns from one or more sources.
Remove current progress, owners, next steps, and one-off environment values; retain applicability boundaries, counterexamples, timeliness notes, and source wikilinks.
Before writing, identify sensitive content such as accounts, passwords, tokens, cookies, personal paths, and customer data; knowledge notes retain only abstract methods and do not copy secret values.
When taking stock of Zone 20, distinguish "curated long-term knowledge" from "historical imports/source corpora"; do not treat the directory location of old corpora as credibility.
When handling PDF, Word, spreadsheet, or image sources, first mark the original attachment type and extraction/OCR status; without body-text extraction evidence, you may only cite the file name/path and must not treat the attachment title as a conclusion.

How clients use it

Provide the vault path and the source notes, topic, or Zone 20 scope to be organized. The Agent first gives candidates and destinations; for a single note with a clear target, it may create-only directly; when creating more than 3 notes, when duplicate names exist, or when sensitive content is involved, it must first confirm an item-by-item plan.

Dependencies and installation

Requires soia-pkm-query-vault for duplicate checking and source location. When moving misplaced files, hand off to soia-pkm-manage-vault-lifecycle; after completion, soia-pkm-maintain-vault-health can be used to check links and maps. Installing the entire soia-pkm-vault@soia plugin is recommended.

Install the entire domain (Claude Code and Codex share the same domain plugin):

claude plugin marketplace add soia-team/soia-open-skills
claude plugin install soia-pkm-vault@soia

Install only this one skill:

npx skills add soia-team/soia-open-pkm-vault-skills -g -a '*' -s soia-pkm-extract-vault-knowledge -y

WorkBuddy 's loading unit is a role-based expert rather than a plugin,npx skills add -a '*' cannot cover it; it needs to be installed separately, see docs/install/workbuddy.md。

Private information and intermediate data

By default, do not write body-text snippets of historical import corpora into the terminal or session logs; first use path filtering and --no-snippets to find candidates, then read only the necessary files. Credentials, real accounts, private absolute paths, customer identities, or family information must not be copied into knowledge notes, manifests, or public skill repositories.

Logs and completion receipt

The receipt includes: source, source SHA-256, duplicate-check results, created/skipped files, stripped status categories, sensitive-information handling, whether the source is retained, link verification, and items pending human judgment.

Execution flow

Read the root AGENTS.md, the source zone, and 20_资料库/AGENTS.md.
Use the query skill to first check the target title, topic, and backlinks; the curated zone takes priority, and historical corpora serve only as sources.
Divide candidates into:
- extract: has reusable conclusions, create new long-term knowledge;
- move: the content itself is stable, only the path is wrong, hand off to the lifecycle skill;
- evidence_only: only a timeline, task status, or personal experience, retain the evidence;
- needs_review: duplicate names, conflicts, outdated, or contains sensitive information.
Write a plan for extract: source path and SHA-256, target path, knowledge type, conclusions to retain, states to delete, sensitivity level, duplicate candidates, and source links. Use a script to generate a create-only manifest:
```
python3 scripts/knowledge_manifest.py plan --vault <vault-path> \
  --manifest <vault-relative-manifest.json> \
  --source <source.md> --target <20-target.md> \
  --type guide --sensitivity internal
```
Check ready_to_write and have the client confirm; write to the target create-only. If the target already exists, stop and compare, do not overwrite, and do not generate a "final version/new version" copy.
Use scripts to verify that the source has not drifted, the target schema, exact source wikilinks, open items, private absolute paths, and secret value candidates. As long as the target is in 20_资料库/ or this creation produced new files, immediately follow soia-pkm-maintain-vault-health/references/index-sync-contract.md to rebuild the map; when the target falls within the scope of an existing Base, run vault_index_verify.py, do not repeatedly maintain a list for a single file:
```
python3 scripts/knowledge_manifest.py verify --vault <vault-path> \
  --manifest <vault-relative-manifest.json>

python3 <health-skill>/scripts/gen_vault_map.py --vault <vault-path>
python3 <lifecycle-skill>/scripts/vault_index_verify.py --vault <vault-path>
```

For detailed criteria and field contracts, see references/knowledge-contract.md。

Content contract

Long-term knowledge body must answer at least:

What is the conclusion or method;
What conditions it applies to, and what it does not apply to;
Where the evidence comes from, and what remains to be verified;
How to execute or reuse it;
Common failure modes, risks, or timeliness.

Do not copy the entire report, do not retain owner/status/priority/next_action, and do not write old commands, ports, product versions, or organizational facts as eternal conclusions.

Boundaries with other skills

Intent	Responsible skill
Find existing knowledge or sources	soia-pkm-query-vault
Create new long-term knowledge retained from sources	This skill
Move Inbox, misplaced notes, or historical files	soia-pkm-manage-vault-lifecycle
Dead links, duplicate names, maps, and weekly health	soia-pkm-maintain-vault-health
Article topic/MOC organization	soia-pkm-organize-article-moc

Do not use move to relocate frozen evidence from Area 30 to Area 20; keep the original in Area 30 and create a new distilled draft in Area 20.

Area 20 target directories follow 10_主题知识/、20_规范与手册/、30_学习指南/; the historical import migration target is 90_历史导入/, and its classification uses numbered directories. Renaming directories is a lifecycle migration and is not directly performed by this skill.

Acceptance

The source is retained and its SHA-256 matches the plan.
The target is a new file, the frontmatter is complete, the first tag is 资料库, and it includes 长期知识 and a source wikilink.
The body contains no current task status, open to-dos, or identifiable secret values.
Notes on the same topic have been merged or it is clearly explained why they coexist.
Automatic fixture forward test "Area 30 audit → Area 20 guide": the original evidence is unchanged, the target is newly created, and both target conflicts and source drift stop.
If an Area 20 file was created, the receipt includes the map updated, file/directory statistics, and relevant Base verification; if there is no Base, clearly record that it is not configured, and do not write a skip as a pass.