knowledge-consolidation（知识巩固）

Knowledge Consolidation

Persist valuable knowledge from AI conversations into structured, reusable documents. Captures debugging breakthroughs, architecture decisions, patterns, and lessons learned — so neither you nor the AI have to rediscover them.

Core Principle: Knowledge that stays in a chat thread is lost knowledge. This skill extracts it, classifies it, and writes it to a discoverable location in the project.

When to Use

Invoke when:

• User says "save this knowledge", "document this", "记录下来", "总结一下"
• User says "we figured it out", "that was hard to solve", "let's not forget this"
• A debugging session reaches resolution — root cause is known and fix is applied
• An architecture decision is made with clear trade-offs discussed
• A reusable pattern or workaround is discovered during development
• A non-obvious configuration was required to make something work
• User asks to summarize, consolidate, or preserve learnings from the conversation

Do NOT invoke when:

• User wants to save AI memory/identity across sessions → delegate to ai-brain
• User wants to create a reusable skill → delegate to project-skill-writer
• User wants to create a rule → delegate to trae-rules-writer
• The knowledge is trivial or already well-documented in official docs
• The conversation contains no actionable insight worth preserving

Prerequisites

• Node.js >= 18
• Target project with a supported AI IDE marker (.trae/, .claude/, .cursor/, .windsurf/)

Workflow

[L1: Detect AI IDE]
         ↓
[L2: Identify Knowledge Candidates]
         ↓
[L3: Classify Knowledge Type]
         ↓
[L4: Generate Output Path]  ← get-knowledge-path.cjs
         ↓
[L5: Write Document]        ← knowledge.md.template
         ↓
[L6: Verify & Deliver]

L1: Detect AI IDE

Scan the project root for AI IDE markers to determine the correct storage path. Check in priority order:

Detection method: Use LS or Glob on the project root looking for these marker directories. If multiple markers exist, prefer the one matching the current AI IDE environment. If none are found, halt and inform the user that a supported AI IDE marker directory is required.

L2: Identify Knowledge Candidates

Review the conversation for knowledge worth preserving. Do NOT ask the user "what should I save?" — infer from the conversation.

Candidate Signals

Extraction Rules

1. Extract the core insight, not the entire conversation
2. Include the context that makes the insight actionable (what project, what version, what constraints)
3. Preserve code snippets only when they demonstrate the key point
4. Capture why, not just what — future readers need the reasoning

If the user explicitly requests consolidation, capture everything they mention. If auto-detecting, focus on the highest-value candidate first and ask whether additional items should also be saved.

L3: Classify Knowledge Type

Select the appropriate type from the reference guide. Each type has specific structural expectations:

See knowledge-types.md for detailed descriptions and key elements per type.

Type selection rule: If the knowledge spans multiple types (e.g., a debug session that also revealed an architecture pattern), pick the primary type and mention the secondary insight in the Key Takeaways section.

L4: Generate Output Path

Run the path generator to get a unique, date-sequenced filename:

node {skill_root}/scripts/get-knowledge-path.cjs \
  -r <project_root> \
  -a <ai_type> \
  -t <type> \
  -n <filename>

Arguments

Output Format

{project_root}/{ai_path}/knowledges/{YYYYMMDD}_{daily_seq}_{type}_{filename}.md

Example: /project/.trae/knowledges/20260325_001_debug_memory-leak-fix.md

The script auto-creates the knowledges/ directory if it doesn't exist and auto-increments the daily sequence number.

Filename Guidelines

• Use lowercase kebab-case: memory-leak-fix, not MemoryLeakFix
• Be specific: react-18-hydration-mismatch, not bug-fix
• Keep it under 50 characters

L5: Write Document

Use the knowledge.md.template to write the document. Fill in all sections:

# {Title}

> **Type:** {type}
> **Date:** {YYYY-MM-DD}
> **Context:** {Brief context — project name, component, technology}

## Summary

{2-3 sentence summary of the knowledge. A reader should know whether this document is relevant after reading only this section.}

## Background

{The situation, problem, or context that led to this knowledge. Include enough detail for someone unfamiliar with the conversation to understand.}

## Details

{Technical content: code snippets, configuration, analysis, step-by-step explanation. This is the core of the document.}

## Key Takeaways

{Bullet points of actionable insights. Each takeaway should be independently useful.}

## Related

{Links to related files, docs, issues, or other knowledge documents. Leave empty if none.}

Writing Quality Rules

1. Title: Use a descriptive title that answers "what will I learn from this?" — not "Debug Session" but "Memory Leak in WebSocket Reconnection Handler"
2. Summary: Must be self-contained — a reader decides whether to read further based on this
3. Background: Include the "why" — what triggered this investigation or decision
4. Details: Use code blocks with language tags, use headings for subsections if lengthy
5. Key Takeaways: Each point is actionable — "Always check X before Y" not "X is important"
6. Related: Link to source files, PRs, or other knowledge docs when available

L6: Verify & Deliver

Before responding to the user, run through the execution checklist.

Execution Checklist

• AI IDE detected and storage path is correct
• Knowledge type matches the content (not a generic fallback)
• get-knowledge-path.cjs ran successfully and returned a valid path
• Document follows the template structure with all sections filled
• Title is descriptive and specific (not generic like "Bug Fix")
• Summary is self-contained (understandable without reading the rest)
• Code snippets have language tags and are minimal (only what illustrates the point)
• Key Takeaways are actionable bullet points
• File was written to the correct project-relative path

Delivery Report

After writing the document, report to the user:

Knowledge saved:
  Type:  {type}
  Title: {title}
  Path:  {project-relative path}

Key takeaways:
  - {takeaway 1}
  - {takeaway 2}

Error Handling

Boundary Enforcement

This skill ONLY handles:

• Detecting the AI IDE and determining the storage path
• Identifying knowledge worth preserving from conversations
• Classifying knowledge into the defined type system
• Generating unique file paths via get-knowledge-path.cjs
• Writing structured knowledge documents using the template
• Verifying document quality before delivery

This skill does NOT handle:

• Building a full knowledge base from raw sources → llm-wiki
• Persistent AI memory across sessions → ai-brain
• Creating reusable skills → project-skill-writer
• Creating project rules → trae-rules-writer
• Creating agents → project-agent-writer
• Searching or indexing existing knowledge documents (read-only retrieval is out of scope)
• Modifying or updating previously written knowledge documents

Scripts

Resources