How do I read goal status and budget usage?

Call await goal.get() from the Python REPL. It returns the current goal as a dict with goal, remaining_tokens, and completion_budget_report. The goal dict carries objective, status, token_budget, tokens_used, time_used_seconds, and timestamps.

When should I start a goal?

Only when the user or system/developer instructions explicitly ask for a persistent long-running goal. Do not infer goals from ordinary tasks. Call await goal.create(objective), and pass token_budget only when an explicit token budget is requested.

Goal

SkillAI & models

The goal skill is a kernel-side interface that lets an agent manage a persistent thread goal from the Python REPL. It reads goal status and token budget usage, starts a new goal when the user explicitly asks for one, and marks the active goal complete once its objective is fully achieved.

Connect your AI Use it in a pipeline

Then ask your AI: use the Goal skill

Details

Instructions available. Your AI can read the instructions. Execution depends on the setup they require.

Account requirements not reviewed. Check the skill instructions before use; Ahel provides instructions and does not run this skill.

No other account needed.

Have a Python REPL available in the agent environment where the goal skill is installed.

What your AI can do with it

Read the current goal with goal.get(), including objective, status, and token budget
Check remaining tokens and the completion budget report
Start a new active goal with goal.create(objective)
Pass a token_budget to goal.create only when explicitly requested
Mark the active goal achieved with goal.complete()
Report final usage from the completion budget report to the user

Getting started

Have a Python REPL available in the agent environment where the goal skill is installed.
Call await goal.get() to read the current goal status and budget usage.
When the user explicitly asks for a persistent long-running goal, call await goal.create(objective), adding token_budget only if an explicit budget is requested.
Once the objective is fully achieved and no required work remains, call await goal.complete().
If the completion result includes a completion_budget_report, report that final usage to the user.

What this skill tells your AI

The instructions your AI receives, as published by primeintellect-ai/prime-agent in skills/goal/SKILL.md and read by Ahel’s review.

The thread goal is a persistent objective the harness keeps re-prompting you to pursue across turns until it is complete. Goal state (status, token budget, usage accounting) lives in the host; this skill is the kernel-side interface to it. Call it directly from the Python REPL:

await goal.get()
await goal.create("ship the release notes")
# Only pass token_budget when the user explicitly asks for one:
# await goal.create("ship the release notes", token_budget=200000)
await goal.complete()

API

await goal.get() — current goal as a dict: goal (or None when no goal is set), remaining_tokens, and completion_budget_report. The goal dict carries objective, status, token_budget, tokens_used, time_used_seconds, and timestamps.
await goal.create(objective, token_budget=None) — start a new active goal. Fails while a goal is still pending (active, paused, or budget-limited); a completed or errored goal is replaced by the new one. Only create a goal when the user or system/developer instructions explicitly ask for a persistent long-running goal; do not infer goals from ordinary tasks. Set token_budget only when an explicit token budget is requested.
await goal.complete() — mark the existing goal achieved. Use only when the objective has actually been achieved and no required work remains; do not call it merely because the budget is nearly exhausted or because you are stopping work. When the result includes a completion_budget_report, report that final usage to the user.

Rules

Goal status transitions other than completion (pause, resume, clear, budget-limiting) are controlled by the user and the host; there is no API for them here.
When an active goal is actually complete, call await goal.complete(); do not merely say it is done — the harness keeps continuing the goal until the completion call arrives.

Signals

GitHub stars: 22k
Forks: 2k
Last commit: Oct 2026

Questions

How do I read goal status and budget usage?: Call await goal.get() from the Python REPL. It returns the current goal as a dict with goal, remaining_tokens, and completion_budget_report. The goal dict carries objective, status, token_budget, tokens_used, time_used_seconds, and timestamps.
When should I start a goal?: Only when the user or system/developer instructions explicitly ask for a persistent long-running goal. Do not infer goals from ordinary tasks. Call await goal.create(objective), and pass token_budget only when an explicit token budget is requested.

Advanced

Item type: skill
Key: goal-primeintellect-ai
Source: github.com/primeintellect-ai/prime-agent

github.com/primeintellect-ai/prime-agent