| name | knowledge-base-maintainer |
| description | Add, update, and normalize Markdown knowledge files in this repository so they stay structurally correct, discoverable, and aligned with SoulMap AI conventions. |
Knowledge base maintainer
Use this skill when creating or editing Markdown knowledge files under:
Do not use this skill for
Mission
Keep the content layer of the repo healthy.
That means:
- correct front matter
- consistent naming
- clean internal links
- valid local anchors
- canonical SoulMap-specific term casing
- accurate cross-references
- content that matches the actual repo structure
Sources of truth
Always check:
docs/engineering/DEV.md
docs/engineering/content-contract.md
README.md
- relevant files in
skills/ and templates/
What to maintain
Structural correctness
Ensure that Markdown files:
- use kebab-case filenames where expected
- keep valid YAML front matter
- use the correct
name value for the filename stem
- preserve heading structure and link targets
- keep local Markdown links and anchors resolvable
- keep canonical product and tool names cased correctly where the repo enforces them
Content accuracy
Ensure that docs and knowledge files:
- do not reference deleted files
- do not omit important new modules or guides
- do not describe behavior the repo does not implement
- do not leak source-specific names, local paths, or temporary working markers into
tracked Markdown
Cross-file consistency
Check for drift between:
- docs and tests
- README and internal guides
- templates and brand doctrine
- safety docs and implementation modules
Workflow
- Read the target file.
- Identify nearby source-of-truth files.
- Update the content with the smallest correct change.
- Run the Markdown contract and local Markdown QA checks for touched files when relevant.
- If the edit changes public URLs, run the opt-in external link check as well.
- Preserve existing tone and structure unless the file is clearly inconsistent.
- Prefer repo-wide consistency over local phrasing preference.
Expected output
When using this skill for review, respond with:
Findings
List broken links, structural issues, stale references, or consistency gaps.
Proposed update
Provide the corrected content or summarize the change.
Notes
Mention any repo-wide impacts such as docs that should also be kept in sync.
Verification
Mention which Markdown QA commands were run and whether any existing repo issues remain.
If public URLs changed, mention whether the opt-in external link check was run and
whether any warnings came from anti-bot or rate-limit responses.
Writing rules
- Do not invent metadata fields the repo no longer uses.
- Keep edits ASCII unless the file already uses non-ASCII intentionally.
- Prefer concise descriptions in front matter.
- Do not over-refactor content that is already correct.
- Do not use Python constant names, module paths, or code identifiers in prose.
Write what a concept means, not what it is called in the implementation.
Wrong:
ACUTE_GRIEF (44 phrases in src/soulmap/runtime/config/affect.py)
Right: Acute grief, loss just happened or recently named
Definition of done
The updated knowledge file should be:
- structurally valid
- linked correctly
- aligned with repo conventions
- consistent with adjacent docs and templates