Skip to content
Skills Library
AI & agents · Building & coding

background-agents

/background-agents

Configure and run background agents with reusable profiles for agent engines, model providers and execution backends. Use when delegating background work, reusing agents across sessions, or adding an engine or backend. Trigger.dev and Cloudflare Workflows are available backends; the approach is extensible. Includes optional source-backed evidence review.

Licence
MIT
Last repository change
10.11.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
16
Scripts
6
HTML comments
0
URLs in SKILL.md
3
Deprecation

No signals detected. Repository changed on 10.11.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What to check before installing
  • 6 scripts in this package. Review them before installing, as Claude may execute them.

Scripts: assets/cloudflare-worker/src/index.ts, assets/cloudflare-worker/src/pi-agent.ts, scripts/cloudflare_workflows.py, scripts/profiles.py, scripts/test_cloudflare_workflows.py, scripts/test_profiles.py

What it does and when to use it

Configure and run background agents with reusable profiles for agent engines, model providers and execution backends. Use when delegating background work, reusing agents across sessions, or adding an engine or backend. Trigger.dev and Cloudflare Workflows are available backends; the approach is extensible. Includes optional source-backed evidence review.

Original author description

Configure and run background agents with reusable profiles for agent engines, model providers and execution backends. Use when delegating background work, reusing agents across sessions, or adding an engine or backend. Trigger.dev and Cloudflare Workflows are available backends; the approach is extensible. Includes optional source-backed evidence review.

How it works

  1. Select configuration
  2. Confirm the deployed contract
  3. Execute and verify
  4. Handle results
  5. Credentials and portability
Original SKILL.md headings · 73 lines, 788 words
SKILL.md preview
---
name: background-agents
description: Configure and run background agents with reusable profiles for agent engines, model providers and execution backends. Use when delegating background work, reusing agents across sessions, or adding an engine or backend. Trigger.dev and Cloudflare Workflows are available backends; the approach is extensible. Includes optional source-backed evidence review.
---

# Background Agents

Run the requested work through a selected profile, verify the remote outcome, and return usable results with run references.

Keep four choices separate: **execution backend** (Trigger.dev by default), **agent engine** (for example Pi), **model provider**, and **model**. Changing one does not automatically change the others. Profiles select deployed tasks; they do not install a new engine or grant it tools.

## Select configuration

Use the configuration explicitly supplied by the user, otherwise `BACKGROUND_AGENT_PROFILES`, otherwise `agents.profiles.json` in the working project. Do not search unrelated projects or reuse remembered account/project identifiers.

Read [references/profiles.md](references/profiles.md) when creating, extending or resolving profiles. Copy [assets/profiles.example.json](assets/profiles.example.json) as a starting point; it contains environment references, not working deployment identifiers.

The standard-library helper lists and resolves profiles without executing jobs:

```sh
python3 scripts/profiles.py --config agents.profiles.json list
python3 scripts/profiles.py --config agents.profiles.json validate
python3 scripts/profiles.py --config agents.profiles.json resolve pi-openrouter
```

Run helper commands from this skill folder, or use the helper's resolved path and the project's configuration path. An explicit profile takes precedence over `defaultProfile`. Unset references, unknown profiles, disabled profiles and inheritance cycles stop resolution. An omitted backend resolves to Trigger.dev. An explicitly selected different backend must never silently fall back to Trigger.dev.

## Confirm the deployed contract

Inspect the selected backend's task metadata or implementation before execution:

- Match project, environment, task, expected input/output and available tools.
- Verify engine/provider/model when the profile specifies them. A profile's model label is an expectation, not a model override supported by every task.
- Check actual concurrency, duration and retry settings. Profile limits describe desired bounds; they do not reconfigure a deployed task by themselves.
- For Trigger.dev, **development runs use a local worker**; cloud execution requires a deployed production, staging or preview worker. Keep the selected environment explicit.
- Distinguish a fresh per-run session from durable conversation state. Do not promise continuity unless the task implements it.

If the task lacks a required capability, use an already deployed compatible profile or implement the missing capability within the user's scope. Do not ask a prompt-only agent to claim it searched, ran tools or updated records.

## Execute and verify

For Cloudflare Workers/Workflows, read [references/cloudflare.md](references/cloudflare.md). The optional adapter and Worker template support a prompt-only Pi core engine; Trigger.dev remains the default.

Prefer an available backend MCP tool when it supports the selected profile and required operation. For Trigger.dev, the CLI is a fallback:

```sh
npx trigger.dev@latest tasks trigger "$TASK_ID" \
  --project-ref "$PROJECT_REF" --env "$ENVIRONMENT" \
  --payload-file payload.json --idempotency-key "$REQUEST_ID" \
  --wait --timeout "$TIMEOUT_SECONDS"
```

Derive these values from the resolved profile and actual task contract. Include a branch/login profile when required. Check the installed CLI's help for current flags.

- Give each job a bounded payload and a stable request identity derived from its operation and canonical inputs. Reuse it when an outcome is uncertain; changed inputs need a new identity.
- Respect shared provider quotas as well as task concurrency. Moving work to another backend must not bypass a shared research allowance.
- Preserve receipts with profile, environment, task, request identity, run ID/status and result disposition. Keep private payloads and credentials out of general receipts.
- A submission or deployment is not a completed job. Inspect terminal status and output. After a timeout, reconcile the existing run before submitting another.
- For failures, fix a demonstrated cause before a bounded retry. Stop and report when repeated failures require a credential, capability or external change.
- Do not wrap Trigger.dev `wait.*`, `triggerAndWait` or `batchTriggerAndWait` in `Promise.all`.

## Handle results

Validate outputs against the task's actual schema and the user's acceptance criteria. For source review or enrichment, read [references/evidence-review.md](references/evidence-review.md) before dispatch and before import. Unknown, proposed, accepted and verified outcomes remain distinct.

Import only the intended validated results. Correct an error in an agent-generated proposal without rewriting unrelated records or changing review decisions. Report completed/failed/pending coverage, useful results, unresolved gaps and remote run links. Say whether the work used saved evidence or fresh external research.

## Credentials and portability

The shared skill and example profiles contain no credentials, account/project IDs, run references, private datasets or absolute machine paths. Runtime project configuration belongs outside the shared skill.

Credential **environment-variable names** may appear in profiles. Values belong in the selected backend's secret store. Never resolve credential references into a payload, command argument, profile output or receipt. Use existing authenticated connections and preserve dashboard-managed variables; do not overwrite them from an old local environment file.

Creating this skill does not authorize unrelated deployments, credential changes or data writes. Work within the current user's request; consult current official documentation before adding SDKs or changing deployment behavior. Trigger.dev SDK imports use `@trigger.dev/sdk`; exported tasks, built-in `fetch`, explicit task directories and finite durations are the supported starting points.

Official references: [Trigger.dev tasks](https://trigger.dev/docs/tasks/overview), [environments](https://trigger.dev/docs/deployment/overview), [environment variables](https://trigger.dev/docs/deploy-environment-variables).
Files in this package (16)
  • SKILL.md 6 KB
  • agents/openai.yaml 1 KB
  • assets/profiles.example.json 2 KB
  • assets/cloudflare-worker/.gitignore 1 KB
  • assets/cloudflare-worker/package.json 1 KB
  • assets/cloudflare-worker/tsconfig.json 1 KB
  • assets/cloudflare-worker/wrangler.jsonc 1 KB
  • assets/cloudflare-worker/src/index.ts 1 KB
  • assets/cloudflare-worker/src/pi-agent.ts 2 KB
  • references/cloudflare.md 4 KB
  • references/evidence-review.md 3 KB
  • references/profiles.md 4 KB
  • scripts/cloudflare_workflows.py 9 KB
  • scripts/profiles.py 8 KB
  • scripts/test_cloudflare_workflows.py 3 KB
  • scripts/test_profiles.py 4 KB

Versions

The database has no other skills named background-agents.

Database snapshot: 13.11.2026 · package version 57af71e5466a (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100background
    Use when the user wants to see, inspect, cancel, or prune background agents fired during prior chain runs. Read/manage `.hyperflow/background/registry.json` and the per-agent output buffers at `.hyperflow/background/<id>.md`. Standalone — never auto-invoked. Trigger with…
  • 100agenticx-agent-builder
    Guide for creating and configuring AgenticX agents with roles, goals, tools, LLM providers, and execution strategies. Use when the user wants to create agents, assign tools to agents, configure LLM backends, set up agent execution, or build multi-agent systems.
  • 100agenticx-agent-builder
    Guide for creating and configuring AgenticX agents with roles, goals, tools, LLM providers, and execution strategies. Use when the user wants to create agents, assign tools to agents, configure LLM backends, set up agent execution, or build multi-agent systems.
  • 100background-prompt
    Execute a task in the background with a prompt through the core engine LLM provider and return plain text output. Use when the user wants to run a prompt as a background task via the Agent CLI.
  • 90jor-writing-for-agents
    Create, edit, review, or consolidate agent skills and instruction files such as AGENTS.md and CLAUDE.md. Use when the requested output is reusable guidance for an agent.
  • 100spawn-backends
    Configure how teammate agents run including in-process, tmux, and iTerm2 backends. Use when choosing a display mode, setting up split panes, troubleshooting backend issues, or configuring teammateMode.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.