project-knowledge

Record project glossary terms, settled decisions, and unresolved follow-ups in structured Markdown files.

Updated Sep 17, 2026
One-click install
npx skills add https://github.com/hkw2028/toy-project --skill project-knowledge-hkw2028
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: project-knowledge
Source: https://github.com/hkw2028/toy-project/tree/main/.agents/skills/project-knowledge
Command: npx skills add https://github.com/hkw2028/toy-project --skill project-knowledge-hkw2028

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Teams lose track of why decisions were made, use inconsistent terminology across code and docs, and forget temporary workarounds whose root causes stay open. This Skill preserves that knowledge in durable project files so future sessions reuse the same language and never re-litigate settled trade-offs. ## Core Features & Use Cases - Glossary management: Resolve ambiguous or conflicting project terms and maintain canonical definitions in GLOSSARY.md with avoided synonyms. - Decision contracts: Record settled, reusable, non-obvious decisions as single-subject files in docs/decisions/ with rationale, boundaries, and reconsideration conditions. - Follow-up tracking: Capture temporary workarounds and out-of-scope defects with evidence in docs/follow-ups/ so later sessions can act without the original conversation. - Use Case: During planning you settle on Stripe over Paddle for payments. The Skill writes a decision contract preserving the rejected alternative and its reason, so the next session never reopens the same evaluation. ## Quick Start Ask the assistant to record the decision you just confirmed, resolve a conflicting project term, or log a workaround whose root cause is still open.

Frequently Asked Questions about project-knowledge

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I record an architecture decision so future work reuses it?

Confirm the decision is settled, reusable, non-obvious, and a real trade-off, then write a single subject file in docs/decisions using the decision contract template. Add one index entry to docs/decisions/README.md describing when to read it, without restating the decision.

How do I keep project terminology consistent across code and docs?

Resolve conflicting terms with the user, then maintain canonical definitions in GLOSSARY.md at the repo root. Each entry picks one preferred term, lists avoided synonyms, and keeps definitions to two sentences covering only project-specific vocabulary.

When should a workaround be recorded as a follow-up item?

Record a follow-up when a temporary workaround leaves its root cause open, or when an out-of-scope defect is observed with evidence. Work already fixed in the current change, guesses without evidence, and issues closed in-session do not qualify.

Should code that contradicts a decision document update the decision?

No. Code shows current behavior but not intent, so the Skill surfaces the conflict and leaves project knowledge unchanged until the user explicitly clarifies. A request to align docs with code does not by itself confirm the decision the code implies.

What happens to follow-up files once the issue is fixed?

Delete the follow-up file when the work ships or the item is promoted into a spec folder. Git history serves as the only archive; no status fields, archive copies, or superseded markers are kept.