kb-add

name	kb-add
description	Quickly add a learning, rule, or note to the knowledge base. Accepts free-text input and suggests the best KB file location.
disable-model-invocation	true

Knowledge Base Quick Add

You are a knowledge base assistant. Your job is to take a piece of knowledge from the user and save it to the appropriate KB file.

Frontmatter Schema

Every KB file you create or update MUST have valid YAML frontmatter. When creating a new file, include all required fields. When updating an existing file whose content actually changed, set last-updated to today's date.

---
tags: [topic-tag-1, topic-tag-2]       # Required: lowercase tags for discovery
related: [[other-kb-file]]             # Optional: cross-references to related KB files
created: YYYY-MM-DD                    # Required: date created
last-updated: YYYY-MM-DD              # Required: date last modified (update on every write)
pinned: false                          # Optional: true = always loaded. Default false
scope: "src/api/**"                    # Optional: glob pattern(s) for auto-matching. String or array.
---

Resolving today's date (cross-platform, CRITICAL): Never guess, infer, or increment prior dates. When this skill writes created / last-updated, resolve today's date once at the start of the write phase, then reuse that single value for every write. Try these commands in order and use the first that returns a YYYY-MM-DD string:

• macOS / Linux / WSL / Git Bash (bash, zsh, sh): date +%Y-%m-%d
• Windows PowerShell / pwsh: Get-Date -Format 'yyyy-MM-dd'
• Windows cmd.exe: powershell -NoProfile -Command "Get-Date -Format 'yyyy-MM-dd'"
• Portable fallback (Node or Python available): node -e "console.log(new Date().toISOString().slice(0,10))" or python -c "import datetime; print(datetime.date.today().isoformat())"

Only update last-updated when the file's content actually changed. If an edit would leave the file byte-identical, do not rewrite it or bump the date.

Obsidian-Compatible Related Links

When a KB file has related entries in its frontmatter, you MUST also include a ## Related section at the end of the file body with the same references as [[wiki-links]]. This enables Obsidian graph view and link navigation. Always keep the related frontmatter AND the body ## Related section in sync. If there are no related files, omit the ## Related section entirely.

Instructions

Step 1: Get the Learning

Check if the user provided text after the command (e.g., /kb-add Never use the legacy auth endpoint, always use v2).

• If text was provided: Use it as the learning to save.
• If no text was provided: Use AskUserQuestion to ask:
  • Question: "What would you like to add to the knowledge base?"
  • Header: "KB Quick Add"
  • Allow free-text input.

SECURITY: Never store secrets, API keys, tokens, passwords, connection strings, or any sensitive credentials. If the user's input contains actual secret values, strip them and record only the pattern/rule (e.g., "API keys for service X must come from environment variables" rather than the actual key). Inform the user if sensitive content was redacted.

Step 2: Check KB State

1. Read CLAUDE.md: Check for the Knowledge Base section. If it doesn't exist, inform the user to run /kb-init first, then stop.
2. Scan existing KB files: Read all .md files under docs/kb/ to understand what topics already exist. Parse their frontmatter for tags and related references to inform location suggestions.
3. Parse Global Learnings: Read the Global Learnings subsection in CLAUDE.md.

Step 3: Suggest Location

Based on the learning content, existing KB structure, and frontmatter tags, determine where it best fits. Present options using AskUserQuestion:

• Question: "Where should this be saved?"
• Header: "KB Location"
• Options should include (as applicable):
  • Matching existing KB file(s) if the learning fits an existing topic — prioritize tag matches (e.g., "Append to docs/kb/api-conventions.md (tags: api, rest)")
  • A suggested new KB file if no existing file fits — prefer subfolder organization (e.g., "Create new file: docs/kb/tools/deployment.md"). Use existing folder structure as a guide.
  • "Global Learnings (docs/kb/_global-learnings.md)" if the learning is cross-cutting
  • "Custom location" for the user to specify their own path

If the user selects "Custom location", ask a follow-up:

• Question: "Enter the KB file path (relative to project root, e.g., docs/kb/my-topic.md):"
• Header: "Custom KB Path"

Step 4: Determine Metadata (for new KB files only)

If saving to a new KB file, gather metadata:

Tags: Suggest tags based on the learning content. Use AskUserQuestion:

• Question: "Suggested tags: [{suggested tags}]. Adjust or confirm?"
• Header: "KB Tags"
• Options: "Use suggested" | "Let me adjust" (free-text follow-up)

When to Load: Determine the scope patterns and keywords for the loading context:

1. Infer scope patterns from the learning content. If the learning relates to specific directories or file types, suggest glob patterns (e.g., src/api/**, *.controller.ts).
2. Use the file's tags as keywords.
3. Present the suggested "When to Load" value in the structured format: `glob1`, `glob2` — keyword1, keyword2.

• Question: "Suggested loading context: {formatted When to Load value}. Adjust or confirm?"
• Header: "Loading Context"
• Options:
  • "Use suggested" (show the formatted value)
  • "Always load (pinned)" (for critical knowledge)
  • "Let me adjust" (free-text)

Step 5: Write the Learning

If appending to an existing KB file:

1. Read the existing file.
2. Append the learning under the appropriate section (typically ## Key Rules).
3. Use imperative voice, keep it concise.
4. Deduplicate: if a substantially similar entry exists, update it rather than adding a duplicate.
5. Update last-updated in the frontmatter to the date resolved at the start of the write phase (only if file content actually changed).
6. Add any new tags to the frontmatter tags array if the learning introduces a new cross-cutting topic.
7. Add cross-references to related if the learning connects to other KB files.

If creating a new KB file:

1. Create the file with frontmatter, content, and related links:

   ---
   tags: [{confirmed tags}]
   related: [{cross-references to related KB files if any}]
   created: {today's date}
   last-updated: {today's date}
   pinned: {true if user selected "Always load", else false}
   scope: ["{glob patterns if applicable}"]   # String or array
   ---
   
   # {Topic Name}
   
   {Brief description of what this KB covers.}
   
   ## Key Rules
   
   - {The learning, concise and actionable}
   
   ## Related
   
   - [[{related-kb-file}]]
   

   Only include the ## Related section if there are related files. It must be the last section.
2. Update the CLAUDE.md Knowledge Base table:
   • Remove placeholder row if present.
   • Add new row with Topic, File path, and When to Load (use "Always (pinned)" if pinned).
   • Format the "When to Load" column using the structured format: `scope-glob1`, `scope-glob2` — tag1, tag2. Derive scope patterns from the file's scope frontmatter and keywords from tags.
   • Keep table sorted alphabetically by Topic.
3. Add reverse cross-references: if the new file relates to existing KB files, add [[new-file]] to those files' related frontmatter, update their ## Related body section to match, and update their last-updated.

If adding to Global Learnings:

1. Read docs/kb/_global-learnings.md. If it doesn't exist, create it with frontmatter (tags: [global, cross-cutting], pinned: true, today's dates) and a # Global Learnings heading.
2. Append as a bullet point under ## Key Rules.
3. Remove placeholder text if present ("No global learnings captured yet...").
4. Deduplicate against existing entries.
5. Update last-updated in frontmatter to the date resolved at the start of the write phase (only if _global-learnings.md's content actually changed).
6. Ensure _global-learnings.md is registered in the CLAUDE.md Knowledge Base table as: | Global Learnings | docs/kb/_global-learnings.md | Always (pinned) |

Step 6: Update Index and Log

1. Update docs/kb/_index.md: If this file exists, add or update the entry for the modified file with a one-line summary. Update last-updated in its frontmatter.
2. Append to docs/kb/_log.md: If this file exists, append:

   ## [YYYY-MM-DD] add | Quick add to {destination}
   - Added: "{brief learning text}"
   

Step 7: Confirm

Display:

• What was saved and where
• The formatted entry as written
• Tags applied (if KB file)
• Cross-references added (if any)