Skill repo maintenance (pkbllm)
Source of truth
- Treat canonical skill folders under
knowledge/,productivity/,human/,bootstrap/as the source of truth. - Treat
skills/as generated output (mirror). Never editskills/by hand.
Add or import a skill (from another repo)
- Clone reference repos under
.references/(for one-time study and provenance). Never depend on.references/at runtime. - Copy only what you need into canonical folders, then adapt it for pkbllm:
- Remove upstream extras inside skills (e.g.
README.md,QUICK_REFERENCE.md, ad-hoc test files) unless truly required. - Keep skills self-contained:
SKILL.md+ optionalscripts/,references/,assets/.
- Remove upstream extras inside skills (e.g.
- Rename the skill:
SKILL.mdfrontmattername:must start withuv-.- Choose names for discoverability and to avoid collisions (use verbs when possible).
- Make it work in pkbllm conventions:
- If a skill targets the HUMAN materials repo, use
$HUMAN_MATERIAL_PATHand store bulky artifacts under.references/(gitignored) and tracked outputs underresearch/,slides/,manuscripts/,exercises/. - Prefer the pkbllm config precedence:
$HUMAN_MATERIAL_PATH/.agents/config.toml(repo override)~/.agents/config.toml(user default)
- If a skill targets the HUMAN materials repo, use
- Handle licensing:
- Check upstream
LICENSE/ notices in.references/…. - If the upstream material is not distributable, do not import it.
- Add an entry to
THIRD_PARTY_NOTICES.mddescribing what was taken and the license. - If helpful, record a
license:field in the imported skill frontmatter (e.g.MIT,Apache-2.0).
- Check upstream
Regenerate the mirror and README tables
After changing canonical skills, run:
python bootstrap/scripts/update_skills_mirror.py all
This regenerates:
skills/(mirrored skills, slugs derived from frontmattername)skills/manifest.jsonREADME.md<TABLE>sections across the repo (excluding.references/anddocs/)
Quick checks before committing
python -m compileall -q <changed_script_paths>npx -y skills add . --list(should report a skill count and not error)- Ensure no generated artifacts accidentally got committed (especially under any
.references/).
Converted and distributed by TomeVault — claim your Tome and manage your conversions.