Skip to content

BuilderIO/agent-native / .agents/skills/recurring-jobs

recurring-jobs

Verified

The legacy manage-jobs compatibility surface, job files under jobs/, and cron scheduler internals. Use when maintaining manage-jobs integrations or debugging the scheduler.

Recurring Jobs (Compatibility)

Rule

Recurring Jobs is the legacy name and API for scheduled automations. Jobs live as resource files under jobs/ with YAML frontmatter for scheduling metadata.

Read automations for the product model, trigger types, frontmatter fields, organization scope, and when to prefer manage-automations over manage-jobs. This skill covers only what is specific to the legacy scheduled path: the manage-jobs tool and the cron scheduler behind it.

How It Works

  1. User asks for something recurring via the agent chat
  2. Agent uses manage-jobs tool (action: "create") to write a job file at jobs/<name>.md
  3. A scheduler tick finds due jobs about once a minute. Long-running servers fire it in-process; Netlify, Vercel, and Cloudflare fire it from a platform trigger the build emits; AWS Lambda has no trigger, so jobs never fire there
  4. Due jobs enter the shared background-automation runner, on the same execution lifecycle as event automations
  5. Job results are saved as chat threads

Connected MCPs in background jobs

When a job needs a connected remote MCP, bind the exact advertised mcp__<server>__<tool> names through mcpTools. The scheduler passes that definition to the shared runner, which resolves only that allowlist under the persisted creator/org request context and never stores or exposes OAuth tokens, URLs, or arbitrary proxy targets.

Use an app-owned bounded import/upsert action for writes. Keep provider-specific response mapping, provenance, deduplication, and write policy in the app rather than in core. For example, a job can read meeting notes from any connected MCP and pass normalized action items to an app's idempotent import action.

Job Tool (built in)

ToolActionPurpose
manage-jobscreateCreate a recurring job (name, cron schedule, instructions); fails if the name exists
manage-jobslistList all jobs and their status
manage-jobsupdateUpdate schedule, instructions, or toggle enabled

Job files an app owns

create never replaces an existing job file, so a name that collides with an app's file (Factory's factories/<id>/<name>) is refused instead of reset. An app that stores its own settings in a job's frontmatter marks the file with triggerType, which makes list, update, and delete skip it and sends the caller to manage-automations. Edit those files only through the owning app's actions, and patch fields in place; rebuilding a file from the fields the writer knows drops the rest while the job keeps running.

Any write to a jobs/ file that removes a frontmatter field other than run bookkeeping is recorded as a job-fields-dropped audit event (org admins read it with list-audit-events and action: "job-fields-dropped"). Its input names the writer, the dropped fields, and the agent thread and run that made it.

UI Surface

/agent#jobs is the stable compatibility URL for the Agent page's Automations tab, which lists legacy scheduled jobs alongside trigger-aware automations and is backed by the scoped list/manage actions. Direct users there instead of describing job files when they just want to view or toggle scheduled work.

Key Files

FilePurpose
packages/core/src/jobs/cron.tsCron parsing (nextOccurrence, isValidCron, describeCron)
packages/core/src/jobs/scheduler.tsJob execution engine (processRecurringJobs)
packages/core/src/jobs/tools.tsAgent tool (manage-jobs with create/list/update actions)
packages/core/src/client/agent-page/AgentJobsTab, the /agent#jobs surface

Related Skills

  • automations — The primary Scheduled/Event product model
  • actions — How tools and actions work
  • delegate-to-agent — How jobs invoke the agent loop
slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack."Stars: 196kUpdated Claude CodeCodexVerifiedInstall
ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read.Stars: 193kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 193kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt.Stars: 193kUpdated Claude CodeCodexVerifiedInstall