Knowledge base update

Skill omergocmen/vibe-coder-kit/.agent/skills/knowledge-base-update

Install

npx -y skills add omergocmen/vibe-coder-kit --skill knowledge-base-update

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

What its author says it does

Copied from the file, not written here

Use this skill whenever you learn something important during a conversation: a key architectural decision, a project-specific convention, a bug root-cause, a 3rd-party API quirk, or any fact that would help a future agent avoid re-doing the same research. Writes structured entries to the project's knowledge base so that context persists across conversations and agents.

SKILL.md

4.0 KB, as published. Nobody here has run it

Knowledge Base Update Skill

When to Trigger

Activate this skill when any of the following occur:

An architectural or tech-stack decision is made (and the why matters)
A non-obvious bug is fixed (root cause + fix documented)
A 3rd-party service/API has a quirk, limit, or gotcha discovered
A project convention is established (naming, folder structure, patterns)
A research question is answered after significant investigation
A "we tried X and it failed because Y" moment happens

Step-by-Step Process

1. Identify the Entry Type

Choose the category that best describes what was learned:

Type	When to Use
`decision`	Architecture, tech choices, trade-offs
`convention`	Naming rules, code patterns, folder structures
`bug`	Root cause + fix for a non-obvious problem
`gotcha`	3rd-party quirk, env issue, edge case trap
`research`	Answer to a question requiring significant investigation

2. Determine the File Path

Write to: .agent/knowledge/<slug>.md

slug = kebab-case summary of the topic (e.g., auth-token-refresh-strategy)
If an entry for this topic already exists, update it rather than creating a new file
Group related topics under subfolders: .agent/knowledge/auth/, .agent/knowledge/infra/, etc.

3. Write the Entry

Use this exact template:

---
type: <decision|convention|bug|gotcha|research>
topic: <Short human-readable title>
date: <YYYY-MM-DD>
tags: [<tag1>, <tag2>]
---

## Summary
<One or two sentences — what was learned, bottom line up front>

## Context
<Why this came up. What problem were we solving?>

## Decision / Finding
<The actual content. Be specific. Include code snippets if helpful.>

## Rationale
<Why this choice over alternatives. What alternatives were rejected and why.>

## Consequences
<What does this affect going forward? What to watch out for?>

## References
- <File path, PR link, conversation snippet, or external URL>

4. Update the Index

After writing the entry, append a one-line summary to .agent/knowledge/INDEX.md:

| <date> | <type> | [<topic>](./<path>.md) | <one-line summary> |

If INDEX.md doesn't exist yet, create it with this header first:

# Project Knowledge Base

| Date | Type | Topic | Summary |
|------|------|-------|---------|

5. Confirm to User

After writing, report:

What was saved and where
The one-line summary that was added to the index

Rules

Never summarize vaguely. "We decided to use X" is useless without why.
Include the anti-pattern. If something was tried and rejected, document it — that's often the most valuable knowledge.
Keep entries atomic. One topic per file. Don't bundle unrelated decisions.
Date is mandatory. Future agents need to know how fresh this knowledge is.
If in doubt, write it. The cost of a redundant entry is low. The cost of a missing one is re-doing the work.