nav-init

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Navigator Initialization Skill

Navigator初始化Skill

Purpose

用途

Creates the Navigator documentation structure (

.agent/

) in a new project, copies templates, and sets up initial configuration.

在新项目中创建Navigator文档结构（

.agent/

），复制模板并完成初始配置。

When This Skill Auto-Invokes

自动触发场景

"Initialize Navigator in this project"
"Set up Navigator documentation structure"
"Create .agent folder for Navigator"
"Bootstrap Navigator for my project"

"Initialize Navigator in this project"
"Set up Navigator documentation structure"
"Create .agent folder for Navigator"
"Bootstrap Navigator for my project"

What This Skill Does

功能说明

Checks if already initialized: Prevents overwriting existing structure

Creates
.agent/
directory structure:

.agent/
├── DEVELOPMENT-README.md
├── .nav-config.json
├── tasks/
├── system/
├── sops/
│   ├── integrations/
│   ├── debugging/
│   ├── development/
│   └── deployment/
└── grafana/
    ├── docker-compose.yml
    ├── prometheus.yml
    ├── grafana-datasource.yml
    ├── grafana-dashboards.yml
    ├── navigator-dashboard.json
    └── README.md

Creates
.claude/
directory with hooks:

.claude/
└── settings.json    # Token monitoring hook configuration

Copies templates: DEVELOPMENT-README.md, config, Grafana setup
Auto-detects project info: Name, tech stack (from package.json if available)
Updates CLAUDE.md: Adds Navigator-specific instructions to project
Creates .gitignore entries: Excludes temporary Navigator files

检查是否已初始化：防止覆盖现有结构
创建
.agent/
目录结构：

.agent/
├── DEVELOPMENT-README.md
├── .nav-config.json
├── tasks/
├── system/
├── sops/
│   ├── integrations/
│   ├── debugging/
│   ├── development/
│   └── deployment/
└── grafana/
    ├── docker-compose.yml
    ├── prometheus.yml
    ├── grafana-datasource.yml
    ├── grafana-dashboards.yml
    ├── navigator-dashboard.json
    └── README.md

创建带钩子的
.claude/
目录：

.claude/
└── settings.json    # Token监控钩子配置

复制模板：DEVELOPMENT-README.md、配置文件、Grafana设置
自动检测项目信息：名称、技术栈（若有package.json则从中获取）
更新CLAUDE.md：向项目中添加Navigator专属说明
创建.gitignore条目：排除Navigator临时文件

Execution Steps

执行步骤

1. Check if Already Initialized

1. 检查是否已初始化

bash

if [ -d ".agent" ]; then
    echo "✅ Navigator already initialized in this project"
    echo ""
    echo "To start a session: 'Start my Navigator session'"
    echo "To view documentation: Read .agent/DEVELOPMENT-README.md"
    exit 0
fi

bash

if [ -d ".agent" ]; then
    echo "✅ Navigator already initialized in this project"
    echo ""
    echo "To start a session: 'Start my Navigator session'"
    echo "To view documentation: Read .agent/DEVELOPMENT-README.md"
    exit 0
fi

2. Detect Project Information

2. 检测项目信息

Read

package.json

pyproject.toml

go.mod

Cargo.toml

, or similar to extract:

Project name
Tech stack
Dependencies

Fallback: Use current directory name if no config found.

读取

package.json

、

pyproject.toml

、

go.mod

、

Cargo.toml

或类似文件以提取：

项目名称
技术栈
依赖项

备选方案：若未找到配置文件，则使用当前目录名称。

3. Create Directory Structure

3. 创建目录结构

Use Write tool to create:

.agent/
.agent/tasks/
.agent/system/
.agent/sops/integrations/
.agent/sops/debugging/
.agent/sops/development/
.agent/sops/deployment/
.agent/grafana/

使用Write工具创建：

.agent/
.agent/tasks/
.agent/system/
.agent/sops/integrations/
.agent/sops/debugging/
.agent/sops/development/
.agent/sops/deployment/
.agent/grafana/

4. Copy Templates

4. 复制模板

Copy from plugin's

templates/

directory to

.agent/

DEVELOPMENT-README.md:

Replace
```
${PROJECT_NAME}
```
with detected project name
Replace
```
${TECH_STACK}
```
with detected stack
Replace
```
${DATE}
```
with current date

.nav-config.json
:

json

{
  "version": "5.5.0",
  "project_name": "${PROJECT_NAME}",
  "tech_stack": "${TECH_STACK}",
  "project_management": "none",
  "task_prefix": "TASK",
  "team_chat": "none",
  "auto_load_navigator": true,
  "compact_strategy": "conservative",
  "auto_update": {
    "enabled": true,
    "check_interval_hours": 1
  }
}

Grafana Setup: Copy all Grafana dashboard files to enable metrics visualization:

bash

undefined

从插件的

templates/

目录复制到

.agent/

：

DEVELOPMENT-README.md：

将
```
${PROJECT_NAME}
```
替换为检测到的项目名称
将
```
${TECH_STACK}
```
替换为检测到的技术栈
将
```
${DATE}
```
替换为当前日期

.nav-config.json
：

json

{
  "version": "5.5.0",
  "project_name": "${PROJECT_NAME}",
  "tech_stack": "${TECH_STACK}",
  "project_management": "none",
  "task_prefix": "TASK",
  "team_chat": "none",
  "auto_load_navigator": true,
  "compact_strategy": "conservative",
  "auto_update": {
    "enabled": true,
    "check_interval_hours": 1
  }
}

Grafana设置：复制所有Grafana仪表盘文件以启用指标可视化：

bash

undefined

Find plugin installation directory

PLUGIN_DIR="${HOME}/.claude/plugins/marketplaces/jitd-marketplace"

Copy Grafana files if plugin has them

if [ -d "${PLUGIN_DIR}/.agent/grafana" ]; then cp -r "${PLUGIN_DIR}/.agent/grafana/"* .agent/grafana/ echo "✓ Grafana dashboard installed" else echo "⚠️ Grafana files not found in plugin" fi


Files copied:
- docker-compose.yml (Grafana + Prometheus stack)
- prometheus.yml (scrape config for Claude Code metrics)
- grafana-datasource.yml (Prometheus datasource config)
- grafana-dashboards.yml (dashboard provider config)
- navigator-dashboard.json (10-panel Navigator metrics dashboard)
- README.md (setup instructions)

if [ -d "${PLUGIN_DIR}/.agent/grafana" ]; then cp -r "${PLUGIN_DIR}/.agent/grafana/"* .agent/grafana/ echo "✓ Grafana dashboard installed" else echo "⚠️ Grafana files not found in plugin" fi


已复制文件：
- docker-compose.yml（Grafana + Prometheus栈）
- prometheus.yml（Claude Code指标的抓取配置）
- grafana-datasource.yml（Prometheus数据源配置）
- grafana-dashboards.yml（仪表盘提供者配置）
- navigator-dashboard.json（10面板Navigator指标仪表盘）
- README.md（设置说明）

5. Update Project CLAUDE.md

5. 更新项目CLAUDE.md

CLAUDE.md

exists:

Append Navigator-specific sections
Keep existing project customizations

CLAUDE.md

doesn't exist:

Copy
```
templates/CLAUDE.md
```
to project root
Customize with project info

若

CLAUDE.md

已存在：

追加Navigator专属章节
保留现有项目自定义内容

若

CLAUDE.md

不存在：

将
```
templates/CLAUDE.md
```
复制到项目根目录
结合项目信息进行定制

6. Setup Token Monitoring Hook

6. 配置Token监控钩子

Create

.claude/settings.json

for token budget monitoring:

bash

mkdir -p .claude

cat > .claude/settings.json << 'EOF'
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit|Bash|Task",
        "hooks": [
          {
            "type": "command",
            "command": "python3 \"${CLAUDE_PLUGIN_DIR}/hooks/monitor-tokens.py\"",
            "timeout": 5
          }
        ]
      }
    ]
  }
}
EOF

echo "✓ Token monitoring hook configured"

What this does:

Monitors context usage after each tool call
Warns at 70% usage, critical alert at 85%
Suggests
```
/nav:compact
```
when approaching limits

创建用于Token预算监控的

.claude/settings.json

：

bash

mkdir -p .claude

cat > .claude/settings.json << 'EOF'
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit|Bash|Task",
        "hooks": [
          {
            "type": "command",
            "command": "python3 \"${CLAUDE_PLUGIN_DIR}/hooks/monitor-tokens.py\"",
            "timeout": 5
          }
        ]
      }
    ]
  }
}
EOF

echo "✓ Token monitoring hook configured"

功能说明：

监控每次工具调用后的上下文使用情况
使用率达70%时发出警告，85%时发出严重警报
接近限制时建议使用
```
/nav:compact
```

7. Create .gitignore Entries

7. 创建.gitignore条目

Add to

.gitignore

if not present:

undefined

若尚未存在，添加以下内容到

.gitignore

：

undefined

Navigator context markers

.context-markers/

Navigator temporary files

.agent/.nav-temp/

undefined

.agent/.nav-temp/

undefined

8. Success Message

8. 成功提示

✅ Navigator Initialized Successfully!

Created structure:
  📁 .agent/                    Navigator documentation
  📁 .agent/tasks/              Implementation plans
  📁 .agent/system/             Architecture docs
  📁 .agent/sops/               Standard procedures
  📁 .agent/grafana/            Metrics dashboard
  📄 .agent/.nav-config.json    Configuration
  📁 .claude/                   Claude Code hooks
  📄 .claude/settings.json      Token monitoring config
  📄 CLAUDE.md                  Updated with Navigator workflow

Next steps:
  1. Start session: "Start my Navigator session"
  2. Optional: Enable metrics - see .agent/sops/integrations/opentelemetry-setup.md
  3. Optional: Launch Grafana - cd .agent/grafana && docker compose up -d

Token monitoring is active - you'll be warned when approaching context limits.

Documentation: Read .agent/DEVELOPMENT-README.md

✅ Navigator Initialized Successfully!

Created structure:
  📁 .agent/                    Navigator documentation
  📁 .agent/tasks/              Implementation plans
  📁 .agent/system/             Architecture docs
  📁 .agent/sops/               Standard procedures
  📁 .agent/grafana/            Metrics dashboard
  📄 .agent/.nav-config.json    Configuration
  📁 .claude/                   Claude Code hooks
  📄 .claude/settings.json      Token monitoring config
  📄 CLAUDE.md                  Updated with Navigator workflow

Next steps:
  1. Start session: "Start my Navigator session"
  2. Optional: Enable metrics - see .agent/sops/integrations/opentelemetry-setup.md
  3. Optional: Launch Grafana - cd .agent/grafana && docker compose up -d

Token monitoring is active - you'll be warned when approaching context limits.

Documentation: Read .agent/DEVELOPMENT-README.md

Error Handling

错误处理

If
.agent/
exists:

Don't overwrite
Show message: "Already initialized"

If templates not found:

Error: "Navigator plugin templates missing. Reinstall plugin."

If no write permissions:

Error: "Cannot create .agent/ directory. Check permissions."

若
.agent/
已存在：

不进行覆盖
显示提示："Already initialized"

若模板未找到：

错误提示："Navigator plugin templates missing. Reinstall plugin."

若无写入权限：

错误提示："Cannot create .agent/ directory. Check permissions."

Predefined Functions

预定义函数

project_detector.py

project_detector.py

python

def detect_project_info(cwd: str) -> dict:
    """
    Detect project name and tech stack from config files.

    Checks (in order):
    1. package.json (Node.js)
    2. pyproject.toml (Python)
    3. go.mod (Go)
    4. Cargo.toml (Rust)
    5. composer.json (PHP)
    6. Gemfile (Ruby)

    Returns:
        {
            "name": "project-name",
            "tech_stack": "Next.js, TypeScript, Prisma",
            "detected_from": "package.json"
        }
    """

python

def detect_project_info(cwd: str) -> dict:
    """
    Detect project name and tech stack from config files.

    Checks (in order):
    1. package.json (Node.js)
    2. pyproject.toml (Python)
    3. go.mod (Go)
    4. Cargo.toml (Rust)
    5. composer.json (PHP)
    6. Gemfile (Ruby)

    Returns:
        {
            "name": "project-name",
            "tech_stack": "Next.js, TypeScript, Prisma",
            "detected_from": "package.json"
        }
    """

template_customizer.py

template_customizer.py

python

def customize_template(template_content: str, project_info: dict) -> str:
    """
    Replace placeholders in template with project-specific values.

    Placeholders:
    - ${PROJECT_NAME}
    - ${TECH_STACK}
    - ${DATE}
    - ${YEAR}

    Returns customized template content.
    """

python

def customize_template(template_content: str, project_info: dict) -> str:
    """
    Replace placeholders in template with project-specific values.

    Placeholders:
    - ${PROJECT_NAME}
    - ${TECH_STACK}
    - ${DATE}
    - ${YEAR}

    Returns customized template content.
    """

Examples

示例

Example 1: New Next.js Project

示例1：新Next.js项目

User says: "Initialize Navigator in this project"

Skill detects:

```
package.json
```
exists
Name: "my-saas-app"
Dependencies: next, typescript, prisma

Result:

```
.agent/
```
created
DEVELOPMENT-README.md shows: "Project: My SaaS App"
DEVELOPMENT-README.md shows: "Tech Stack: Next.js, TypeScript, Prisma"
.nav-config.json has project_name: "my-saas-app"

用户指令："Initialize Navigator in this project"

Skill检测到：

```
package.json
```
存在
名称："my-saas-app"
依赖项：next, typescript, prisma

结果：

```
.agent/
```
已创建
DEVELOPMENT-README.md显示："Project: My SaaS App"
DEVELOPMENT-README.md显示："Tech Stack: Next.js, TypeScript, Prisma"
.nav-config.json的project_name为："my-saas-app"

Example 2: Python Project

示例2：Python项目

User says: "Set up Navigator"

Skill detects:

```
pyproject.toml
```
exists
Name: "ml-pipeline"
Dependencies: fastapi, pydantic, sqlalchemy

Result:

```
.agent/
```
created
Tech stack: "FastAPI, Pydantic, SQLAlchemy"

用户指令："Set up Navigator"

Skill检测到：

```
pyproject.toml
```
存在
名称："ml-pipeline"
依赖项：fastapi, pydantic, sqlalchemy

结果：

```
.agent/
```
已创建
技术栈："FastAPI, Pydantic, SQLAlchemy"

Example 3: Already Initialized

示例3：已初始化项目

User says: "Initialize Navigator"

Skill checks:

```
.agent/
```
directory exists

Result:

✅ Navigator already initialized in this project

To start a session: 'Start my Navigator session'

用户指令："Initialize Navigator"

Skill检查：

```
.agent/
```
目录已存在

结果：

✅ Navigator already initialized in this project

To start a session: 'Start my Navigator session'

Integration with Other Skills

与其他Skill的集成

nav-start skill:

Checks for
```
.agent/DEVELOPMENT-README.md
```
If missing, suggests: "Initialize Navigator first"

nav-task skill:

Creates tasks in
```
.agent/tasks/
```
Requires initialization

nav-sop skill:

Creates SOPs in
```
.agent/sops/
```
Requires initialization

nav-start skill：

检查是否存在
```
.agent/DEVELOPMENT-README.md
```
若缺失，建议："Initialize Navigator first"

nav-task skill：

在
```
.agent/tasks/
```
中创建任务
需要先完成初始化

nav-sop skill：

在
```
.agent/sops/
```
中创建SOP
需要先完成初始化

Version History

版本历史

1.0.0 (2025-01-20): Initial implementation
- Auto-detection of project info
- Template customization
- Grafana setup included
- Error handling for existing installations

1.0.0 (2025-01-20)：初始实现
- 自动检测项目信息
- 模板定制
- 包含Grafana设置
- 已存在安装的错误处理

Notes

注意事项

This skill replaces the deleted
```
/nav:init
```
command from v2.x
Templates are copied from plugin installation directory
Project info detection is best-effort (falls back to directory name)
Safe to run multiple times (won't overwrite existing structure)

本Skill替代了v2.x中已删除的
```
/nav:init
```
命令
模板从插件安装目录复制
项目信息检测为尽力而为（未找到时回退到目录名称）
可安全多次运行（不会覆盖现有结构）