discover-capabilities

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Discover CodeCompass Capabilities

了解CodeCompass的功能

Purpose

用途

This meta-skill teaches how to efficiently discover what CodeCompass can do without manual exploration or rediscovery.

此元技能讲解如何高效了解CodeCompass的功能，无需手动探索或重新摸索。

When to Use

适用场景

✅ Session start (understand available capabilities)
✅ User asks: "What can CodeCompass do?"
✅ Before implementing features (check if exists)
✅ Exploring unfamiliar parts of codebase
✅ Planning complex workflows (know available tools)

✅ 会话开始时（了解可用功能）
✅ 用户询问：“CodeCompass能做什么？”时
✅ 实现功能之前（检查是否已有对应功能）
✅ 探索代码库中不熟悉的部分时
✅ 规划复杂工作流时（了解可用工具）

Discovery Layers

发现层级

Layer 1: Quick Reference (CLAUDE.md)

第一层：快速参考（CLAUDE.md）

Purpose: Project overview and entry point Location:

/CLAUDE.md

Token cost: ~2,000 tokens Content: Tech stack, infrastructure, basic commands

Read for:

Project background
Technology choices
Infrastructure setup
Quick commands

用途：项目概览与入口位置：

/CLAUDE.md

Token消耗：约2000 tokens 内容：技术栈、基础设施、基础命令

适用场景：

项目背景
技术选型
基础设施搭建
快速命令

Layer 2: Structured Discovery (capabilities.json) ⭐

第二层：结构化发现（capabilities.json）⭐

Purpose: Complete module and capability map Location:

.ai/capabilities.json

Token cost: ~2,500 tokens Content: All domains, modules, relationships, entry points

Read for:

What domains exist
What modules are available
What each module can do
How modules relate to each other
When to use which module

用途：完整的模块与功能映射位置：

.ai/capabilities.json

Token消耗：约2500 tokens 内容：所有领域、模块、关联关系、入口点

适用场景：

了解现有领域
查看可用模块
知晓各模块功能
了解模块间的关联
明确何时使用对应模块

Layer 3: Skills Index (this directory)

第三层：技能索引（当前目录）

Purpose: How-to workflows and perspectives Location:

.claude/skills/

Token cost: ~700 tokens (metadata scan) Content: Workflows, roles, patterns

Read for:

How to accomplish complex tasks
What workflows exist
Which skill to apply

用途：操作工作流与视角位置：

.claude/skills/

Token消耗：约700 tokens（元数据扫描）内容：工作流、角色、模式

适用场景：

如何完成复杂任务
现有工作流情况
应选用的技能

Layer 4: Semantic Search (Weaviate)

第四层：语义搜索（Weaviate）

Purpose: Implementation-level discovery Location: Weaviate database Token cost: Variable (query results) Content: Actual code, indexed semantically

Use for:

Finding specific implementations
Similar code patterns
Deep code understanding

用途：实现级别的发现位置：Weaviate数据库 Token消耗：可变（取决于查询结果）内容：实际代码，已进行语义索引

适用场景：

查找特定实现
类似代码模式
深入理解代码

Layer 5: Source Code

第五层：源代码

Purpose: Implementation details Location:

src/modules/

Token cost: Variable (file reading)

Read for:

Exact implementation
Edge cases
Internal logic

用途：实现细节位置：

src/modules/

Token消耗：可变（取决于读取的文件）

适用场景：

精确实现逻辑
边缘情况处理
内部运行机制

Discovery Workflow

发现工作流

Quick Discovery (5 seconds)

快速发现（5秒）

bash

undefined

bash

undefined

1. Read capabilities.json structure

1. 查看capabilities.json结构

cat .ai/capabilities.json | jq '.domains | keys'

Returns: ["code_analysis", "semantic_search", "requirements_extraction", "vault_integration", "system_operations"]

返回结果: ["code_analysis", "semantic_search", "requirements_extraction", "vault_integration", "system_operations"]

2. Check specific domain

2. 查看特定领域

cat .ai/capabilities.json | jq '.domains.code_analysis'

Returns: modules, capabilities, entry_points, when_to_use

返回结果: modules, capabilities, entry_points, when_to_use

undefined

undefined

Structured Discovery (Recommended)

结构化发现（推荐）

Step 1: Read capabilities.json

json

{
  "domains": {
    "code_analysis": {
      "modules": ["ast-analyzer", "yii2-analyzer", ...],
      "capabilities": ["parse_php_ast", "extract_yii2_controllers", ...],
      "entry_points": {...}
    }
  }
}

Step 2: Identify relevant domain

User wants: "Analyze Yii2 project" →
```
code_analysis
```
domain
User wants: "Search for payment logic" →
```
semantic_search
```
domain
User wants: "Extract requirements" →
```
requirements_extraction
```
domain

Step 3: Check module capabilities

json

{
  "code_analysis": {
    "modules": ["yii2-analyzer"],
    "capabilities": ["extract_yii2_controllers", "extract_yii2_models"],
    "entry_points": {
      "cli": "codecompass analyze:yii2 <path>"
    }
  }
}

Step 4: Load relevant skill

For Yii2 analysis → Load
```
analyze-yii2-project.md
```
skill
For requirements → Load
```
extract-requirements.md
```
skill

步骤1：查看capabilities.json

json

{
  "domains": {
    "code_analysis": {
      "modules": ["ast-analyzer", "yii2-analyzer", ...],
      "capabilities": ["parse_php_ast", "extract_yii2_controllers", ...],
      "entry_points": {...}
    }
  }
}

步骤2：确定相关领域

用户需求：“分析Yii2项目” →
```
code_analysis
```
领域
用户需求：“搜索支付逻辑” →
```
semantic_search
```
领域
用户需求：“提取需求” →
```
requirements_extraction
```
领域

步骤3：查看模块功能

json

{
  "code_analysis": {
    "modules": ["yii2-analyzer"],
    "capabilities": ["extract_yii2_controllers", "extract_yii2_models"],
    "entry_points": {
      "cli": "codecompass analyze:yii2 <path>"
    }
  }
}

步骤4：加载相关技能

针对Yii2分析 → 加载
```
analyze-yii2-project.md
```
技能
针对需求提取 → 加载
```
extract-requirements.md
```
技能

Semantic Discovery (Deep Dive)

语义发现（深度探索）

When capabilities.json shows a module exists but you need implementation details:

Use Weaviate semantic search:

bash

pnpm run cli -- search:semantic "how does Yii2 controller extraction work"

Returns:

Relevant source files
Similar code patterns
Implementation examples

当capabilities.json显示模块存在，但你需要了解实现细节时：

使用Weaviate语义搜索:

bash

pnpm run cli -- search:semantic "how does Yii2 controller extraction work"

返回结果:

相关源文件
类似代码模式
实现示例

Example Flows

示例流程

Example 1: "Can CodeCompass analyze database schemas?"

示例1：“CodeCompass能分析数据库架构吗？”

Step 1: Check capabilities.json

bash

cat .ai/capabilities.json | jq '.domains.code_analysis.modules[]' | grep database

步骤1：查看capabilities.json

bash

cat .ai/capabilities.json | jq '.domains.code_analysis.modules[]' | grep database

Returns: "database-analyzer"

返回结果: "database-analyzer"


✅ **Answer**: Yes, via `database-analyzer` module

**Step 2**: Check entry points
```bash
cat .ai/capabilities.json | jq '.domains.code_analysis.entry_points'

Step 3: Check if skill exists

bash

ls .claude/skills/ | grep database


✅ **答案**：可以，通过`database-analyzer`模块实现

**步骤2**：查看入口点
```bash
cat .ai/capabilities.json | jq '.domains.code_analysis.entry_points'

步骤3：检查是否存在对应技能

bash

ls .claude/skills/ | grep database

If exists, load that skill for workflow

如果存在，加载该技能获取工作流

If not, use capabilities.json guidance directly

如果不存在，直接参考capabilities.json的指引

undefined

undefined

Example 2: "How do I search code semantically?"

示例2：“如何进行代码语义搜索？”

Step 1: Check capabilities.json

bash

cat .ai/capabilities.json | jq '.domains.semantic_search'

Returns: modules, capabilities, dependencies

Step 2: Load semantic-search skill

bash

cat .claude/skills/semantic-search.md

Follow the workflow in the skill

步骤1：查看capabilities.json

bash

cat .ai/capabilities.json | jq '.domains.semantic_search'

返回结果：模块、功能、依赖关系

步骤2：加载语义搜索技能

bash

cat .claude/skills/semantic-search.md

遵循技能中的工作流操作

Example 3: "What modules handle authentication?"

示例3：“哪些模块处理认证？”

Step 1: Semantic search in Weaviate

bash

pnpm run cli -- search:semantic "authentication and authorization modules"

Step 2: Verify in capabilities.json

bash

cat .ai/capabilities.json | jq '.module_relationships'

步骤1：在Weaviate中进行语义搜索

bash

pnpm run cli -- search:semantic "authentication and authorization modules"

步骤2：在capabilities.json中验证

bash

cat .ai/capabilities.json | jq '.module_relationships'

Discovery Decision Tree

发现决策树

┌─────────────────────────────────────┐
│ USER REQUEST                        │
└─────────────────────────────────────┘
              ↓
        ┌─────────┐
        │ What?   │ "What can CodeCompass do?"
        └─────────┘
              ↓
    Read: .ai/capabilities.json
              ↓
        ┌─────────┐
        │ How?    │ "How do I use X?"
        └─────────┘
              ↓
    Load: .claude/skills/<relevant>.md
              ↓
        ┌─────────┐
        │ Where?  │ "Where is X implemented?"
        └─────────┘
              ↓
    Search: Weaviate semantic search
              ↓
        ┌─────────┐
        │ Details │ "How does X work internally?"
        └─────────┘
              ↓
    Read: src/modules/<module>/<file>

┌─────────────────────────────────────┐
│ 用户请求                            │
└─────────────────────────────────────┘
              ↓
        ┌─────────┐
        │ 是什么？ │ “CodeCompass能做什么？”
        └─────────┘
              ↓
    查看: .ai/capabilities.json
              ↓
        ┌─────────┐
        │ 怎么做？ │ “我如何使用X？”
        └─────────┘
              ↓
    加载: .claude/skills/<相关技能>.md
              ↓
        ┌─────────┐
        │ 在哪里？ │ “X的实现位置在哪里？”
        └─────────┘
              ↓
    搜索: Weaviate语义搜索
              ↓
        ┌─────────┐
        │ 细节？  │ “X的内部工作机制是怎样的？”
        └─────────┘
              ↓
    查看: src/modules/<模块>/<文件>

Avoid Rediscovery Pattern

避免重复探索模式

❌ Old Pattern (Inefficient)

❌ 旧模式（低效）

User asks: "Can CodeCompass do X?"
Claude explores with Grep: 1,000+ tokens
Claude reads multiple files: 5,000+ tokens
Claude builds mental model: slow, error-prone
Total: 6,000+ tokens, slow, may miss things

用户询问：“CodeCompass能做X吗？”
Claude使用Grep探索：消耗1000+ tokens
Claude读取多个文件：消耗5000+ tokens
Claude构建思维模型：缓慢且易出错
总计：6000+ tokens，速度慢，可能遗漏内容

✅ New Pattern (Efficient)

✅ 新模式（高效）

User asks: "Can CodeCompass do X?"
Claude reads capabilities.json: 2,500 tokens (cached)
Claude checks domain → module → capability
Claude loads skill if complex workflow needed
Total: 2,500-4,000 tokens, instant, accurate

用户询问：“CodeCompass能做X吗？”
Claude读取capabilities.json：消耗2500 tokens（可缓存）
Claude查看领域→模块→功能
如果需要复杂工作流，Claude加载对应技能
总计：2500-4000 tokens，即时响应，结果准确

Module Relationship Understanding

模块关系理解

capabilities.json includes

module_relationships

json

{
  "indexing": {
    "depends_on": ["vectorizer", "weaviate"],
    "used_by": ["search", "vault"],
    "provides": "embedding_generation_pipeline"
  }
}

Use this to:

Understand module dependencies
Trace data flow
Plan refactoring
Debug integration issues

capabilities.json包含

module_relationships

字段：

json

{
  "indexing": {
    "depends_on": ["vectorizer", "weaviate"],
    "used_by": ["search", "vault"],
    "provides": "embedding_generation_pipeline"
  }
}

用途：

了解模块依赖关系
追踪数据流
规划重构
调试集成问题

Common Workflows Reference

常见工作流参考

capabilities.json includes

common_workflows

json

{
  "analyze_legacy_yii2": [
    "1. Verify infrastructure: codecompass health",
    "2. Analyze project: codecompass analyze:yii2 <path>",
    ...
  ]
}

Use as:

Quick reference for common tasks
Starting point for complex workflows
Checklist for multi-step processes

capabilities.json包含

common_workflows

字段：

json

{
  "analyze_legacy_yii2": [
    "1. 验证基础设施：codecompass health",
    "2. 分析项目：codecompass analyze:yii2 <path>",
    ...
  ]
}

用途：

常见任务的快速参考
复杂工作流的起点
多步骤流程的检查清单

Maintenance Notes

维护说明

This skill references:

```
.ai/capabilities.json
```
- Keep this file updated when modules change
```
.claude/skills/
```
- Skills directory for workflows
```
CLAUDE.md
```
- Project entry point

Update triggers:

New module added → Update capabilities.json
Module removed → Update capabilities.json
New workflow discovered → Consider creating new skill

本技能引用：

```
.ai/capabilities.json
```
- 模块变更时请更新此文件
```
.claude/skills/
```
- 工作流技能目录
```
CLAUDE.md
```
- 项目入口文件

更新触发条件：

添加新模块 → 更新capabilities.json
删除模块 → 更新capabilities.json
发现新工作流 → 考虑创建新技能

discover-capabilities

Original

Translation

Discover CodeCompass Capabilities

了解CodeCompass的功能

Purpose

用途

When to Use

适用场景

Discovery Layers

发现层级

Layer 1: Quick Reference (CLAUDE.md)

第一层：快速参考（CLAUDE.md）

Layer 2: Structured Discovery (capabilities.json) ⭐

第二层：结构化发现（capabilities.json）⭐

Layer 3: Skills Index (this directory)

第三层：技能索引（当前目录）

Layer 4: Semantic Search (Weaviate)

第四层：语义搜索（Weaviate）

Layer 5: Source Code

第五层：源代码

Discovery Workflow

发现工作流

Quick Discovery (5 seconds)

快速发现（5秒）

1. Read capabilities.json structure

1. 查看capabilities.json结构

Returns: ["code_analysis", "semantic_search", "requirements_extraction", "vault_integration", "system_operations"]

返回结果: ["code_analysis", "semantic_search", "requirements_extraction", "vault_integration", "system_operations"]

2. Check specific domain

2. 查看特定领域

Returns: modules, capabilities, entry_points, when_to_use

返回结果: modules, capabilities, entry_points, when_to_use

Structured Discovery (Recommended)

结构化发现（推荐）

Semantic Discovery (Deep Dive)

语义发现（深度探索）

Example Flows

示例流程

Example 1: "Can CodeCompass analyze database schemas?"

示例1：“CodeCompass能分析数据库架构吗？”

Returns: "database-analyzer"

返回结果: "database-analyzer"

If exists, load that skill for workflow

如果存在，加载该技能获取工作流

If not, use capabilities.json guidance directly

如果不存在，直接参考capabilities.json的指引

Example 2: "How do I search code semantically?"

示例2：“如何进行代码语义搜索？”

Example 3: "What modules handle authentication?"

示例3：“哪些模块处理认证？”

Discovery Decision Tree

发现决策树

Avoid Rediscovery Pattern

避免重复探索模式

❌ Old Pattern (Inefficient)

❌ 旧模式（低效）

✅ New Pattern (Efficient)

✅ 新模式（高效）

Module Relationship Understanding

模块关系理解

Common Workflows Reference

常见工作流参考

Maintenance Notes

维护说明

Related Skills

相关技能

Related Modules

相关模块