skills/bdi-agency-model/SKILL.md
BDI (Beliefs-Desires-Intentions) agency framework for designing autonomous agents with mental state architectures
npx skillsauth add curiositech/windags-skills bdi-agency-modelInstall this skill globally with one command. Works with Claude Code, Cursor, and Windsurf.
3 of 9 scanners reported clean
Some scanners were skipped, did not run, or reported a non-clean status. Review each row below.
license: Apache-2.0
Load this skill when facing:
This skill applies beyond robotics/AI agents—it's relevant for any system that must make decisions over time with partial information, including business process systems, game AI, automated trading, and organizational design.
Beliefs (informational state), Desires (motivational state), and Intentions (deliberative state) aren't philosophical conveniences—they're architectural necessities for resource-bounded agents in dynamic environments.
Why separate? Because conflating them creates impossible computational requirements:
The separation enables local updates and selective reasoning.
The core tension:
The empirical finding (bold vs. cautious agents):
Rational commitment = maintaining intentions until there's sufficient reason to reconsider, where "sufficient" depends on environment dynamics and computational costs.
Task-oriented systems: Execute procedures without maintaining why
Goal-oriented systems: Maintain explicit desired states and plans to achieve them
The gap: Most software is task-oriented. BDI provides the minimal architecture for goal-orientation.
Intentions don't just represent commitments—they actively constrain future reasoning:
This is not bounded rationality or satisficing—it's a rational strategy for resource-bounded agents. The alternative (consider all options always) is computationally intractable.
BDI (philosophy/logic tradition) and Soar (cognitive psychology tradition) independently converged on isomorphic architectures:
| BDI Component | Soar Component | Computational Role | |---------------|----------------|-------------------| | Beliefs | States | World representation | | Desires | Subgoals | Motivational targets | | Intentions | Operators | Chosen actions | | Plans | Problem spaces | Action sequences |
Implication: These components aren't arbitrary design choices but discovered necessities—like multiple cultures independently inventing the wheel. Any system facing similar constraints (bounded resources, partial information, dynamic environments, real-time action) will need similar structures.
IF environment is highly static THEN bias toward bold commitment (rarely reconsider) IF environment is highly dynamic THEN bias toward cautious reconsideration (frequently reevaluate)
IF computational resources abundant THEN can afford more frequent reconsideration IF computational resources scarce THEN must commit more strongly to amortize planning cost
IF action execution is expensive THEN reconsider before acting IF deliberation is expensive THEN commit and act quickly
IF new information directly contradicts intention's preconditions THEN reconsider immediately IF new information merely opens alternatives THEN reconsider only if significantly better
IF system must act in real-time THEN needs intentions (can't replan from desires every cycle) IF system faces conflicting goals THEN needs desire/intention distinction (desires can conflict, intentions cannot) IF system must coordinate with others THEN needs explicit intentions (for commitment communication) IF system must explain behavior THEN needs all three (explain actions via intentions, intentions via desires, desires via beliefs) IF system must adapt to failures THEN needs goal-oriented representation (to find alternative means)
IF environment is static AND goals are clear AND plans rarely fail THEN task-oriented architecture may suffice IF environment changes OR goals conflict OR plans frequently fail THEN need BDI-style architecture IF multiple agents must coordinate THEN need explicit commitment mechanisms (load multi-agent reference) IF system must learn from experience THEN need BDI + learning extensions (load learning reference)
| Reference File | Load When... | Key Content |
|----------------|--------------|-------------|
| why-beliefs-desires-intentions-exist.md | Justifying architectural decisions; explaining why three components are necessary | Detailed computational argument for BDI separation; what each component solves; costs of conflation |
| rational-commitment-and-reconsideration.md | Designing reconsideration strategies; debugging thrashing or stubbornness | Kinny-Georgeff experiments; bold vs. cautious agents; meta-level control; empirical results |
| task-vs-goal-orientation.md | Comparing architecture approaches; explaining need for goal representation | Deep dive on task/goal distinction; recovery capabilities; opportunistic replanning; explainability |
| soar-bdi-convergent-evolution.md | Validating design choices; comparing with cognitive architectures | Soar-BDI mapping; convergent evolution argument; universal principles; cross-tradition insights |
| multi-agent-commitment-and-coordination.md | Designing multi-agent systems; coordination protocols | Joint intentions; social commitments; team reasoning; coordination mechanisms; distributed BDI |
| learning-the-missing-piece.md | Adding adaptation; integrating ML with planning | BDI limitations; learning integration strategies; experience-based improvement; open challenges |
Symptom: System constantly reconsiders all options, thrashes between plans, never completes actions Root cause: Treating every belief update as requiring complete replanning (classical decision theory mistake) BDI insight: Rational commitment means maintaining intentions despite minor belief changes
Symptom: System continues executing plan after goal achieved or becomes impossible Root cause: Task-oriented architecture without goal representation BDI insight: Maintain explicit relationship between intentions, plans, and desires to enable goal-aware execution
Symptom: System tries to pursue conflicting goals simultaneously, resources spread too thin Root cause: Not distinguishing between "would like to achieve" and "committed to pursuing" BDI insight: Desires can conflict; intentions cannot (must resolve conflicts during deliberation)
Symptom: System abandons plans at first difficulty; erratic, unpredictable behavior Root cause: Treating intentions as weak preferences rather than commitments BDI insight: Intentions constrain future reasoning—they're not just goals but committed goals
Symptom: System fails when environment changes; no recovery from failures Root cause: Conventional software approach (plan = fixed procedure) BDI insight: Plans must be monitored against goals; reconsideration needed when environment dynamics high
Symptom: Fixed reconsideration strategy fails across different environment dynamics Root cause: Not adapting commitment strategy to environment characteristics BDI insight: Need meta-level reasoning about when to reconsider (the central open problem)
Symptom: Coordination failures; agents undermine each other's plans Root cause: Using individual BDI without social commitment mechanisms BDI insight: Multi-agent requires joint intentions and commitment communication protocols
Key diagnostic question: "Why can't you just merge desires and intentions?"
data-ai
license: Apache-2.0 NOT for unrelated tasks outside this domain.
development
Use when designing caching strategies (cache-aside, write-through, write-behind), implementing distributed locks, building rate limiters, leaderboards, real-time streams (XADD/consumer groups), pub/sub, or tuning eviction policies. Triggers: thundering-herd on cache miss, dogpile on key expiry, Redlock vs SET-NX-PX choice, sliding-window rate limiter, hot-key on a single cluster slot, big-key blowup, MULTI/EXEC across slots, KEYS in production. NOT for Redis Cluster operations/admin (different domain), embedded KV (SQLite, leveldb), in-process LRU caches, or Memcached.
tools
Drawing the `'use client'` boundary correctly in React Server Components apps (Next.js App Router, RSC frameworks) — leaf-pushing, slot composition, serialization rules, and environment poisoning prevention. Grounded in react.dev and Next.js 16 docs.
development
Use when designing rate limiting for an API, choosing between token bucket / sliding window / leaky bucket / fixed window, implementing it in Redis, deciding edge (Cloudflare/Upstash) vs origin enforcement, sizing per-user vs per-IP vs per-endpoint quotas, returning the right 429 response with Retry-After, or fixing the boundary-burst bug in fixed-window limiters. Triggers: 429 too many requests, INCR + EXPIRE, ZADD + ZREMRANGEBYSCORE + ZCARD, X-RateLimit-Remaining header, Cloudflare WAF rate limiting rules, Upstash @upstash/ratelimit, leaky bucket shaping vs policing, distributed rate limiter consistency. NOT for DDoS mitigation specifically (different scale), CAPTCHA / bot management, full WAF design, or per-user quota billing.