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.

```yaml
---
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:
   ```markdown
   ---
   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)