knowledge-base

Knowledge Base Skill

A knowledge base management tool designed to eliminate cognitive biases and make tacit knowledge explicit. It combines code scanning (ace-tool), web search, and structured document management to build a project's "second brain".

Core Philosophy: Breaking the "Curse of Knowledge"

The "Curse of Knowledge" refers to the difficulty, once we possess a certain kind of knowledge, of imagining the state of someone who does not understand it. In software engineering, this manifests as:

• Senior developers assume newcomers "should know" certain context.
• The code is full of domain-specific abbreviations and metaphors.
• The background of architectural decisions is forgotten, leaving only the results.

This skill addresses this problem through the following methods:

1. Explicitness: Forcibly convert tacit knowledge into explicit knowledge.
2. Context Alignment: Extract domain terms through code scanning and establish a unified vocabulary.
3. Cognitive Consensus: Record "why it is done this way" rather than just "how to do it".

Execution Environment

Path Type	Path	Description
Skill Directory	~/.pi/agent/skills/knowledge-base/	Script and template location
Main Script	~/.pi/agent/skills/knowledge-base/lib.ts	Core logic script
Knowledge Base Directory	./docs/knowledge/	Project root directorydocument storage location under

Directory Structure

docs/knowledge/
├── concepts/             # 领域概念与术语 (名词解释)
│   ├── [Term].md         # 一级文档：e.g. "DoubleEntryBookkeeping.md"
│   └── auth/             # 二级分类
│       ├── User.md
│       └── Session.md
│   └── frontend/         # 二级分类
│       ├── responsive/   # 三级分类
│       │   └── design/   # 四级分类
│       │       └── MobileFirst.md
│       └── pwa/          # 三级分类
│           └── advanced/ # 四级分类
│               └── optimization/  # 五级分类
│                   └── ProgressiveWebApp.md
├── guides/               # 操作指南与最佳实践 (How-to)
│   ├── [Topic].md        # 一级文档：e.g. "ErrorHandlingStrategy.md"
│   └── backend/          # 二级分类
│       ├── API.md
│       └── Database.md
│   └── frontend/         # 二级分类
│       └── css/          # 三级分类
│           └── flexbox/  # 四级分类
│               └── ResponsiveLayout.md
├── decisions/            # 认知决策记录 (Why)
│   ├── [Date]-[Topic].md # 一级文档：e.g. "20240101-WhyChooseRestOverGraphQL.md"
│   └── database/         # 二级分类
│       └── 20240101-WhyUsePostgres.md
│   └── frontend/         # 二级分类
│       └── layout/       # 三级分类
│           └── modern/   # 四级分类
│               └── strategies/  # 五级分类
│                   └── 20260107-WhyUseCSSGrid.md
├── external/             # 行业共识与外部参考
│   ├── [Source].md       # e.g. "ReactPatternConsensus.md"
│   └── standards/        # 二级分类
│       └── RESTfulAPI.md
├── GLOSSARY.md           # 专业术语表（自动生成，包含定义摘要）
└── index.md              # 自动生成的知识索引（支持多层级显示）

Command Reference

All commands are recommended to be executed in theproject root directory.

# 1. 初始化
bun ~/.pi/agent/skills/knowledge-base/lib.ts init

# 2. 扫描代码提取概念 (集成 ace-tool)
bun ~/.pi/agent/skills/knowledge-base/lib.ts scan

# 3. 发现项目结构并生成文档清单
bun ~/.pi/agent/skills/knowledge-base/lib.ts discover

# 4. 创建知识条目（支持目录分类）
bun ~/.pi/agent/skills/knowledge-base/lib.ts create term "术语名称" [分类路径]     # alias for concept
bun ~/.pi/agent/skills/knowledge-base/lib.ts create concept "术语名称" [分类路径]
bun ~/.pi/agent/skills/knowledge-base/lib.ts create guide "指南标题" [分类路径]
bun ~/.pi/agent/skills/knowledge-base/lib.ts create decision "决策标题" [分类路径]

# 示例：创建带分类的文档（支持无限层级）
bun ~/.pi/agent/skills/knowledge-base/lib.ts create concept "UserAuthentication" auth/user
bun ~/.pi/agent/skills/knowledge-base/lib.ts create guide "ErrorHandling" backend/api
bun ~/.pi/agent/skills/knowledge-base/lib.ts create decision "WhyUsePostgres" database

# 三级和四级分类示例
bun ~/.pi/agent/skills/knowledge-base/lib.ts create concept "MobileFirst" frontend/responsive/design
bun ~/.pi/agent/skills/knowledge-base/lib.ts create concept "ProgressiveWebApp" frontend/pwa/advanced/optimization
bun ~/.pi/agent/skills/knowledge-base/lib.ts create guide "ResponsiveLayout" frontend/css/flexbox
bun ~/.pi/agent/skills/knowledge-base/lib.ts create decision "WhyUseCSSGrid" frontend/layout/modern/strategies

# 4. 搜索知识库
bun ~/.pi/agent/skills/knowledge-base/lib.ts search "关键词"

# 5. 生成专业术语表 (GLOSSARY.md)
bun ~/.pi/agent/skills/knowledge-base/lib.ts glossary

# 6. 生成/更新索引
bun ~/.pi/agent/skills/knowledge-base/lib.ts index

Core Feature Details

1. Intelligent Scanning (scan)

Use ace-tool to analyze the codebase, identify high-frequency terms, specific class names, and complex logic, and automatically suggest "concept documents" that need to be created.

• Input: Codebase status
• Output: Recommended list of concepts to create (docs/knowledge/suggested_concepts.md)

2. Structured Documentation (create)

Provides standardized templates that mandatorily include:

• Definition: One-sentence definition (to prevent ambiguity).
• Context: Scenarios in which it appears.
• Anti-patterns: Common misconceptions (to resolve cognitive biases).
• References: Code references or external links.

3. Industry Consensus Integration

Manage general knowledge (such as RESTful specifications and React Hooks rules) through the external directory to avoid reinventing the wheel and clarify whether this project follows the standard or has special customizations.

4. Professional Glossary Maintenance (glossary)

Automatically scan all documents under the concepts/ directory, extract the Definition parts, and generate a flattened GLOSSARY.md table.

• Purpose: Provide a quickly consultable glossary of terms, suitable for non-technical personnel or rapid context alignment.
• Format: A Markdown table containing Term (Link), Category, Definition.

Best Practices

1. When encountering an unfamiliar abbreviation: Immediately run create concept [缩写], and fill it in after finding out.
2. During code review: If explaining a piece of logic takes more than 3 sentences, create a guide and link it.
3. When a new member joins: have them read docs/knowledge/index.md, and ask them to record all points of confusion as new Issues.