<!-- TÜRKÇE AÇIKLAMA ─────────────── Bu skill, konuşma sırasında öğrenilen önemli bilgilerin kaybolmaması için kullanılır. Mimari kararlar, proje kuralları, bug köken nedenleri, 3. parti servis tuzakları veya tekrar araştırılmasını istemediğin her şeyi yapılandırılmış biçimde .agent/knowledge/ dizinine yazar. Böylece gelecekteki agent'lar aynı soruyu sıfırdan araştırmak zorunda kalmaz.
NE ZAMAN: Önemli bir karar alındığında, sürpriz bir bug çözüldüğünde, bir API davranışı belgelendiğinde, yeni bir proje kuralı oluşturulduğunda. ÇIKTI: .agent/knowledge/<slug>.md + INDEX.md satırı -->
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.