ai4pkm-helper（ai4pkm 助手）

AI4PKM Helper

This skill provides guidance for configuring and managing AI4PKM orchestrator and workers. It helps users set up agents, configure multi-worker execution, and manage CLI workflows.

AI4PKM Architecture

flowchart BT
    subgraph Gobi["Gobi Desktop"]
        subgraph Storage["Storage"]
            FS[File System]
        end
        subgraph Interface["Interface"]
            OBS[Obsidian]
            CC[Claude Code]
        end
        subgraph Core["Core"]
            ORC[Orchestrator]
            CLI[AI4PKM CLI]
        end
    end
    Storage --> Interface --> Core

3-tier model:

• Storage: Markdown files (AI-optimal format)
• Interface: Obsidian for viewing/editing, Claude Code for AI interaction
• Core: Orchestrator for automation, CLI for quick commands
• GUI: Gobi Desktop wraps all above with visual interface

When to Use This Skill

Claude should automatically load this skill when:

• User wants to add, modify, or remove agents/nodes in orchestrator.yaml
• User wants to configure multi-worker execution (comparing AI models)
• User wants to update orchestrator defaults (executor, timeout, max_parallel)
• User wants to add or modify pollers (limitless, apple_photos, apple_notes)
• User asks about CLI commands for orchestrator management
• User needs help with orchestrator.yaml structure

Quick Commands

"워커 설정" / "Worker config" → Worker Configuration Guide
"에이전트 추가" / "Add agent" → Add New Agent Node
"폴러 설정" / "Poller config" → Poller Configuration
"설정 보기" → Show Current Config (ai4pkm --show-config)
"에이전트 목록" → List Agents (ai4pkm --list-agents)
"Orchestrator 설정" → Orchestrator Setup Module
"태스크 추가" → Task Management Module

Core Modules

Module 1: Orchestrator Setup (워크플로우 자동화)

Purpose: Configure orchestrator.yaml for event-driven automation

Key Concepts:

• Node: Event-driven agent that triggers on file changes or schedules
• Executor: AI engine to run (claude_code, codex_cli, gemini_cli)
• Poller: External data sync (limitless, apple_photos, apple_notes)
• Worker: Execution unit within a node (supports multi-worker for model comparison)

Setup Process:

1. Explain orchestrator purpose and benefits
2. Show orchestrator.yaml structure (nodes, pollers, defaults)
3. Configure first agent (e.g., EIC - Enrich Ingested Content)
4. Test agent execution with file trigger

Prompt: AI4PKM - Orchestrator Setup.md

Example Configuration (current format):

version: "1.0"

orchestrator:
  prompts_dir: _Settings_/Prompts
  tasks_dir: _Settings_/Tasks
  logs_dir: _Settings_/Logs
  skills_dir: _Settings_/Skills
  max_concurrent: 3
  poll_interval: 1

defaults:
  executor: claude_code
  timeout_minutes: 30
  max_parallel: 3
  task_create: true

nodes:
  - type: agent
    name: Enrich Ingested Content (EIC)
    input_path: Ingest/Clippings
    output_path: AI/Articles
    executor: claude_code

  - type: agent
    name: Daily Driver Workflow (DDW)
    cron: "15,45 * * * *"
    output_path: Journal
    completion_status: IGNORE
    agent_params:
      calendars:
        - Default
        - Work
      past_hours: 24
      future_days: 3
      goals_file: _Settings_/Goals & Principles.md
      roundup_lookback_days: 7

pollers:
  limitless:
    enabled: true
    target_dir: "Ingest/Limitless"
    poll_interval: 300

Node Configuration Fields Reference

Node Types

Worker Configuration Fields

Multi-worker 설정 시 각 worker에 사용 가능한 필드:

Multi-Worker 설정 예시 (여러 AI 모델 비교/평가):

- type: agent
  name: Article Summary Comparison
  prompt: EIC
  input_path: Ingest/Articles
  workers:
    - executor: gemini_cli
      label: Gemini
      output_path: AI/Summary/Gemini
    - executor: claude_code
      label: Claude
      output_path: AI/Summary/Claude
    - executor: codex_cli
      label: Codex
      output_path: AI/Summary/Codex

Poller Configuration

Pollers sync external data sources to your vault.

Poller 설정 예시:

pollers:
  limitless:
    enabled: true
    target_dir: "Ingest/Limitless"
    poll_interval: 300

  apple_photos:
    enabled: false
    target_dir: "Ingest/Photos"
    albums:
      - "Screenshots"
      - "PKM"

  apple_notes:
    enabled: false
    target_dir: "Ingest/Notes"
    folders:
      - "Quick Notes"

CLI Quick Reference

Common Configuration Tasks

Add New Agent

1. Open orchestrator.yaml
2. Add new node under nodes::

  - type: agent
    name: Your New Agent (ABBR)
    input_path: Ingest/YourFolder
    output_path: AI/YourOutput
    executor: claude_code

1. Create corresponding prompt in _Settings_/Prompts/

Enable/Disable Agent

  - type: agent
    name: Some Agent
    enabled: false  # Add this line to disable

Set Up Multi-Worker Comparison

1. Replace single executor with workers list
2. Define output_path per worker to separate results
3. Use consistent labels for tracking

Module 2: Task Management (태스크 관리)

Purpose: Add, update, and track tasks in AI4PKM system

Operations:

• Add Task: Create new task with description, category, priority
• Update Status: Mark tasks as in_progress, completed, or blocked
• View Tasks: List tasks by status, category, or date

Prompt: AI4PKM - Add Task.md

Task Categories:

• 🔍 Research
• 📐 Design
• 🛠️ Implement
• ✍️ Write
• 📝 Docs & System

Voice Mode Configuration

Language Support

• Support both English and Korean
• Use tts_model="gpt-4o-mini-tts" for natural pronunciation
• Continue conversation naturally

Listening Behavior

• Patient listening: Wait for user to finish (use min_listen_duration=8)
• Adaptive waiting: Don't interrupt incomplete thoughts
• Use vad_aggressiveness=0 for permissive voice detection

Progress Updates

• For long operations (10+ seconds), provide voice updates

- "지금 설정 확인 중이에요..." / "에이전트 추가하는 중입니다..."

• Keep user informed throughout process

Example Interactions

Adding an Agent

User: 에이전트 추가해줘
Agent: 어떤 에이전트를 추가할까요?
       - 파일 기반 (input_path 필요)
       - 스케줄 기반 (cron 필요)
User: 파일 기반, Ingest/Articles 폴더 감시해서 AI/Summaries에 요약 저장
Agent: 다음 설정으로 추가할게요:
       - name: Article Summarizer
       - input_path: Ingest/Articles
       - output_path: AI/Summaries
       - executor: claude_code
       프롬프트는 어떤 걸 사용할까요?

Configuring Multi-Worker

User: 여러 모델로 비교하고 싶어
Agent: Multi-worker 설정을 도와드릴게요.
       어떤 모델들을 비교할까요?
       - claude_code (Claude)
       - gemini_cli (Gemini)
       - codex_cli (Codex)
User: Claude랑 Gemini
Agent: 각 모델 결과를 어디에 저장할까요?
       예: AI/Compare/Claude, AI/Compare/Gemini

Implementation Notes

Prompt Chaining

Each prompt is independent but connected:

• Input: Previous step's output (optional)
• Process: Execute current step
• Output: Results for next step

Semi-Automatic Execution

• Each step requires user confirmation
• Keywords: "완료", "다음", "계속" → proceed
• Keywords: "중단", "나중에" → pause
• User can resume from any step

Error Handling

• Clear error messages in Korean
• Suggest fixes or alternatives
• Allow retry or skip (when safe)
• Never leave user stuck

Files Structure

_Settings_/Skills/ai4pkm-helper/
├── SKILL.md                    # This file
└── modules/                    # (Future: detailed module guides)
    ├── orchestrator.md
    └── tasks.md

_Settings_/Prompts/
├── AI4PKM - Orchestrator Setup.md
├── AI4PKM - Add Task.md
└── ...

orchestrator.yaml               # Main config file (vault root)

References

Documentation

• Orchestrator config reference: orchestrator.yaml
• CLI documentation: ai4pkm --help

Design Documents

• [[AI/Analysis/2025-12-10 AI4PKM Onboarding Agent Design - Claude Code]]

Troubleshooting

Common Issues

"에이전트가 실행 안 돼요" → ai4pkm --status로 상태 확인 후, 로그 확인: ai4pkm --logs

"폴러가 동작 안 해요" → pollers: 섹션에서 enabled: true 확인, poll_interval 값 확인

"Multi-worker 결과가 섞여요" → 각 worker에 다른 output_path 지정했는지 확인

"cron이 트리거 안 돼요" → cron 표현식 문법 확인, ai4pkm --status로 다음 실행 시간 확인

"설정 변경이 반영 안 돼요" → orchestrator 재시작 필요: ai4pkm --restart

Future Enhancements

Planned (v2.1+)

• GUI-based config editor (Gobi Desktop)
• Agent template library
• Performance monitoring dashboard
• Webhook triggers support
• Remote execution support

Notes

• Config validation: Always validate YAML syntax before saving
• Backup: Keep backup of working orchestrator.yaml
• Testing: Test new agents with small input sets first
• Logging: Check logs for troubleshooting execution issues