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:

Explain orchestrator purpose and benefits
Show orchestrator.yaml structure (nodes, pollers, defaults)
Configure first agent (e.g., EIC - Enrich Ingested Content)
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

필드	필수	설명	예시
`type`	✓	노드 타입	`agent`
`name`	✓	Agent 이름	`Enrich Ingested Content (EIC)`
`prompt`		프롬프트 파일 참조 (ABBR)	`EIC`
`input_path`		입력 디렉토리 (파일 트리거)	`Ingest/Clippings`
`output_path`		출력 디렉토리	`AI/Articles`
`executor`		실행 엔진	`claude_code`, `codex_cli`, `gemini_cli`
`cron`		스케줄 실행 (cron 표현식)	`"15,45 * * * *"`
`enabled`		활성화 여부	`true` / `false`
`timeout_minutes`		타임아웃	`30`
`completion_status`		완료 후 상태	`DONE`, `IGNORE`
`agent_params`		Agent-specific 파라미터	(object)
`workers`		Multi-Worker 설정	(list)

Node Types

Type	Trigger	Example
File-triggered	New/updated file in input_path	EIC, GDR
Cron-scheduled	Time-based (cron expression)	DDW

Worker Configuration Fields

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

필드	설명	예시
`executor`	실행 엔진	`claude_code`, `gemini_cli`
`label`	Worker 식별 라벨	`Claude`, `Gemini`
`output_path`	Worker별 출력 경로	`AI/Summary/Claude`
`agent_params`	Worker별 파라미터	(object)

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	설명	주요 설정
`limitless`	Limitless 라이프로그 동기화	`target_dir`, `poll_interval`
`apple_photos`	Apple Photos 동기화	`target_dir`, `albums`
`apple_notes`	Apple Notes 동기화	`target_dir`, `folders`

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

Command	설명
`ai4pkm --show-config`	현재 설정 보기
`ai4pkm --list-agents`	에이전트 목록
`ai4pkm --run <agent>`	특정 에이전트 실행
`ai4pkm --enable <agent>`	에이전트 활성화
`ai4pkm --disable <agent>`	에이전트 비활성화
`ai4pkm --status`	실행 상태 확인
`ai4pkm --logs`	로그 확인

Common Configuration Tasks

Add New Agent

Open orchestrator.yaml
Add new node under nodes::

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

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

Replace single executor with workers list
Define output_path per worker to separate results
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