Skip to content

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

knowledge-base-update

Unverified

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.

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:

TypeWhen to Use
decisionArchitecture, tech choices, trade-offs
conventionNaming rules, code patterns, folder structures
bugRoot cause + fix for a non-obvious problem
gotcha3rd-party quirk, env issue, edge case trap
researchAnswer 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.
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: 463kUpdated Claude CodeCodexVerifiedInstall
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: 463kUpdated Claude CodeCodexVerifiedInstall
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: 318kUpdated Claude CodeCodexUnverifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 318kUpdated Claude CodeCodexUnverifiedInstall