omergocmen/vibe-coder-kit / .agent/skills/knowledge-base-update
knowledge-base-update
UnverifiedUse 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.
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.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 463k | Updated | Claude CodeCodex | Verified | Install |
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 463k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 318k | Updated | Claude CodeCodex | Unverified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 318k | Updated | Claude CodeCodex | Unverified | Install |