Skip to content

README_EN.md

Latest commit

 

History

History
260 lines (183 loc) · 5.67 KB

README_EN.md

File metadata and controls

260 lines (183 loc) · 5.67 KB

GoSkill

Turn a one-shot Skill into a goal-driven execution loop that keeps going until success criteria are met or time runs out.

Python License Tests

English | 简体中文

Not a magic autonomous agent platform — a more honest execution wrapper for long-running tasks with explicit success criteria.

Why GoSkill?

A lot of tasks do not fail because they are impossible. They fail because:

  • they stop after one attempt
  • the completion criteria are vague
  • long-running work has no built-in validation loop
  • the final output says “done” but nobody knows whether it actually meets the bar

GoSkill is meant to address that gap:

turn a one-shot task into a goal-driven execution pattern with retries, checks, and a stopping condition.

It is better thought of as a goal-driven execution helper, not an all-powerful autonomous framework.

In one sentence

If a normal Skill runs once and returns, GoSkill is the pattern where you:

  • define the goal
  • define the success criteria
  • keep trying / checking / retrying
  • stop only when the goal is met or time expires

🆚 What is it good for?

Scenario Normal function / Skill GoSkill
One-shot short tasks ✅ —
Long-running iterative work — ✅
Explicit acceptance criteria 🟡 ✅
Built-in status tracking 🟡 ✅
Multi-attempt execution loops 🟡 ✅

The value of GoSkill is not “more intelligence”, but “better execution discipline around goals”.

🚀 Quick start

Install

pip install -e .

Decorator style

from goskill import goskill

@goskill(
    goal="Migrate an Android project to HarmonyOS",
    criteria={
        "compile": "0 errors",
        "test": "100% pass",
        "performance": ">= 90%"
    },
    max_hours=48
)
def migrate():
    return {"done": True}

migrate()

Class style

from goskill import GoSkill

skill = GoSkill(
    goal="Analyze 1000 financial reports",
    criteria={
        "coverage": ">= 90%",
        "report": "complete"
    },
    max_hours=24,
    max_attempts=20,
    verbose=False,  # optional: suppress runtime logs
)

result = skill.run(lambda: {"coverage": 95, "report": "complete"})
print(result)
print(skill.status)

structured = skill.run_with_result(lambda: {"coverage": 95, "report": "complete"})
print(structured)

🎬 Minimal runnable example

A tiny demo is included in the repo:

python examples/basic_usage.py

It shows:

  • how to define a goal
  • how to define criteria
  • how to run and inspect status

Core ideas

The library now offers two output styles:

  • run() returns the raw task result
  • run_with_result() returns a structured result object with success/status/attempts/report

1) Goal-driven

Instead of only passing a function, you describe the task as:

  • goal: what should be achieved
  • criteria: what counts as success
  • max_hours: how long it is allowed to keep trying
  • max_attempts: how many attempts are allowed (optional)

2) Persistent attempts

If the criteria are not met, GoSkill does not assume one execution is enough. It keeps going until:

  • success
  • timeout
  • or manual stop

3) Trackable status

Built-in status lets you inspect:

  • current goal
  • attempt count
  • elapsed runtime
  • max runtime
  • terminal reason (terminal_status)
  • latest criteria check
  • latest execution result

How it works

Define goal + success criteria
        ↓
Run task function
        ↓
Check if result meets criteria
        ↓
Success → return result
Not enough → wait and retry
        ↓
Repeat until success or timeout

Good fit / bad fit

Good fit

  • large refactors
  • long-running analysis tasks
  • automation with explicit acceptance criteria
  • research-style iterative tasks
  • workflows that need execution + validation + retry in one wrapper

Bad fit

  • simple one-shot Q&A
  • tiny synchronous functions
  • tasks with no meaningful acceptance criteria
  • production-grade distributed orchestration systems

Project boundaries

GoSkill currently targets a single-process, lightweight goal-driven execution loop.

It does not try to provide:

  • distributed orchestration
  • multi-node scheduling
  • advanced persistence recovery
  • enterprise queueing systems

That boundary makes the project more trustworthy, not less.

Current project status

Right now GoSkill is best understood as:

  • an execution pattern prototype
  • a lightweight Python helper
  • an experimental wrapper for OpenClaw / agent workflows

It is not yet a full long-running autonomous agent platform.

That clarity is a feature, not a weakness. Better alignment = higher trust.

Development

make install-dev
make test
make build
make version

Related docs

License

Apache-2.0

If you're building long-running, goal-driven workflows, give it a Star ⭐