Ai4pkm Helper

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, applephotos, applenotes)
• 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 (claudecode, codexcli, gemini_cli)
• Poller: External data sync (limitless, applephotos, applenotes)
• 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

| 필드 | 필수 | 설명 | 예시 | |------|------|------|------| | 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 | 특정 에이전트 실행 | | ai4pkm --enable | 에이전트 활성화 | | ai4pkm --disable | 에이전트 비활성화 | | ai4pkm --status | 실행 상태 확인 | | ai4pkm --logs | 로그 확인 |

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

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: jykim
• Source: jykim/claude-obsidian-skills
• License: MIT

Install and usage instructions live in the source repository linked above.