From pka-skills
ALWAYS use this skill when the user mentions PKA, personal knowledge, repo map, knowledge base setup, replacing Obsidian/Notion/Tana/Heptabase, organizing notes and files into a unified system, adding roles to their AI team, project lifecycle management, transitioning or archiving projects, restoring archived projects, checking which projects are stale or winding down, bootstrapping any kind of personal knowledge assistant, OR setting up Obsidian coexistence / a hybrid monorepo (root .git + child repos at knowledge/ and projects/* coordinated via .meta). Triggers also include: "bootstrap obsidian", "bootstrap vault", "MOC stubs", "frontmatter retrofit", "bootstrap git", "initialize the hybrid repo", "set up the meta monorepo", "bootstrap all", "bootstrap everything". This skill handles first-run setup (scanning folders, inferring structure, writing CLAUDE.md, creating SQLite indexes, defining roles) AND ongoing management (updating the repo map, adding team roles, transitioning completed projects to a knowledge archive, checking project activity) AND the additive Obsidian / hybrid-monorepo bootstraps (idempotent, user-triggered, never auto-run). Use it even if the user doesn't say "PKA" explicitly — if they want to unify scattered notes, set up AI-powered file organization, or manage workspace lifecycle, this is the right skill.
How this skill is triggered — by the user, by Claude, or both
Slash command
/pka-skills:pka-bootstrapThis skill is limited to the following tools:
The summary Claude sees in its skill listing — used to decide when to auto-load this skill
First-run setup and ongoing management for a Personal Knowledge Assistance system.
references/claude-md-template.mdreferences/decision-log.mdreferences/git-bootstrap.mdreferences/git-protocol.mdreferences/inference-guide.mdreferences/obsidian-bootstrap.mdreferences/obsidian-conventions.mdreferences/owner-profile.mdreferences/pkaignore-defaults.mdreferences/project-summary-template.mdreferences/role-definitions.mdreferences/sqlite-modes.mdreferences/upgrade.mdFirst-run setup and ongoing management for a Personal Knowledge Assistance system.
Everything related to PKA setup and management:
<project> to knowledge"<project>"<project> to active"pka-bootstrap is a single skill that handles three independent bootstrap procedures. The user picks one (or all):
| Target | What it does | Idempotent? | Reference |
|---|---|---|---|
| (default) | Original PKA setup: Repo Map, .pka/, roles, SQLite, CLAUDE.md. Phase 1–3 below. | Yes | This document |
obsidian | One-time mechanical retrofit of an Obsidian vault at knowledge/: MOC stubs, person indexes, filename-pattern frontmatter, domain tags. | Yes | references/obsidian-bootstrap.md |
git | One-time setup of a hybrid monorepo: root .git, knowledge/.git, each projects/*/.git with LFS, .meta manifest, .pka/ templates and helper scripts. | Yes | references/git-bootstrap.md |
upgrade | For a workspace already bootstrapped on an earlier version of pka-skills: backs up .pka/roles/, seeds missing shared-reference files (_obsidian.md, _git-protocol.md), structured-merges new H2 sections into existing role files. Never overwrites user customizations. | Yes | references/upgrade.md |
all | Run upgrade if a previous bootstrap exists, else base PKA setup; then obsidian if knowledge/.obsidian/ exists; then git. | Yes | All four references |
Resolution rules (the orchestrator dispatches; this skill is the executor):
| Phrasing the user used | Target |
|---|---|
| "bootstrap obsidian", "bootstrap the vault", "moc stubs", "frontmatter retrofit" | obsidian |
| "bootstrap git", "bootstrap the hybrid repo", "bootstrap the monorepo", "set up meta" | git |
| "upgrade", "upgrade my pka", "bootstrap upgrade", "update my role files", "refresh the addendum behavior" | upgrade |
| "bootstrap all", "bootstrap everything", or all vocabularies appear | all |
| Generic "bootstrap" without a target qualifier | base PKA setup (existing behavior) |
If the orchestrator can't tell, it asks the user before delegating here.
Hard rules across all targets:
knowledge/.obsidian/) is not a trigger.git bootstrap never creates remote repos, sets origin URLs, or pushes. Remote topology is the user's decision.git bootstrap never auto-commits the root repo. Root scaffolding is staged for the user's review only.obsidian and git bootstraps fail soft — non-critical errors log and continue; the primary task isn't blocked.Runs before any user interaction or file modification.
Walk up from cwd checking for .pka/ directories:
def find_pka_root(cwd):
path = cwd
while path != os.path.dirname(path):
if os.path.exists(os.path.join(path, '.pka')):
return path
path = os.path.dirname(path)
return None
pka_root = find_pka_root(os.getcwd())
has_local_pka = os.path.exists('.pka/')
has_local_cmd = os.path.exists('CLAUDE.md')
| Signals | Situation | Action |
|---|---|---|
No .pka/, no CLAUDE.md | Fresh setup | Full bootstrap |
Folders present, no .pka/, no CLAUDE.md | Existing structure | Adapt bootstrap — infer, add infrastructure, don't move content |
.pka/ exists but no CLAUDE.md | Partial/interrupted bootstrap | Resume: write CLAUDE.md, skip already-created infrastructure |
CLAUDE.md exists but no .pka/ | CLAUDE.md without PKA infrastructure | Ask: "I see a CLAUDE.md but no PKA infrastructure. Treat as an existing PKA and add .pka/, or is this an unrelated CLAUDE.md?" |
.pka/ and CLAUDE.md both exist | Already bootstrapped | Update mode — refresh map, extend roles, or lifecycle command |
pka_root found and pka_root != cwd | Inside a project workspace | Refuse. Say: "You're inside a project workspace under <pka_root>. Run PKA bootstrap from <pka_root> to manage the full system." |
.pkaignoreIf .pkaignore exists at root, load it. If not, write the default (see references/pkaignore-defaults.md). Always load before scanning.
Walk the directory applying .pkaignore. For each top-level folder, collect:
CLAUDE.md → project workspace signalproject-summary.md → transitioned project signalCargo.toml, package.json, go.mod, pyproject.toml at root → code-primary project; index top-level markdown only2026-03-15-1-1-aarav.md) → meeting notes home signal (used by pka-meetings for routing)wiki.md → topic wiki home signal (used by pka-wiki for synthesis)The flat vs. subfolder-organized distinction is critical for inference quality — a folder of 30 subfolders named after people is personnel notes; a flat folder of 30 date-named .md files is a journal or meeting log.
For each folder, infer using references/inference-guide.md:
meeting-home if the folder contains date-slug meeting files; multiple folders can be taggedwiki-home if the folder contains subfolders each with wiki.md; multiple folders can be taggedPresent as a readable table. Low-confidence entries flagged for user correction at Q3.
Count noise-filtered indexable files (.md, .pdf, .docx, .txt) in knowledge-domain folders only — Active or Reference priority, excluding project workspaces (folders containing CLAUDE.md).
| Knowledge-domain file count | Mode |
|---|---|
| < 300 | Markdown-only |
| 300–800 | Index mode |
| > 800 | Index mode (strongly recommended) |
| User has CRM / structured query needs | Record-store mode (opt-in post-bootstrap only) |
Present as a recommendation already made, one-sentence rationale. Override with "change storage mode."
Three questions only.
Q1 — Name and profile: "What's your first name?" Then gather a lightweight owner profile — role/title, domain expertise, communication style preference. Keep it conversational, not a form. See references/owner-profile.md for the full protocol. Never ask more than 5 questions total across the entire interview.
Q2 — Autonomy level:
Q3 — Confirm or correct the Repo Map
Show draft map including meeting-home tags and archive destination. For low-confidence entries, ask specifically. Confirm archive destination: "I've identified <folder> as where completed project archives should live — is that right?" If none inferred, ask.
.pkaignoreWritten in Phase 1 if absent. See references/pkaignore-defaults.md.
.pka/ directory.pka/
├── roles/
│ ├── roster.md
│ ├── orchestrator.md
│ ├── researcher.md
│ └── librarian.md
├── owner-profile.md
├── session-log.md
├── decision-log.md
└── knowledge.db (index mode only)
Create owner-inbox/ and team-inbox/ at PKA root. Never create content folders when adapting to an existing structure.
CLAUDE.mdIf an existing CLAUDE.md lacks the <!-- PKA header comment: show diff and confirm before overwriting regardless of autonomy level.
Generate using references/claude-md-template.md.
Generate .pka/owner-profile.md from Q1 interview responses. See references/owner-profile.md for schema and generation rules.
Seed roles in .pka/roles/: orchestrator, researcher, librarian. See references/role-definitions.md for the standard schema and seed definitions.
Also seed two shared-reference files in .pka/roles/ (these are not roles — they have no role: frontmatter and aren't in the roster, but they sit alongside roles because the roles reference them):
| Target file | Source seed | Notes |
|---|---|---|
.pka/roles/_obsidian.md | references/obsidian-conventions.md | Inert when knowledge/.obsidian/ is absent |
.pka/roles/_git-protocol.md | references/git-protocol.md | Inert when no .meta / hybrid monorepo |
Both files are seeded verbatim from the fenced markdown block inside their source seeds. Do not overwrite if the file already exists — the user may have customized it. If absent, write it.
Seeding these in the base bootstrap is benign — they only document conventions that activate when the relevant predicate is true. It also means role-file references like "see .pka/roles/_obsidian.md" don't dangle.
session-log.md## <date> | bootstrap | PKA initialized | Repo map inferred — verify low-confidence entries | Start using team-inbox
decision-log.mdSeed with bootstrap decisions (storage mode, autonomy level, archive destination). See references/decision-log.md for entry format and when-to-log rules.
Schema generated from Repo Map. Documented in .pka/schema.md (runtime-generated, not a skill asset). Bootstrap population is metadata-only — full content indexing is the librarian's job. Target: under 30 seconds for any repo size.
See references/sqlite-modes.md for schema details.
Print: Repo Map summary, meeting-home folders, archive destination, storage mode, roles, two suggested first actions.
@researcher generates competency brief → owner-inbox/research-<role>-<date>.md.md written to .pka/roles/CLAUDE.md ## Roles section updatedroster.md updatedsession-log.md entry appendedCheck all project workspace folders (contain CLAUDE.md at root, not in .pka/):
Triggered by: "transition <folder> to knowledge"
## Archive Destination in CLAUDE.mdCLAUDE.md + top-level markdown → generate project-summary.md draft using references/project-summary-template.md → save to owner-inbox/<folder>-summary-draft.md.pkaignore matches) → confirm deletionmv <project>/ <archive-destination>/<folder>/; copy approved summarysession-log.mdproject-summary.md stays in project directory as contextobsidian)A one-time, user-triggered mechanical retrofit of an existing Obsidian vault at knowledge/. Detection-only behavior (when knowledge/.obsidian/ exists but bootstrap hasn't been run) does not modify any vault content — it only causes roles to enhance files they touch during normal work.
knowledge/.obsidian/ exists (vault is opted in).If knowledge/.obsidian/ is absent, refuse with a clear message: "No Obsidian vault detected at knowledge/.obsidian/. The Obsidian bootstrap is a no-op outside an Obsidian vault."
Full step-by-step algorithm in references/obsidian-bootstrap.md. Summary:
.pka/roles/_obsidian.md from references/obsidian-conventions.md if absent.knowledge/ collecting:
_MOC.md stub if absent).personnel/<name>/ subfolders (each gets an index.md stub if absent).knowledge/ (when hybrid_monorepo_present): Bootstrap (obsidian): N MOCs, N person indexes, N frontmatter additions. Never commits the root.Print before finishing:
Re-running produces no changes. The bootstrap detects existing MOCs, indexes, and frontmatter and skips. Augmentation on re-run is additive only (e.g., a new domain folder created since last run gets a new MOC).
git)A one-time, user-triggered setup of a hybrid monorepo: root .git coordinating independent child repos at knowledge/ and each projects/<name>/, tied together by a .meta manifest.
git and git-lfs binaries are on PATH (else fail with a remediation hint).bootstrap-assets/ (vendored templates and scripts in this plugin).Full step-by-step algorithm in references/git-bootstrap.md. Summary:
.pka/ templates from bootstrap-assets/:
gitattributes-template → .pka/gitattributes-templategitignore-template → .pka/gitignore-template.pka/ helper scripts from bootstrap-assets/scripts/:
graduate.sh, init_project_repos.sh, reinit-project-with-lfs.sh, push-all.sh, build-repo-list.sh.pka/roles/_git-protocol.md from references/git-protocol.md if absent..gitignore: create or augment to exclude child-repo content (knowledge/, projects/), inboxes (owner-inbox/, team-inbox/), local artifacts (.pka/knowledge.db*, .pka/*-log.txt), and secrets (.gitea-pat*, *.token, *.secret). Merge — never replace..git: initialize if absent. Stage files. Do not commit. Root commits are the user's review gate.knowledge/ child repo: if knowledge/.git is absent, initialize with init_project_repos.sh's pattern (templates → git init -b main → git lfs install --local → initial commit Bootstrap (git): Initial hybrid monorepo setup).projects/*/: same as knowledge/ for any directory lacking .git. Projects with .git but no LFS are flagged in the summary as reinit candidates — never modified silently..meta generation: walk knowledge/ and projects/*/, read each child's origin remote (or empty if none), write .meta JSON at root. Use build-repo-list.sh after the init pass.git remote add origin, never makes network requests.git push..git but no LFS are NOT reinitialized. They are flagged with a pointer to reinit-project-with-lfs.sh (which is a destructive opt-in operation).Print before finishing:
knowledge/: initialized with LFS / already present.git but no LFS).meta generated/updated with N entriesRe-running produces no changes. Each step checks "is this already done?" before acting.
upgrade)A user with an already-bootstrapped workspace (typically from a pre-v1.6 install) requests this target to refresh role files in place without losing customizations. Common phrasings: "upgrade my pka", "bootstrap upgrade", "update my role files".
.pka/roles/ exists (the workspace has been bootstrapped at least once).If .pka/roles/ is absent, refuse with a message pointing to base bootstrap.
Full step-by-step algorithm in references/upgrade.md. Summary:
.pka/upgrade-roles.py from bootstrap-assets/scripts/upgrade-roles.py if absent. (This is a Python helper that does the deterministic merge — no LLM-driven editing of user role files.)python3 .pka/upgrade-roles.py --workspace <root>. The helper:
.pka/roles/ to .pka/upgrade-backups/<timestamp>/.pka/roles/_obsidian.md and .pka/roles/_git-protocol.md if absentknowledge/.obsidian/ exists and the user hasn't already, suggest bootstrap obsidian for the mechanical retrofit..meta file at root, suggest bootstrap git if the user wants the hybrid monorepo.## Key Competencies and ## Output Conventions (the upgrade does not touch these — see references/upgrade.md for the rationale).Re-running on an already-upgraded workspace produces no further role-file changes (every new section's H2 heading is detected as already-present). A new backup is still created, by design.
The helper prints (and the orchestrator surfaces):
Role upgrade summary
------------------------
Backup: /workspace/.pka/upgrade-backups/<timestamp>/roles
Shared references seeded: N (M already present)
orchestrator: added K section(s):
+ ## Session-start checks (cached for the session)
+ ## File references in responses
...
librarian: added K section(s):
+ ## Obsidian coexistence (gated on `obsidian_present`)
+ ## Commit/push protocol (gated on `hybrid_monorepo_present`)
researcher: added K section(s):
...
NOTE: This upgrade only ADDS new H2 sections. It does NOT modify
existing sections (e.g., 'Key Competencies', 'Output Conventions',
or 'Invocation'). See references/role-definitions.md for any
bullet-level additions you may want to merge manually.
all)If the user requests bootstrap all or bootstrap everything:
.pka/roles/ already exists (bootstrapped previously), run the upgrade target first to refresh roles. Otherwise run base bootstrap (Phase 1–3).knowledge/.obsidian/ exists, run the Obsidian bootstrap. (If absent, skip with a one-line note in the summary.)Provides UI/UX resources: 50+ styles, color palettes, font pairings, guidelines, charts for web/mobile across React, Next.js, Vue, Svelte, Tailwind, React Native, Flutter. Aids planning, building, reviewing interfaces.
Fetches up-to-date documentation from Context7 for libraries and frameworks like React, Next.js, Prisma. Use for setup questions, API references, and code examples.
npx claudepluginhub rappdw/pka-skills --plugin pka-skills