Agent skill

Promise Theory

by magnus919 in magnus919/agent-skills

Teach promise vocabulary, fundamentals, and coordination diagnosis for promise-based systems.

MITAuto-check passed

Install Promise Theory

skills CLI
$ npx skills add magnus919/agent-skills --skill promise-theory -a claude-code

Project install by default; add -g for ~/.claude/skills/.

GitHub CLI
$ gh skill install magnus919/agent-skills promise-theory --agent claude-code

Project scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).

Manual copy
$ git clone --depth 1 https://github.com/magnus919/agent-skills.git skills-src && mkdir -p .claude/skills && cp -r skills-src/promise-theory .claude/skills/promise-theory && rm -rf skills-src

Use ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.

Claude Code skills documentation · loads skills from .claude/skills/

Facts

Skill name
promise-theory
GitHub stars
115
Token cost
~2.7k tokens
SKILL.md length
1,290 words
Files
17 (incl. scripts, references)
Skills in repo
131
Repo updated
First seen
Licence
MIT

At a glance

Teach promise vocabulary, fundamentals, and coordination diagnosis for promise-based systems.

  • Works in 4 steps: Draft a promise manifest. Copy… → Lint it. Run python3… → Add --json for machine-readable output.… → …
  • Semantic Spacetime models
  • SKILL.md covers Core model, When to use, When not to use and Load By Need, plus 7 more sections
  • Runs Python scripts from its folder; calls python3

What it does

Promise Theory is an agent skill from magnus919/agent-skills. Teach promise vocabulary, fundamentals, and coordination diagnosis for promise-based systems. Do not use this skill for Semantic Spacetime models or SST CLI tooling; use semantic-spacetime for those model and tool workflows.

Its SKILL.md is about 2.7k tokens, which your agent loads only when the skill is triggered. The skill folder holds 21 other files, including scripts and reference files (for example `README.md`, `evals/evals.json` and `references/agent-coordination.md`).

The repository describes itself as: Curated collection of AI agent skills for Hermes and other agent frameworks. The licence is MIT.

When your agent uses it

  • Semantic Spacetime models
  • SST CLI tooling
  • Use semantic-spacetime for those model and tool workflows

Example prompts

  • “/promise-theory”

Requirements

  • Python 3

Workflow steps

4 steps, taken from the first numbered list in SKILL.md.

  1. Draft a promise manifest. Copy templates/promise-manifest.yaml.tmpl to a working file (for example promise-manifest.yaml) and fill the…
  2. Lint it. Run python3 scripts/promise-contract.py lint promise-manifest.yaml. Exit 0 with full expectation coverage means the manifest is…
  3. Add --json for machine-readable output. Run python3 scripts/promise-contract.py lint promise-manifest.yaml --json to get a single JSON…
  4. Add --dry-run to confirm no writes. Run python3 scripts/promise-contract.py lint promise-manifest.yaml --dry-run to repeat the same check…

What it can do on your machine

Read from SKILL.md and the folder at commit 22b4723. It shows what the files ask for, not the result of running them.

  • Tool permissions

    Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.

    From allowed-tools in the SKILL.md frontmatter.

  • Runs code

    Ships 1 file in scripts/ (Python, from the files we listed), which the agent can run.

    Shell commands in SKILL.md call:

    • python3

    From the folder's file list and the shell code blocks in SKILL.md.

  • Network

    No URLs in SKILL.md.

    From URLs in SKILL.md, links to its own repository left out.

  • Credentials

    Names no API keys, tokens, secrets or passwords.

    From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

Promise Theory loads about 2.7k tokens when it runs, and up to ~51k if it reads all its reference files. Until then it costs about 60 tokens; SKILL.md has 1,290 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it
~60
When it runs · the whole SKILL.md, loaded when a task matches
~2.7k
With references · SKILL.md plus every file in references/, read only if the agent opens them
~51k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Auto-check passed

The automated check found no risky patterns in SKILL.md.

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); the scripts in this folder are not scanned.

SKILL.md

The full file from magnus919/agent-skills at commit 22b4723, republished under its MIT licence (© magnus919). 1,290 words, ~2,651 tokens.

Download SKILL.mdSave it as .claude/skills/promise-theory/SKILL.md (or your agent's skills folder). This skill also uses 16 other files; get the full folder from GitHub.
name
promise-theory
description
Teach promise vocabulary, fundamentals, and coordination diagnosis for promise-based systems. Do not use this skill for Semantic Spacetime models or SST CLI tooling; use `semantic-spacetime` for those model and tool workflows.
license
MIT

Promise Theory

Promise theory (Mark Burgess; formalized with Jan Bergstra) is a method of analysis for systems of autonomous agents — humans, LLM agents, APIs, and deterministic automation. It supplies the vocabulary for designing and diagnosing delegation: promises, acceptances, assessments, breaches, and renegotiation. This skill is a thin router; load the dense material only when a row in Load By Need matches your task.

Core model

A promise is an autonomous declaration of intended, but as yet unverified, behaviour from a promiser to a promisee (body: label Λ, type τ, constraint χ). Agents are autonomous: no agent can promise another's behaviour. Coordination emerges from voluntary cooperation — an offer plus an acceptance (a counter-promise) — never from imposed obligation. Obligations are derived, non-autonomous impositions (imposition + penalty). Agents keep promises via an evaluation loop: observe → assess → act, converging on the promised state. The Downstream Principle: the most downstream party in a promise chain carries the greatest causal responsibility for the outcome.

When to use

Load this skill when any of these triggers matches:

  • Modeling delegation between humans and agents — decide who may promise what to whom, and who accepts, in a human + AI workforce.
  • Designing capability manifests or agent contracts — declare capabilities and intent with acceptance criteria, verification, and withdrawal semantics.
  • Diagnosing coordination failures — explain unkept promises, refused acceptances, or missing assessments in multi-agent work.
  • Calibrating trust and verification — decide how much to verify an agent, at what rate, and at what cost.
  • Designing self-healing or convergent infrastructure — evaluation loops that observe, assess, and act toward a desired state.
  • Converting obligation-based designs to promise-based ones — replace push commands and mandates with voluntary offers and acceptance.

When not to use

  • When enforceable centralized control is guaranteed — if you can command and verify compliance directly, promise theory's machinery is overhead, not insight.
  • For simple single-agent prompting — one model and one prompt, with no delegation graph to model, needs no promise vocabulary.
  • For imperative push-based orchestration scripts that need no consent modeling — a cron job or CI pipeline that runs without acceptance semantics is not a promise system.
  • For legal contracts — promise theory is not contract law; it models voluntary intent and assessment, not enforceable legal instruments. Draft real contracts with legal counsel.
  • When the user needs a specific tool manual — route to the tool's own skill (for example, cli-builder for CLI conventions) instead of framing the tool with promise theory.

Load By Need

NeedLoad
Re-derive a definition or the formal model (promise, imposition, obligation, bindings, trust, Downstream Principle)references/foundations.md
Learn from CFEngine, IaC, or distributed-systems practice before designing convergent infrastructurereferences/applications-infrastructure.md
Design coordination between specific humans and agents (manifests, acceptance handshakes, oversight, authority)references/agent-coordination.md
Apply a named pattern — promise manifest, acceptance handshake, agent contract, evaluation loop, breach→renegotiation, redundancy, trust calibrationreferences/patterns.md
Decide how much to verify an agent, set a starting trust level, or wire assessment into evals and observabilityreferences/trust-and-verification.md
Diagnose a coordination failure, run the breach taxonomy, or check the theory's limitationsreferences/diagnosis-and-debugging.md
Hit an unfamiliar term while applying this skillreferences/glossary.md

Quick Start

Run these commands from the skill directory (promise-theory/); python3 scripts/promise-contract.py --help lists every command and flag.

  1. Draft a promise manifest. Copy templates/promise-manifest.yaml.tmpl to a working file (for example promise-manifest.yaml) and fill the placeholders: agent ids and roles, at least one promise per agent (body, type, target), and at least one expectations entry whose about references a declared promise id.
  2. Lint it. Run python3 scripts/promise-contract.py lint promise-manifest.yaml. Exit 0 with full expectation coverage means the manifest is valid; exit 1 names the violations to fix (coverage gaps, dangling acceptances, invalid enums) or reports a malformed file as a parse error — never a traceback. Re-run after each fix until clean.
  3. Add --json for machine-readable output. Run python3 scripts/promise-contract.py lint promise-manifest.yaml --json to get a single JSON object on stdout (valid, errors, warnings, coverage, bindings) and nothing else.
  4. Add --dry-run to confirm no writes. Run python3 scripts/promise-contract.py lint promise-manifest.yaml --dry-run to repeat the same check; lint is read-only, so nothing is written or modified.

Available Scripts

This skill bundles one script; there are no others to discover. Both commands are read-only (--dry-run is accepted everywhere as a no-op guard).

ScriptPurposeInvocation
scripts/promise-contract.pyValidates and renders promise-theory manifest contracts (restricted-YAML or JSON). lint checks a promise manifest against the promise-manifest v1 schema (exit 0 = valid with full expectation coverage; exit 1 = named lint errors or coverage gaps; exit 2 = usage/IO errors) and render prints a promise-graph summary of agents, promises, bindings, and uncovered expectations. Run lint after drafting or every edit of a manifest until it exits clean, and render when you need a human- or machine-readable view of the coordination model you just built.python3 scripts/promise-contract.py lint promise-manifest.yaml

Append --json for machine-readable output (a single JSON object on stdout); render --json gives the same treatment to the graph summary.

Show full SKILL.md (488 more words)Show less
SkillRoute when...
agent-evals-and-observabilityYou need the assessment layer: evals, guardrails, and observability that verify promises are kept (also routed from references/trust-and-verification.md)
agent-councilYou need multi-agent debate as structured promise exchange and convergence (also routed from references/agent-coordination.md)
workflow-architectYou need to design a workflow as a chain of promises (also routed from references/patterns.md)
artifact-pyramidsYou need to structure promise-keeping evidence as summaries → analysis → evidence dossiers (also routed from references/trust-and-verification.md)
agent-skillsYou are authoring or editing an Agent Skills-format skill — the format this skill follows
cli-builderYou are building or refactoring the bundled CLI — scripts/promise-contract.py follows cli-builder conventions (non-interactive, --json, --dry-run)

Gotchas

  1. Provenance honesty. The direct "promise theory + AI agents" literature is thin and recent (Burgess, "Cooperation in Human and Machine Agents," arXiv:2604.10505, 2026). In the references, claims not verified against a primary source carry [UNVERIFIED], and the promise-theory → LLM-agent synthesis is labeled EXTRAPOLATION. Preserve those markers; they are what keep this skill honest.
  2. The theory is "semi-formal." The authors themselves use that term: there is a notation, definitions, lemmas, and rules, but no complete axiomatisation or model theory. The famous ≤50% (impositions) vs ≤100% (promises) claim is an informal heuristic, not a derived result. Use the formalism as a reasoning aid, not a proof system.
  3. Autonomy is a modeling postulate, not an ideology. It does not claim decentralization is morally right or always better; it is chosen because it forces complete documentation of intended behaviour and exposes failure modes.
  4. Promise-keeping must be stored as data. CFEngine's documented gap: it reported whether a promise was kept right now, but promise-keeping was never stored as data, so the evaluation loop was incomplete. In a hybrid workforce, record assessments as versioned data (a promise ledger) or trust cannot accumulate.
  5. Verification loads are an attention/energy budget. The rate at which you check (kinetic mistrust) is spent attention; Burgess & Dunbar model it as a bounded budget. Budget verification cost explicitly and start unknown agents at 50-50 rather than assuming trust or distrust.

Prerequisites

  • Python 3 with standard library only; promise-contract.py requires no third-party packages.
  • A manifest to lint or render: copy templates/promise-manifest.yaml.tmpl and fill the placeholders (see Quick Start) before running either command.

Limitations

  • The CLI validates declaration structure, enum values, expectation coverage, and dangling acceptances — it cannot judge whether the promised behaviour is sensible, achievable, or actually kept; assessments live in your promise ledger, not in this tool.
  • Promise theory is not contract law: nothing the script validates creates an enforceable legal instrument (see When not to use).
  • Lint is a static check at a point in time; it does not observe agents or verify runtime promise-keeping.

Exit Conditions

Stop when the delegation is modeled as a promise set, acceptances and assessments are recorded (or their absence explicitly deferred), and every breach has a renegotiation or escalation path. When diagnosing, stop after three non-converging passes and report the evidence instead of re-litigating the same promises.

© magnus919, MIT. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

SKILL.md and 16 other files (scripts, references) in promise-theory of magnus919/agent-skills.

  • SKILL.md
  • LICENSE
  • README.md
  • evals/evals.json
  • references/agent-coordination.md
  • references/applications-infrastructure.md
  • references/diagnosis-and-debugging.md
  • references/foundations.md
  • references/glossary.md
  • references/patterns.md
  • references/trust-and-verification.md
  • scripts/promise-contract.py
  • templates/agent-contract.md.tmpl
  • templates/promise-manifest.yaml.tmpl
  • templates/promise-review.md.tmpl
  • tests/test_promise_contract.py
  • … and 1 more

Open the folder on GitHubat commit 22b4723

Compare with similar skills

Promise Theory next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.

Promise Theory compared with similar skills
SkillStarsUsed inTokensAuto-checkLicenceRepo updated
Promise Theory this skillmagnus919/agent-skills115—~2.7kAutomated safety check: PassMIT
Teachcursor/plugins11k9 repos~1.4kAutomated safety check: PassNone
Agent Adaptive Coordinatorruvnet/ruflo74k2 repos~4kAutomated safety check: PassMIT
Agent Consensus Coordinatorruvnet/ruflo74k2 repos~3.2kAutomated safety check: PassMIT
Agent Hierarchical Coordinatorruvnet/ruflo74k2 repos~2.8kAutomated safety check: PassMIT
Agent Memory Coordinatorruvnet/ruflo74k2 repos~1.2kAutomated safety check: PassMIT

Similar skills

  • Teach

    cursor/plugins

    Official

    Explain a body of work plainly so a person actually understands it.

    11k GitHub starsUsed in 9 repos~1.4k tokens
    EducationAuto-check passed
  • Agent skill for adaptive-coordinator - invoke with $agent-adaptive-coordinator

    74k GitHub starsUsed in 2 repos~4k tokens
    Data & AnalyticsAuto-check passed
  • Agent skill for consensus-coordinator - invoke with $agent-consensus-coordinator

    74k GitHub starsUsed in 2 repos~3.2k tokens
    Agent WorkflowsAuto-check passed
  • Agent skill for hierarchical-coordinator - invoke with $agent-hierarchical-coordinator

    74k GitHub starsUsed in 2 repos~2.8k tokens
    Agent WorkflowsAuto-check passed
  • Agent skill for memory-coordinator - invoke with $agent-memory-coordinator

    74k GitHub starsUsed in 2 repos~1.2k tokens
    Agent WorkflowsAuto-check passed
  • Agent skill for mesh-coordinator - invoke with $agent-mesh-coordinator

    74k GitHub starsUsed in 2 repos~3.2k tokens
    Agent WorkflowsAuto-check passed

More from magnus919/agent-skills

All 131 skills in this repo
  • Artifact Pyramids

    magnus919/agent-skills

    Organize durable agent research outputs as summaries, analysis, and evidence dossiers.

    119 GitHub stars~2.7k tokensUpdated today
    Auto-check passed
  • Ascii City Engine

    magnus919/agent-skills

    Build portable, first-person colored ASCII city engines and small GIS-derived city packs.

    119 GitHub stars~1.1k tokensUpdated today
    Auto-check passed
  • Color Management

    magnus919/agent-skills

    Manage color workflows with ICC profiles, working spaces, gamut mapping, and color science.

    119 GitHub stars~2.6k tokensUpdated today
    Auto-check: notes
  • Data Scientist

    magnus919/agent-skills

    A skill your agent uses for PhD-level expertise in data science, statistics, and machine learning: rigorous statistical analysis, experimental design, causal inference, advanced modeling, research…

    119 GitHub stars~4.1k tokensUpdated today
    Auto-check passed
  • Docker Compose

    magnus919/agent-skills

    Use Docker Compose to define, run, debug, and harden multi-container applications.

    119 GitHub stars~2k tokensUpdated today
    Auto-check: notes
  • Fpga Development

    magnus919/agent-skills

    Design, review, simulate, and verify FPGA logic using explicit RTL contracts, clock and reset models, CDC analysis, timing constraints, and reproducible implementation evidence.

    119 GitHub stars~2.7k tokensUpdated today
    Auto-check passed

Questions about Promise Theory

What does Promise Theory do?

Teach promise vocabulary, fundamentals, and coordination diagnosis for promise-based systems. Promise Theory is an agent skill from magnus919/agent-skills. Teach promise vocabulary, fundamentals, and coordination diagnosis for promise-based systems.

When should I use Promise Theory?

Promise Theory fits situations like: semantic Spacetime models; SST CLI tooling; use semantic-spacetime for those model and tool workflows.

How do I install Promise Theory in Claude Code?

Run `npx skills add magnus919/agent-skills --skill promise-theory -a claude-code`. Or copy the skill folder (promise-theory in magnus919/agent-skills) into .claude/skills/promise-theory in your project. Claude Code loads it when a task matches its description.

How do I install Promise Theory in Codex?

Run `npx skills add magnus919/agent-skills --skill promise-theory -a codex`. Or copy the skill folder (promise-theory in magnus919/agent-skills) into .agents/skills/promise-theory in your project. Codex loads it when a task matches its description.

Can I use Promise Theory in Cursor, Gemini CLI or GitHub Copilot?

Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add magnus919/agent-skills --skill promise-theory -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/promise-theory, .gemini/skills/promise-theory, .github/skills/promise-theory and .opencode/skills/promise-theory in your project.

What does Promise Theory need to run?

Going by SKILL.md and its folder, Promise Theory needs Python for the scripts in its folder and the command-line tools its instructions call (python3). Our summary lists: Python 3.

Does Promise Theory access the network?

SKILL.md contains no URLs. Any network use would come from the scripts or tools the agent runs. This is read from the text; nothing was executed.

Is Promise Theory safe to install?

Our automated static check of SKILL.md found no risky patterns, such as piping downloads into a shell, reading credential files or hidden Unicode. It is not a guarantee. The check reads SKILL.md only: the scripts in the folder are not scanned, so read them before running anything.

What licence does Promise Theory use?

Promise Theory is published under the MIT licence (declared in SKILL.md). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does Promise Theory use?

About 2.7k tokens (SKILL.md is roughly 11k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full. Its references folder adds about 48k tokens, read only when the agent opens those files.

What are the alternatives to Promise Theory?

Skills that share tags, products or a category with Promise Theory: Teach (cursor/plugins, 11k stars), Agent Adaptive Coordinator (ruvnet/ruflo, 74k stars), Agent Consensus Coordinator (ruvnet/ruflo, 74k stars) and Agent Hierarchical Coordinator (ruvnet/ruflo, 74k stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains Promise Theory?

magnus919 (a GitHub user) maintains it in magnus919/agent-skills, which has 115 GitHub stars. The repository holds 131 skills in this directory. The repository was last updated on October 10, 2026.

Source: magnus919/agent-skills on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.