Engineering an Agentic Operating System: Architecting Skills, State Management, and Knowledge Graphs with Claude Code
The current discourse surrounding "Agentic OS" often falls into two polarized camps: those mesmerized by the visual spectacle of high-fidelity dashboards (the "Jarvis" enthusiasts) and those who dismiss them as mere "smoke and mirrors." Both perspectives miss the fundamental engineering reality. The true value of an Agentic Operating System does not reside in its UI/UX; it resides in the underlying architecture: loop engineering, skill architecture, state management, and the codification of workflows.
To build a functional Agent/OS construct—whether powered by Claude Code, Codex, or local LLMs—one must move beyond simple prompting and toward building a modular, programmable environment. This post breaks down the construction of an Agentic OS into four distinct architectural levels.
Level 1: The Backbone — Skill Architecture and Loop Engineering
The foundation of any Agentic OS is the transition from manual interaction to codified execution. In a standard LLM interaction, the user operates in a loop of manual input and output. An Agentic OS breaks this by turning repetitive tasks into Skills (specific, repeatable instructions for a specific output) and Automations (scheduled or triggered executions of those skills).
The Workflow Audit
Before engineering skills, you must perform a workflow audit to identify high-value targets for codification. There are three primary methodologies for this:
- Manual Identification: The developer manually identifies repetitive prompts and converts them into structured skills.
- Session Analysis (Retrospective Auditing): Leveraging Claude Code’s ability to access previous session logs, you can prompt the model to analyze its own history. By instructing the model to parse the last $N$ sessions for repeated tool calls or patterns of interaction, you can generate a structured chart of tasks that lack formal skill definitions.
- Conversational Interviewing: A stream-of-consciousness approach where the user provides raw context about their daily operations, and the AI acts as an interviewer to identify blind spots and potential automation candidates.
From Skills to Automations and Loops
Once a task is codified into a "Skill," the next step is moving it into Automation. In environments like Claude Desktop, this involves utilizing routines—assigning a name to a skill and setting a specific execution schedule.
The ultimate evolution of Level 1 is Loop Engineering. This involves creating self-improving constructs where the system records the outputs of previous iterations and uses that state to refine future runs. While complex, this provides the foundation for an agent that can autonomously iterate on its own performance.
Level effectively: State Management and Knowledge Graphs
Level 2 focuses on Memory and State Control. An AI OS is only as effective as its ability to retrieve relevant context without overwhelming the context window or inflating token costs. While many use Obsidian for this purpose due to its file-based nature, the principle applies to any structured database.
The Karpathy-Inspired RAG Architecture
To prevent the "morass of files" problem—where an LLM struggles to navigate a massive directory—you must implement a hierarchical knowledge map. Inspired by Andrej Karpathy’s approach to building a personal knowledge base, a highly efficient structure for an Agentic OS follows a tripartite pattern:
/raw: Contains unstructured data (articles, raw research, unparsed logs)./wiki: Contains structured, processed data. This is where the agent transforms/rawdata into Wikipedia-style articles, creating high-density information nodes./outputs: The destination for deliverables (slide decks, briefs, code snippets).
Navigational Efficiency via index.md
The critical technical component of this architecture is the implementation of index.md files at every directory level. By placing an index file in each subfolder, you provide a "map" for Claude Code. When the agent enters a directory, it reads the index.md to understand the available contents and paths without needing to perform expensive recursive directory listings. This significantly reduces latency and token consumption during retrieval-augmented generation (RAG) tasks.
Level 3: The Interface — Custom Visual Wrappers
Level 3 is where we implement a custom UI/UX layer over the backend logic. This can be achieved through two primary methods: Web App Wrappers or Obsidian Plugins.
The goal here is to expose "headless" functionality via actionable elements like buttons and real-time metrics. For example, a web dashboard might display YouTube subscriber counts or Instagram engagement alongside single-click buttons that trigger specific Claude Code skills (e.g., an inbox_brief button).
Headless Execution with claude -p
A key technical implementation detail for these interfaces is the use of headless execution. When a user clicks a button in a custom UI, the system triggers a command like claude -p [skill_name]. This allows the skill to run in the background without manually opening a terminal window.
Note: Developers should be aware of changes in how Anthropic manages subscription-based credits (e.g., Claude Max) versus API-based billing when utilizing these command-line flags.
Level 4: Distribution and Organizational Scaling
The final level is Distribution. The power of an Agentic OS lies in its ability to "raise the floor" of a team's technical capability. By wrapping complex, terminal-based skills into a simplified web interface or an Obsidian plugin, you can distribute high-level AI capabilities to non-technical stakeholders and clients.
A web-based distribution (via GitHub repositories or zipped assets) allows for seamless deployment where users interact with sophisticated automations via simple buttons or even voice commands, completely abstracting the underlying complexity of the Claude Code CLI.
Conclusion
Building an Agentic OS is a modular engineering challenge. By focusing 90% of your effort on Level 1 (Skills/Loops) and Level 2 (State/Memory), you create a robust engine. The UI and distribution layers are merely the "cherry on top" that allow this engine to be utilized at scale.