Enhancement Modes Guide

Enhancement Modes Guide

Complete guide to all LOCAL enhancement modes in Skill Seekers.

Overview

Skill Seekers supports 4 enhancement modes for different use cases:

1. Headless (default) - Runs in foreground, waits for completion
2. Background - Runs in background thread, returns immediately
3. Daemon - Fully detached process, continues after parent exits
4. Terminal - Opens new terminal window (interactive)

Multi-Agent Support (NEW)

All enhancement modes now support multiple local coding agents:

Supported Agents

Agent Selection

CLI Flags:

# Use Codex CLI
skill-seekers enhance output/react/ --agent codex

# Use Copilot CLI
skill-seekers enhance output/react/ --agent copilot

# Use OpenCode CLI
skill-seekers enhance output/react/ --agent opencode

# Custom agent with file input
skill-seekers enhance output/react/ --agent custom --agent-cmd "my-agent --prompt {prompt_file}"

# Custom agent with stdin input
skill-seekers enhance output/react/ --agent custom --agent-cmd "my-agent --enhance"

Environment Variables (CI/CD):

# Set default agent
export SKILL_SEEKER_AGENT=codex
skill-seekers enhance output/react/

# Set custom command template
export SKILL_SEEKER_AGENT=custom
export SKILL_SEEKER_AGENT_CMD="my-agent {prompt_file}"
skill-seekers enhance output/react/

Agent Command Templates

File-based agents (use {prompt_file} placeholder):

--agent-cmd "my-agent --input {prompt_file}"
--agent-cmd "my-agent < {prompt_file}"

Stdin-based agents (no placeholder):

--agent-cmd "my-agent --enhance"

Security

Custom commands are validated for security:

• ✅ Blocks dangerous shell characters: ;, &, |, $, `, \n, \r
• ✅ Validates executable exists in PATH
• ✅ Safe parsing with shlex.split()

Example rejection:

# This will fail with security error:
skill-seekers enhance . --agent custom --agent-cmd "evil; rm -rf /"
# Error: Custom command contains dangerous shell characters

Agent Aliases

Agent names are normalized with smart alias support:

# All resolve to "claude"
--agent claude
--agent claude-code
--agent claude_code
--agent CLAUDE

# All resolve to "codex"
--agent codex
--agent codex-cli

# All resolve to "copilot"
--agent copilot
--agent copilot-cli

Mode Comparison

Usage Examples

1. Headless Mode (Default)

When to use: CI/CD pipelines, automation scripts, when you want to wait for completion

# Basic usage - waits until done (uses Claude Code by default)
skill-seekers enhance output/react/

# Use different agent
skill-seekers enhance output/react/ --agent codex
skill-seekers enhance output/react/ --agent copilot

# With custom timeout
skill-seekers enhance output/react/ --timeout 1200

# Force mode - no confirmations
skill-seekers enhance output/react/ --force

# Combine agent + force mode
skill-seekers enhance output/react/ --agent codex --force

Behavior:

• Runs selected coding agent CLI directly (default: Claude Code)
• BLOCKS until enhancement completes
• Shows progress output
• Returns exit code: 0 = success, 1 = failure

2. Background Mode

When to use: When you want to continue working while enhancement runs

# Start enhancement in background (default agent: Claude Code)
skill-seekers enhance output/react/ --background

# Start with different agent
skill-seekers enhance output/react/ --background --agent codex
skill-seekers enhance output/react/ --background --agent copilot

# Returns immediately with status file created
# ✅ Background enhancement started!
# 📊 Status file: output/react/.enhancement_status.json

Behavior:

• Starts background thread
• Returns immediately
• Creates .enhancement_status.json for monitoring
• Thread continues even if you close terminal

Monitor progress:

# Check status once
skill-seekers enhance-status output/react/

# Watch in real-time
skill-seekers enhance-status output/react/ --watch

# JSON output (for scripts)
skill-seekers enhance-status output/react/ --json

3. Daemon Mode

When to use: Long-running tasks that must survive parent process exit

# Start as daemon (fully detached)
skill-seekers enhance output/react/ --daemon

# Process continues even if you:
# - Close the terminal
# - Logout
# - SSH session ends

Behavior:

• Creates fully detached process using nohup
• Writes to .enhancement_daemon.log
• Creates status file with PID
• Survives parent process exit

Monitor daemon:

# Check status
skill-seekers enhance-status output/react/

# View logs
tail -f output/react/.enhancement_daemon.log

# Check if process is running
cat output/react/.enhancement_status.json
# Look for "pid" field

4. Terminal Mode (Interactive)

When to use: When you want to see Claude Code in action

# Open in new terminal window
skill-seekers enhance output/react/ --interactive-enhancement

Behavior:

• Opens new terminal window (macOS)
• Runs Claude Code visually
• Terminal auto-closes when done
• Useful for debugging

Force Mode (Default ON)

What it does: Skips ALL confirmations, auto-answers "yes" to everything

Default behavior: Force mode is ON by default for maximum automation

# Force mode is ON by default (no flag needed)
skill-seekers enhance output/react/

# Disable force mode if you want confirmations
skill-seekers enhance output/react/ --no-force

Use cases:

• ✅ CI/CD automation (default ON)
• ✅ Batch processing multiple skills (default ON)
• ✅ Unattended execution (default ON)
• ⚠️ Use --no-force if you need manual confirmation prompts

Status File Format

When using --background or --daemon, a status file is created:

Location: {skill_directory}/.enhancement_status.json

Format:

{
  "status": "running",
  "message": "Running Claude Code enhancement...",
  "progress": 0.5,
  "timestamp": "2026-01-03T12:34:56.789012",
  "skill_dir": "/path/to/output/react",
  "error": null,
  "pid": 12345
}

Status values:

• pending - Task queued, not started yet
• running - Currently executing
• completed - Finished successfully
• failed - Error occurred (see error field)

Monitoring Background Tasks

Check Status Command

# One-time check
skill-seekers enhance-status output/react/

# Output:
# ============================================================
# ENHANCEMENT STATUS: RUNNING
# ============================================================
#
# 🔄 Status: RUNNING
#    Message: Running Claude Code enhancement...
#    Progress: [██████████░░░░░░░░░░] 50%
#    PID: 12345
#    Timestamp: 2026-01-03T12:34:56.789012

Watch Mode (Real-time)

# Watch status updates every 2 seconds
skill-seekers enhance-status output/react/ --watch

# Custom interval
skill-seekers enhance-status output/react/ --watch --interval 5

JSON Output (For Scripts)

# Get raw JSON
skill-seekers enhance-status output/react/ --json

# Use in scripts
STATUS=$(skill-seekers enhance-status output/react/ --json | jq -r '.status')
if [ "$STATUS" = "completed" ]; then
    echo "Enhancement complete!"
fi

Advanced Workflows

Batch Enhancement (Multiple Skills)

#!/bin/bash
# Enhance multiple skills in parallel
# Note: Force mode is ON by default (no --force flag needed)

skills=("react" "vue" "django" "fastapi")

for skill in "${skills[@]}"; do
    echo "Starting enhancement: $skill"
    skill-seekers enhance output/$skill/ --background
done

echo "All enhancements started in background!"

# Monitor all
for skill in "${skills[@]}"; do
    skill-seekers enhance-status output/$skill/
done

CI/CD Integration

# GitHub Actions example
- name: Enhance skill
  run: |
    # Headless mode (blocks until done, force is ON by default)
    skill-seekers enhance output/react/ --timeout 1200

    # Check if enhancement succeeded
    if [ $? -eq 0 ]; then
      echo "✅ Enhancement successful"
    else
      echo "❌ Enhancement failed"
      exit 1
    fi

Long-running Daemon

# Start daemon for large skill
skill-seekers enhance output/godot-large/ --daemon --timeout 3600

# Logout and come back later
# ... (hours later) ...

# Check if it completed
skill-seekers enhance-status output/godot-large/

Timeout Configuration

Default timeout: 600 seconds (10 minutes)

Adjust based on skill size:

# Small skills (< 100 pages)
skill-seekers enhance output/hono/ --timeout 300

# Medium skills (100-1000 pages)
skill-seekers enhance output/react/ --timeout 600

# Large skills (1000+ pages)
skill-seekers enhance output/godot/ --timeout 1200

# Extra large (with PDF/GitHub sources)
skill-seekers enhance output/django-unified/ --timeout 1800

What happens on timeout:

• Headless: Returns error immediately
• Background: Status marked as failed with timeout error
• Daemon: Same as background
• Terminal: Claude Code keeps running (user can see it)

Error Handling

Status Check Exit Codes

skill-seekers enhance-status output/react/
echo $?

# Exit codes:
# 0 = completed successfully
# 1 = failed (error occurred)
# 2 = no status file found (not started or cleaned up)

Common Errors

"claude command not found":

# Install Claude Code CLI
# See: https://docs.claude.com/claude-code

"Enhancement timed out":

# Increase timeout
skill-seekers enhance output/react/ --timeout 1200

"SKILL.md was not updated":

# Check if references exist
ls output/react/references/

# Try terminal mode to see what's happening
skill-seekers enhance output/react/ --interactive-enhancement

File Artifacts

Enhancement creates these files:

output/react/
├── SKILL.md                    # Enhanced file
├── SKILL.md.backup             # Original backup
├── .enhancement_status.json    # Status (background/daemon only)
├── .enhancement_daemon.log     # Logs (daemon only)
└── .enhancement_daemon.py      # Daemon script (daemon only)

Cleanup:

# Remove status files after completion
rm output/react/.enhancement_status.json
rm output/react/.enhancement_daemon.log
rm output/react/.enhancement_daemon.py

API Mode Configuration

When using API mode for AI enhancement (instead of LOCAL mode), you can configure any Claude-compatible endpoint:

# Required for API mode
export ANTHROPIC_API_KEY=sk-ant-...

# Optional: Use custom Claude-compatible endpoint (e.g., GLM-4.7)
export ANTHROPIC_BASE_URL=https://your-endpoint.com/v1

Note: You can use any Claude-compatible API by setting ANTHROPIC_BASE_URL. This includes:

• GLM-4.7 (智谱 AI)
• Other Claude-compatible services

All AI enhancement features respect these settings:

• enhance_skill.py - API mode SKILL.md enhancement
• ai_enhancer.py - C3.1/C3.2 pattern and test example enhancement
• guide_enhancer.py - C3.3 guide enhancement
• config_enhancer.py - C3.4 configuration enhancement
• adaptors/claude.py - Claude platform adaptor enhancement

Comparison with API Mode

Best Practices

1. Use headless by default - Simple and reliable
2. Use background for scripts - When you need to do other work
3. Use daemon for large tasks - When task might take hours
4. Use force in CI/CD - Avoid hanging on confirmations
5. Always set timeout - Prevent infinite waits
6. Monitor background tasks - Use enhance-status to check progress

Troubleshooting

Background task not progressing

# Check status
skill-seekers enhance-status output/react/ --json

# If stuck, check process
ps aux | grep claude

# Kill if needed
kill -9 <PID>

Daemon not starting

# Check logs
cat output/react/.enhancement_daemon.log

# Check status file
cat output/react/.enhancement_status.json

# Try without force mode
skill-seekers enhance output/react/ --daemon

Status file shows error

# Read error details
skill-seekers enhance-status output/react/ --json | jq -r '.error'

# Common fixes:
# 1. Increase timeout
# 2. Check references exist
# 3. Try terminal mode to debug

See Also

• ENHANCEMENT.md - Main enhancement guide
• UPLOAD_GUIDE.md - Upload instructions
• README.md - Main documentation