# Agentic Os

> Framework-agnostic persistent memory and self-improvement loops for AI agents. Scaffolds shared state, task queues, and learnings files that can be read/written by Claude, Gemini, and Antigravity. Use this to initialize an Agentic OS layer in any workspace and instruct agents on how to use it.

- Skill: `genericservice/agentic-os` (Agent Skill, multi-file: 7 files)
- Install (CLI): `npx skillmds@latest add genericservice/agentic-os`
- Raw SKILL.md: https://api.skillmd.com/api/skills/genericservice/agentic-os/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- Author: genericservice (https://skillmd.com/u/genericservice)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/genericservice/agentic-os

---


# Agentic OS

This skill establishes a framework-agnostic Agentic Operating System layer in a project workspace. It enables Claude, Gemini, and Antigravity to share persistent operational memory, coordinate via task queues, and continuously improve through structured feedback loops.

## The Core Concept

An Agentic OS solves the "blank slate" problem. Without it, every agent session starts fresh, requiring manual context loading and repeating past mistakes. By centralizing state and learnings into an `.agent/` directory, any agent runtime can pick up exactly where the last one left off and apply compounded knowledge.

## Initialization

To set up the Agentic OS scaffolding in a new project, run:

```bash
bash ~/.agents/skills/agentic-os/scripts/init-os.sh
```

This creates the following structure at the root of the project:
```
.agent/
  ├── state/
  │   ├── last-run.json      # Global log of the last agent actions
  │   ├── tasks.json         # Shared queue of pending/completed tasks
  │   ├── errors.json        # Log of unresolved task failures
  │   └── status.md          # Output of the command-center skill
  ├── learnings/             # Per-skill feedback loops
  │   └── template.json
  └── evals/                 # Per-skill evaluation criteria
      └── template.json
```

## Agent Directives

Whenever you operate in a project that has an `.agent/` directory, you MUST adhere to the following workflow:

### 1. Pre-Task: Load State & Learnings
Before executing a specialized task or skill:
- **Read State**: Check `.agent/state/last-run.json` to understand what was recently completed. Check `.agent/state/tasks.json` if you need to pull a task from the queue.
- **Read Learnings**: If you are about to perform a specific skill (e.g., `write-draft`), check if `.agent/learnings/write-draft.json` exists. If it does, read it and explicitly apply its `rule_change` entries to your approach.
- **Read Evals**: Check if `.agent/evals/<skill>.json` exists to understand the definition of "done".

### 2. Execution & Evaluation (The Learnings Loop)
After generating your output but *before* finalizing:
- If an `eval.json` exists for your task, grade your own output against its criteria. (Use `python3 ~/.agents/skills/agentic-os/scripts/eval.py list --skill <skill>`)
- If you fail any criteria, revise your output.
- Once you pass, log your verification using `python3 ~/.agents/skills/agentic-os/scripts/eval.py verify --skill <skill> --task-id <id> --notes "..."`
- Consider what worked well and what didn't during generation.

### 3. Post-Task: Write State & Learnings
Before you conclude your session or step:
- **Update Learnings**: If you learned something new about how to do this task better in this specific project, use `python3 ~/.agents/skills/agentic-os/scripts/learn.py add --skill <skill> --worked "..." --didnt "..." --rule "..."` to record it.
- **Update State**: Overwrite `.agent/state/last-run.json` with a summary of what you just did, what decisions you made, and what needs to happen next.
- **Update Queue**: If you completed a task from `tasks.json`, mark its status as `completed`.
- **Log External Receipts**: If you took external actions (deployments, API calls), record strict receipts or cryptographic hashes in the `external_receipts` array in `last-run.json` and the corresponding task in `tasks.json` to ensure an audit trail.

### 4. Cross-Agent Memory Unification
When you learn a critical fact about the project, the user's preferences, or system architecture, **do not rely solely on your proprietary memory system** (e.g., Claude's internal `.claude/` memory or Gemini's `save_memory` / `~/.gemini/tmp/.../MEMORY.md`). 
Proprietary memory is siloed and invisible to other agents. You MUST record project-wide facts in shared locations so that Claude, Gemini, and Antigravity can all access them:
- Use `.agent/learnings/` for specific skill rules or workflow learnings.
- Modify `GEMINI.md` or `CLAUDE.md` for team-shared architectural conventions, repository rules, or broad project guidance.

---

## Data Schemas

### `last-run.json`
Used for operational continuity.
```json
{
  "timestamp": "2026-04-25T12:00:00Z",
  "task_id": "task-123",
  "status": "completed",
  "description": "Built the new Hero component.",
  "assigned_skill": "build-component",
  "project_id": "generic-service",
  "agent_id": "antigravity",
  "user_id": "matthias",
  "outcome": {
    "result": "Success"
  },
  "trace_id": "req-12345",
  "decision_log": "Used standard Tailwind utility classes instead of custom CSS for faster rendering",
  "external_receipts": [
    {
      "action": "Vercel Preview Deployment",
      "receipt_hash": "sha256-1a2b3c..."
    }
  ]
}
```

### `errors.json`
Used by the `command-center` skill to track unresolved failures.
```json
[
  {
    "timestamp": "2026-04-25T12:05:00Z",
    "task_id": "task-124",
    "assigned_skill": "osint",
    "reason": "Target API returned 429 Too Many Requests after 3 retries",
    "trace_id": "req-12346",
    "decision_log": "Attempted to backoff but exceeded max wait time.",
    "resolved": false
  }
]
```

### `learnings.json` (per skill)
Used to permanently correct agent behavior without modifying the base skill prompt.
```json
{
  "skill": "build-component",
  "history": [
    {
      "date": "2026-04-21",
      "what_worked": "Extracting the SVG into a separate file kept the component clean.",
      "what_didnt": "Trying to use Next.js Image for inline SVGs caused layout shifts.",
      "rule_change": "Always put complex SVGs in a separate .tsx file and import as a React component. Do not use next/image for vectors."
    }
  ]
}
```

### `eval.json` (per skill)
Used to define rigid quality gates.
```json
{
  "skill": "build-component",
  "criteria": [
    "Component must be responsive down to 320px",
    "Must not use inline styles",
    "Must be exported as a default export"
  ]
}
```