cognitive-update — Claude Code skill for state updates
The cognitive-update Claude Code skill updates goals, beliefs, self-model fields, and procedures from explicit evidence. It activates for cognitive or runtime state changes.
MIT ★ 26 updated 2026-11-16
npx skills add wrg32786/aigent-os --skill cognitive-update -a claude-codeWhat cognitive-update does
The skill edits four project state files: GOAL_STACK.json, BELIEF_STATE.jsonl, SELF_MODEL.json, and PROCEDURES.jsonl. Evidence can come from an operator’s explicit statement with a durable source reference, a command or test result, an external artifact, or repeated observations. An agent’s single claim cannot establish a lasting state change.
Writes stay within those four files; ACTIVE_STATE.json and STATE_EVENTS.jsonl belong to the runtime state daemon. The protocol compares file hashes before writing and runs the COGNITIVE_CONTRACT validator afterward. A manual run needs Node.js, an aigent-root directory, and a temporary snapshot created with node daemons/nightly-contracts.mjs snapshot. A changed hash aborts the write.
What it helps with
- record an explicit goal or blocker in
GOAL_STACK.json - append a supported belief to
BELIEF_STATE.jsonl - update a named capability or limitation in
SELF_MODEL.json - save a recurring workflow in
PROCEDURES.jsonl - validate cognitive-state changes against a snapshot
Example prompts for the agent
- Update cognitive state using explicit evidence.
- Record this goal in
GOAL_STACK.jsonand validate the contract. - Add the repeated workflow to
PROCEDURES.jsonlbased on observed runs.
How to install cognitive-update
1Skills CLI (Vercel)
npx skills add wrg32786/aigent-os --skill cognitive-update -a claude-code2Manually: put the files in place
~/.claude/skills/cognitive-update/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/cognitive-update/
1Skills CLI (Vercel)
npx skills add wrg32786/aigent-os --skill cognitive-update -a codex2Manually: put the files in place
.agents/skills/cognitive-update/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add wrg32786/aigent-os --skill cognitive-update -a cursor2Manually: put the files in place
.cursor/skills/cognitive-update/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install wrg32786/aigent-os skills/cognitive-update2Manually: put the files in place
.github/skills/cognitive-update/SKILL.md1Skills CLI (Vercel)
npx skills add wrg32786/aigent-os --skill cognitive-update -a gemini-cli2Platform CLI
gemini skills install https://github.com/wrg32786/aigent-os --path skills/cognitive-updateManually: put the files in place
.devin/skills/cognitive-update/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add wrg32786/aigent-os --skill cognitive-update -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about cognitive-update
How do I install cognitive-update in Claude Code?
Run npx skills add wrg32786/aigent-os --skill cognitive-update -a claude-code. The skill file is installed at ~/.claude/skills/cognitive-update/SKILL.md.
What does cognitive-update do?
It changes goals, beliefs, self-model fields, and procedures when supported by explicit evidence. It checks source-file hashes before writing.
What evidence does cognitive-update accept?
Accepted evidence includes an operator statement with a durable source reference, a command or test with its literal exit code, an external artifact, or two independent observations of a recurring event. Session Log entries and capsules cannot verify their own claims.
Source text
SKILL.md · MIT
--- name: cognitive-update agent: none description: "Update GOAL_STACK, BELIEF_STATE, SELF_MODEL, and PROCEDURES from explicit evidence. Use when updating cognitive state or runtime state." allowed-tools: Read, Write, Bash user-invocable: true status: PRODUCTION - conservative and source-referenced triggers: - cognitive update - update cognitive state - runtime state update --- # /cognitive-update Nightly uses this shared protocol after `/system-check`. It never infers a durable state change from one agent-authored claim. ## Ownership fence This protocol may update only: - `vault/memory/runtime/GOAL_STACK.json` - `vault/memory/runtime/BELIEF_STATE.jsonl` (append-only) - `vault/memory/runtime/SELF_MODEL.json` - `vault/memory/runtime/PROCEDURES.jsonl` (append-only) The documented `memory/` fallback is valid for minimal installations. This protocol never writes `ACTIVE_STATE.json` or `STATE_EVENTS.jsonl`; the runtime state daemon owns those products. It never writes Dream or measurement ledgers. ## Evidence admission Direct updates require one of: - the operator's explicit goal, belief, or procedure statement with a durable source reference; - a repository-owned command or test invoked with explicit arguments and a literal exit code; - an external artifact that directly decides the claim; - two independent observed occurrences for a recurring capability or failure. Capsules and Session Log entries are discovery sources. They cannot verify their own confident claims. If evidence is incomplete, skip the durable update and stage an observation through the nightly evidence flow. ## File rules ### GOAL_STACK.json Move, append, or update only explicit goals, blockers, next actions, and completions. Completion requires success criteria plus an external artifact or operator confirmation. Preserve unknown fields and unrelated arrays. ### BELIEF_STATE.jsonl Append only. A revision reuses the original id and includes `revision_note`; a new belief receives max numeric `bNNN` plus one. Do not use line count. Serialize UTF-8 JSON and parse the appended line. ### SELF_MODEL.json Update only named capability, limitation, recurring-failure, reliability-risk, or achieved-learning-goal fields. When alias arrays coexist, update each alias pair in lockstep or fail `SELF_MODEL_ALIAS`. A one-off result is not a durable capability. ### PROCEDURES.jsonl Append only when the sequence occurred at least twice, the operator explicitly made it standing, or a non-obvious workflow was mechanically proven. Allocate max numeric `pNNN` plus one and parse after append. ## Write discipline Hash every source immediately after read and compare again before write. A hash change aborts rather than clobbering newer state. Preserve JSON formatting where practical; always serialize JSONL. A nightly fire uses the immutable snapshot created by `nightly-pass begin`. For explicit use, create an operating-system temp snapshot: ```text node daemons/nightly-contracts.mjs snapshot --root <aigent-root> \ --out <os-temp>/cognitive-contract-before.json ``` After any updates: ```text node daemons/nightly-contracts.mjs cognitive --root <aigent-root> \ --snapshot <os-temp>/cognitive-contract-before.json \ --new-belief-ids <csv> --new-procedure-ids <csv> \ --self-alias-additions <csv> ``` Only `COGNITIVE_CONTRACT PASS` is green. The validator re-parses all four products, proves append-only suffixes, derives allocated ids, validates new-row schemas, and derives alias additions and removals. Return: ```text COGNITIVE_UPDATE PASS goals=<N> beliefs=<N> self_model=<N> procedures=<N> skipped=<N> ```
© wrg32786 · MIT · wrg32786/aigent-os