windows-bg-svc-skill

OpenCode agent skill for running long-lived background services on Windows PowerShell without blocking the agent.

Install

npx skills add <your-username>/windows-bg-svc-skill -a opencode

Or from npm:

npx skills add windows-bg-svc-skill -a opencode

What it does

When you ask opencode to start a server (e.g. npx http-server, npm run dev, python -m http.server, dotnet run) on Windows, this skill prevents the agent from using blocking approaches that would hang opencode.

The skill provides a Start-BackgroundService PowerShell helper that:

• Starts the process without blocking the agent
• Captures all output to a log file
• Creates a fully detached OS process (survives across commands)
• Can be stopped cleanly (kills the entire process tree)

Structure

skills/
└── windows-background-service/
    ├── SKILL.md
    └── scripts/
        └── Start-BackgroundService.ps1

Usage (for an agent)

The skill is loaded automatically by opencode. The agent will:

# Dot-source the helper
. <path-to-skill>\scripts\Start-BackgroundService.ps1

# Start a service
$svc = Start-BackgroundService -Command "npx http-server -p 8080"
# Output: "Background service started (PID: 12345, Log: C:\Users\...\bg-svc-xxx.log)"

# Read logs
Read-BackgroundServiceLog -Service $svc -Tail 10

# Stop (keeps logs)
Stop-BackgroundService -Service $svc

# Stop and clean logs
Stop-BackgroundService -Service $svc -CleanLog