DEV Community: Zane Chen

Understand OpenClaw by Building One - 7: More Context! More Context!

Zane Chen — Tue, 17 Mar 2026 03:14:04 +0000

All code snippets and working code bases are available at this repo.

Multi-Layer Prompts: Context Stacking

Getting the system prompt right is actually an non-trivial job. And a lot of pieces are not static.

They're assembled from multiple layers, each adding context from different aspects.

Identity — Rarely changes (agent's core purpose)
Personality — Optional flavor, mostly static
Bootstrap — Workspace guide, changes when you switch projects
Runtime — Timestamp, session ID — every request
Channel — Where the message came from — varies per request

class PromptBuilder:
    def build(self, state: "SessionState") -> str:
        layers = []

        # Layer 1: Identity
        layers.append(state.agent.agent_def.agent_md)

        # Layer 2: Soul (optional)
        if state.agent.agent_def.soul_md:
            layers.append(f"## Personality\n\n{state.agent.agent_def.soul_md}")

        # Layer 3: Bootstrap context (workspace guide)
        bootstrap = self._load_bootstrap_context()
        if bootstrap:
            layers.append(bootstrap)

        # Layer 4: Runtime context
        layers.append(self._build_runtime_context(agent_id, timestamp))

        # Layer 5: Channel hint
        layers.append(self._build_channel_hint(source))

        return "\n\n".join(layers)

Memory: Long-Term Knowledge

Session context is ephemeral. Memory persists. The pattern shown here uses a specialized agent:

pickle: @cookie Do you know <topic> about user?
cookie: Yes, <content>.

A memory agent manages storage and retrieval. The main agent dispatches queries when it needs to remember something.

Memory can be structured as something like below, but this super flexible.

memories/
├── topics/
│   ├── preferences.md    # User preferences
│   └── identity.md       # User info
├── projects/
│   └── my-project.md     # Project-specific notes
└── daily-notes/
    └── 2024-01-15.md     # Daily journal

Memory System Alternatives

The specialized agent approach keeps the main agent focused. But there are other approaches, just list a few:

Direct tools - Memory tools in the main agent
Skill-based - Use CLI tools like grep
Vector database - Semantic search over embeddings

Each has trade-offs. File-based is simple but limited. Vector databases scale but add complexity. Choose based on your needs.

The Open-Ended Problem

Memory is where agents get hard. Retrieval relevance, storage efficiency, context integration - these are unsolved problems at scale. This implementation is a starting point. Where you take it depends on your use case.

Memory is where agents become personalized. And where the hard problems live.

Next Steps

Previous: Agents are Running, Your are Sleeping | End of series

⭐ Star the repo if you found this series helpful!

Understand OpenClaw by Building One - 6: Agents are Running, Your are Sleeping

Zane Chen — Tue, 17 Mar 2026 03:14:01 +0000

All code snippets and working code bases are available at this repo.

Cron & Heartbeat

Your agent works when you talk to it. But what if it could work while you sleep?

Nothing different from a cron job in engineer world, cron expressions define when a job runs. A background worker checks every minute, finds due jobs, and dispatches them.

Jobs are defined in CRON.md files with a schedule and prompt. The agent runs at the appointed time, does the work, and optionally posts a message back.

class CronDef(BaseModel):
    id: str
    name: str
    description: str
    agent: str
    schedule: str  # Cron expression
    prompt: str
    one_off: bool = False

class CronWorker(Worker):
    async def run(self) -> None:
        while True:
            await self._tick()
            await asyncio.sleep(60)

    async def _tick(self) -> None:
        jobs = self.context.cron_loader.discover_crons()
        due_jobs = find_due_jobs(jobs)

        for cron_def in due_jobs:
            event = DispatchEvent(
                session_id=session.session_id,
                source=CronEventSource(cron_id=cron_def.id),
                content=cron_def.prompt,
            )
            await self.context.eventbus.publish(event)

Cron-Ops Skills

The Cron Operation functionality is implemented using the SKILL system rather than registering dedicated tools which avoids bloating the tool registry.

Reference example repo for example skills.

Concurrency Control: Don't Overload

When multiple requests come in - from cron jobs, from users, from other agents - you need limits. Some agents are expensive to run. Some APIs have rate limits. Unbounded concurrency leads to failures.

Lets use a semaphore based solution to limit concurrency. And each agent has a max_concurrency setting. The semaphore ensures no more than that many instances run at once. Requests wait in line instead of crashing the system.

class AgentWorker(SubscriberWorker):
    def __init__(self, context):
        self._semaphores: dict[str, asyncio.Semaphore] = {}

    async def exec_session(self, event, agent_def) -> None:
        sem = self._get_or_create_semaphore(agent_def)
        async with sem:  # Blocks if limit reached
            # ... execute session ...

Post Message Back: Agents Can Initiate

Sometimes an agent needs to reach out proactively. Maybe it finished a long-running task. Maybe it detected something important. The post_message tool lets agents initiate conversations.

@tool(...)
async def post_message(content: str, session) -> str:
    event = OutboundEvent(
        session_id=session.session_id,
        source=AgentEventSource(agent_id=session.agent.agent_def.id),
        content=content,
    )
    await context.eventbus.publish(event)
    return "Message queued for delivery"

This is how agents say "I'm done" or "Something happened" without being prompted.

The post_message tool is only available in Cron jobs — agents can't arbitrarily post messages outside scheduled tasks.

HEARTBEAT Vs CRON

OpenClaw has two distinct scheduling mechanisms:

HEARTBEAT: Only one allowed, runs in the main session at a regular interval without checking time. Simple periodic execution.
CRON: Multiple allowed, runs in background respecting cron expressions. Full scheduling flexibility.

Next Steps

Previous: Many of Them | Next: More Context! More Context!

⭐ Star the repo if you found this series helpful!

Understand OpenClaw by Building One - 5: Many of Them

Zane Chen — Tue, 17 Mar 2026 03:13:56 +0000

All code snippets and working code bases are available at this repo.

Many of Them

One agent can't be an expert at everything. Neither should it try.

You've built a capable agent. It can read files, search the web, run commands. But ask it to do everything and it struggles. Some tasks need specialized knowledge. Some tasks need focused context. The solution isn't a bigger agent - it's multiple smaller ones.

Agent Discovery

Agents are defined in AGENT.md files. A loader discovers them at startup:

class AgentLoader:
    def discover_agents(self) -> list[AgentDef]:
        """Scan agents directory and return list of valid AgentDef."""
        return discover_definitions(
            self.config.agents_path, "AGENT.md", self._parse_agent_def
        )

Routing: Match Tasks to Agents

Right task to right agent? We need a routing policy to handle this.

Tiered Routing Rules: Find rules matching inbound source, starting from most specific rules.
Default Fallback: Fall back to global default agent if no rules match.

@dataclass
class Binding:
    agent: str
    value: str
    tier: int
    pattern: Pattern  # Compiled regex

    def _compute_tier(self) -> int:
        """Compute specificity tier."""
        if not any(c in self.value for c in r".*+?[]()|^$"):
            return 0  # Exact match
        if ".*" in self.value:
            return 2  # Wildcard
        return 1  # Specific regex

@dataclass
class RoutingTable:
    def resolve(self, source: str) -> str:
        for binding in self._load_bindings():
            if binding.pattern.match(source):
                return binding.agent
        return self.context.config.default_agent

Integration in Channel Worker

When a message arrives, the channel worker uses the routing table to find the right agent:

async def callback(message: str, source: EventSource) -> None:
    # Use routing_table to resolve agent from bindings
    session_id = self.context.routing_table.get_or_create_session_id(source)

    # Publish event
    event = InboundEvent(session_id=session_id, source=source, content=message)
    await self.context.eventbus.publish(event)

Agents Want to Call Their Friends

Let's have another tool to delegate tasks to other agents. The way it is implemented here:

Load subagent definition
Create session
Publish dispatch event
Wait for result.

@tool(name="subagent_dispatch", description="Dispatch a task to a specialized subagent.")
async def subagent_dispatch(agent_id: str, task: str, session) -> str:
    agent_def = shared_context.agent_loader.load(agent_id)
    agent = Agent(agent_def, shared_context)
    agent_session = agent.new_session(agent_source)

    # Publish dispatch event
    await shared_context.eventbus.publish(DispatchEvent(...))

    # Wait for result
    response = await result_future
    return json.dumps({"result": response, "session_id": session_id})

The main agent calls subagent_dispatch, which creates a new session for the subagent and waits for its response. The eventbus handles the communication.

Alternative Multi-Agent Patterns

Direct subagent dispatching is just one approach to multi-agent orchestration. Here are some other common patterns:

Shared Task Lists: Agents coordinate by reading from and writing to a shared task queue or database. Each agent picks up tasks as they become available, agent never talk to agent directly.
Tmux/Screen Sessions: tmux allow us running multiple processes. A tmux skill can be provided to agent to guide it execute multiple tasks, achieving multi-agent to some extent.

Next Steps

Previous: Beyond the CLI | Next: Agents are Running, Your are Sleeping

⭐ Star the repo if you found this series helpful!

Understand OpenClaw by Building One - 4: Beyond the CLI

Zane Chen — Tue, 17 Mar 2026 03:13:51 +0000

Beyond the CLI

Your agent works great in the terminal. But what if you want to talk to it from Telegram? Or your phone? Or another program? Or even multiple of them.

Event-Driven Architecture

To make the agent more scalable, we introduce event-driven architecture before adding more feature.

The pattern is pub/sub, and you already know it. An event bus sits at the center. Messages come in as events, workers process them, responses go out as events.

@dataclass
class InboundEvent:
    session_id: str
    content: str
    source: EventSource

@dataclass
class OutboundEvent:
    session_id: str
    content: str
    error: str | None = None

class EventBus(Worker):
    def subscribe(self, event_class, handler):
        """Subscribe a handler to an event class."""

    async def publish(self, event: Event) -> None:
        """Publish an event to the internal queue."""
        await self._queue.put(event)

    async def run(self) -> None:
        while True:
            event = await self._queue.get()
            await self._dispatch(event)

Channels & Agent Worker & Delivery Worker

Three workers form a pipeline:

Channel Worker — Receives messages from platforms (CLI, Telegram, WebSocket), publishes InboundEvents
Agent Worker — Subscribes to InboundEvents, runs the agent session, publishes OutboundEvents
Delivery Worker — Subscribes to OutboundEvents, routes responses back to the right channel

A channel is an abstraction over a messaging platform. CLI, Telegram, Discord, WebSocket. The channel publishes an InboundEvent to the event bus.

class Channel(ABC):
    @abstractmethod
    async def run(self, on_message: Callable) -> None:
        """Run the channel. Blocks until stop() is called."""
        on_message(message) # Inbound Event to event_bus

    @abstractmethod
    async def reply(self, content: str, source) -> None:
        """Reply to incoming message."""

The agent worker bridges events and sessions:

class AgentWorker:
    def __init__(self, context):
        self.context.eventbus.subscribe(InboundEvent, self.dispatch_event)

    async def dispatch_event(self, event: InboundEvent):
        agent = Agent(agent_def, self.context)
        session = agent.resume_session(event.session_id)
        response = await session.chat(event.content)

        # Publish result
        result = OutboundEvent(
            session_id=event.session_id,
            content=response,
        )
        await self.context.eventbus.publish(result)

The delivery worker picks up OutboundEvents and sends them back through the appropriate channel:

class DeliveryWorker:
    def __init__(self, context):
        self.context.eventbus.subscribe(OutboundEvent, self.deliver)

    async def deliver(self, event: OutboundEvent):
        # Look up which channel this session belongs to
        channel = self._get_channel_for_session(event.session_id)
        await channel.reply(event.content, event.source)

        # Confirm delivery - removes persisted event file
        self.context.eventbus.ack(event)

Event Persistence: Don't Lose Messages

What happens if the server crashes after the agent responds but before delivery? The message is lost.

The fix: persist OutboundEvents to disk before dispatching, delete only after successful delivery:

class EventBus(Worker):
    async def run(self) -> None:
        await self._recover()  # Re-dispatch pending events on startup
        while True:
            event = await self._queue.get()
            await self._dispatch(event)

    async def _dispatch(self, event: Event) -> None:
        await self._persist_outbound(event)  # Write to disk first
        await self._notify_subscribers(event)

    def ack(self, event: Event) -> None:
        """Called by DeliveryWorker after successful delivery."""
        filename = f"{event.timestamp}_{event.session_id}.json"
        (self.pending_dir / filename).unlink()  # Delete persisted file

The flow is complete:

user message → channel → InboundEvent → AgentWorker → OutboundEvent → persist → DeliveryWorker → channel → user → ack → delete.

WebSocket

Sometimes you want code to talk to your agent, not a human. WebSocket provides a programmatic interface.

The WebSocketWorker has two roles:

Channel — Receives messages from WebSocket clients, publishes InboundEvents
Broadcaster — Subscribes to all events, broadcasts them to every connected client

class WebSocketWorker:
    def __init__(self, context):
        self.clients: Set[WebSocket] = set()
        # Broadcaster role: subscribe to ALL events
        for event_class in [InboundEvent, OutboundEvent]:
            self.context.eventbus.subscribe(event_class, self.handle_event)

    # Channel role: receive from clients
    async def handle_connection(self, ws: WebSocket) -> None:
        self.clients.add(ws)
        try:
            await self._run_client_loop(ws)  # Publishes InboundEvent
        finally:
            self.clients.discard(ws)

    # Broadcaster role: send to all clients
    async def handle_event(self, event: Event) -> None:
        for client in list(self.clients):
            try:
                await client.send_json(event_dict)
            except Exception:
                self.clients.discard(client)

@app.websocket("/ws")
async def websocket_endpoint(websocket: WebSocket):
    await websocket.accept()
    await context.websocket_worker.handle_connection(websocket)

Next Steps

Previous: Pack the Conversation And Carry On | Next: Many of Them

⭐ Star the repo if you found this series helpful!

Understand OpenClaw by Building One - 3: Pack the Conversation And Carry On

Zane Chen — Tue, 17 Mar 2026 03:13:46 +0000

All code snippets and working code bases are available at this repo.

Save the Conversation

You and your agent had a great conversation. And you kill the shell. Too bad it doesn't remember any of it.

The solution is simple enough, just save session metadata and messages to disk. And it can end up something like below.

.history/
├── index.jsonl              # Session metadata
└── sessions/
    └── {session_id}.jsonl   # Messages (one file per session)

And corresponding methods to operate on it.

class HistoryStore:
    def create_session(self, agent_id: str, session_id: str) -> dict:
        """Create a new conversation session."""

    def save_message(self, session_id: str, message: HistoryMessage) -> None:
        """Save a message to history."""

    def get_messages(self, session_id: str) -> list[HistoryMessage]:
        """Get all messages for a session."""

Context Windows: The Hidden Limit

LLMs have limits. Even with 200k (just became 1M at the moment I am writing this piece) token context windows, you'll hit them. All conversation messages, tool call request response, they all add up. LLM will refuse to handle them eventually.

The solution is compaction, summarize old messages, keep the signal, drop the noise.

Compaction: Pack and Carry On

To be defensive, we apply two layer of protection.

Summarize — Ask LLM to condense old messages into a summary (expensive, preserves gist).
Truncate — Cut down oversized tool outputs first (cheap, no LLM call). This solve the edge case that the last tool call return a huge result bloat up context directly, leaving entire context in a dead state.

async def check_and_compact(self, state: SessionState) -> SessionState:
    if self.estimate_tokens(state) < self.token_threshold:
        return state

    # Stage 1: truncate large tool results
    state.messages = self._truncate_large_tool_results(state.messages)

    if self.estimate_tokens(state) < self.token_threshold:
        return state

    # Stage 2: summarize old messages
    return await self._compact_messages(state)

The Trade-off

Same as human beings can't remember exactly what happened a year ago, the model loses nuance after compaction. You're balancing memory against token cost.

The example repo implements /context to monitor usage and /compact to manually trigger when needed.

Context management is the difference between a demo and a product.

Next Steps

Previous: Gear up Your Agent | Next: Beyond the CLI

⭐ Star the repo if you found this series helpful!

Understand OpenClaw by Building One - 2: Gear up Your Agent

Zane Chen — Tue, 17 Mar 2026 03:13:40 +0000

All code snippets and working code bases are available at this repo.

Beyond Tools

Tools are part of agents' code asset. But every time you want it to do something new, you have to write code, restart the server, and redeploy.

How to extend its capability & knowledge base without changing its code?

Skills - Dynamic Capabilities Loading

Skills are lazy loaded capabilities at runtime. It isn't something Openclaw invented, but an open standard. Reference the official document for more info.

The pattern is simple: a SKILL.md file with YAML frontmatter for metadata loaded up front and markdown for instructions loaded when needed.

def create_skill_tool(skill_loader):
    # Discover skills and get metadata
    skill_metadata = skill_loader.discover_skills()

    # Build XML description of available skills
    skills_xml = "<skills>\n"
    for meta in skill_metadata:
        skills_xml += f'  <skill name="{meta.name}">{meta.description}</skill>\n'
    skills_xml += "</skills>"

    # Tool loads full content only when called
    @tool(name="skill", description=f"Load skill. {skills_xml}", ...)
    async def skill_tool(skill_name: str, session) -> str:
        return skill_loader.load_skill(skill_name).content

Two Approaches to Skills

Openclaw doesn't implement skills with a separate tool. Instead, it uses system prompt injection with file reading:

Tool Approach: Dedicated skill tool lists available skills and loads content. The tool schema includes skill metadata in its description. Self-contained skill discovery and loading.
System Prompt Approach: Skill metadata (id, name, description) injected into system prompt. Agent uses standard read tool to read SKILL.md. No specialized skill tool needed, simpler tool registry.

Slash Commands: User Control

Sometimes you want direct control, not a conversation. Slash commands let you manage the session itself: list skills, show session info, clear history. The implementation is fairly simple.

class Command(ABC):
    name: str
    aliases: list[str] = []

    @abstractmethod
    async def execute(self, args: str, session) -> str:
        pass

class CommandRegistry:
    async def dispatch(self, input: str, session) -> str | None:
        """Parse and execute a slash command. Returns None if not a command."""
        if not input.startswith("/"):
            return None
        # Parse: /command args
        parts = input[1:].split(None, 1)
        cmd_name, args = parts[0], parts[1] if len(parts) > 1 else ""
        if cmd_name in self._commands:
            return await self._commands[cmd_name].execute(args, session)
        return None

Integration in the main loop — check commands before sending to LLM:

async def run(self) -> None:
    while True:
        user_input = await get_input()
        # Check for slash commands first
        cmd_response = await self.command_registry.dispatch(user_input, self.session)
        if cmd_response is not None:
            self.console.print(cmd_response)
            continue

        # Normal chat
        response = await self.session.chat(user_input)
        self.display_agent_response(response)

Slash Commands and Session History

Slash commands may or may not be added to the session history (message log sent to the LLM). This is a design decision — commands are user controls, not conversation content. Either approach is valid depending on your use case.

Web Tools: Connect to the World

Your agent lives in a terminal. But the information it needs lives on the web.

Two tools bridge this gap:

websearch: Search the web and get structured results
webread: Fetch and extract content from URLs

@tool(...)
async def websearch(query: str, session) -> str:
    results = await provider.search(query)
    output = []
    for i, r in enumerate(results, 1):
        output.append(f"{i}. **{r.title}**\n   {r.url}\n   {r.snippet}")
    return "\n\n".join(output)

Now your agent can research, fact-check, and pull in live data.

Agents That Grow

Skill solves the problem of extending agents' capability. Web tools lift the restriction of agents limited knowledge base.

If you try this out, you will find the agent is already way more capable then your expectation.

Next Steps

Previous: Every Agent Starts as a Loop | Next: Pack the Conversation And Carry On

⭐ Star the repo if you found this series helpful!

Understand OpenClaw by Building One - 1: Every Agent Starts as a Loop

Zane Chen — Tue, 17 Mar 2026 03:12:46 +0000

All code snippets and working code bases are available at this repo.

Every Agent Starts as a Loop

Strip away the buzzwords, and an agent is just a chat loop that sometimes executes code. The core is maybe 20 lines:

while True:
    user_input = await get_user_input()
    response = await session.chat(user_input)
    display(response)

That's it. No magic. The session.chat() method sends messages to the LLM and returns the response. You already know this pattern.

Tools Transform Talk into Action

What makes an "agent" different from a "chatbot" is tools calls. The LLM decides when to use them. Your job is to define what tools exist and how to run them.

The pattern is simple, define a tool schema, let the LLM decide when to call it, execute it, feed the result back.

class BaseTool(ABC):
    name: str
    description: str
    parameters: dict[str, Any]

    @abstractmethod
    async def execute(self, session, **kwargs) -> str:
        pass

description tell the LLM what the tool does.
parameters schema tells the what arguments to provide.
execute method is your implementation.

The Tool Calling Loop

When the LLM wants to use a tool, it returns a tool_calls list instead of text and emit stop_reaonson as tool_use at the same time. Your agent executes each tool, adds the results to the message history, and calls the LLM again. This continues until the LLM responds with text.

while True:
    messages = self.state.build_messages()
    content, tool_calls = await self.llm.chat(messages, tool_schemas)
    if not tool_calls:
        break

    await self._handle_tool_calls(tool_calls)

Start Minimal

You don't need dozens of tools. Read, Write, and Bash are enough to start. These let your agent ability to write and execute code, everything else builds on this foundation.

Next Steps

Start from the beginning | Next: Gear up Your Agent

⭐ Star the repo if you found this series helpful!

Beyond the Buzzwords: Context, Prompts, and Tools

Zane Chen — Fri, 13 Feb 2026 01:11:15 +0000

Wake up in 2026, open a coding assistant, and you're jumping into a terminology soup: Agents, Subagents, Prompts, Contexts, Memory, Modes, Permissions, Tools, Plugins, Skills, Hooks, MCP, LSP, Slash Commands, Workflows, Instructions and etc.

Companies building these tools love creating new branding for every slight variation in interaction. Instead of getting trapped in the vocabulary treadmill, look at the architecture. Every AI coding tool, no matter how fancy the marketing, deals with the same three things: context, tools, and prompts.

Context: The Memory Budget

Context is the agent's working memory. It's also the bottleneck. While context windows have grown, they're still finite and expensive. Every file you open, every tool output you receive, every turn in the conversation eats into your budget.

The different terminologies you see imply different strategies for managing this constraint.

Slash Commands (/commit, /explain): Reusable instructions. When you catch yourself typing the same prompt over and over, slash commands are the shortcut.
Context Compaction: The AI's long-term memory mechanism. When the chat gets bloated, the system summarizes previous turns. This keeps the conversation going, but you lose the granular details of why a specific decision was made.
Selective Loading: Load only what you need, when you need it. The idea is simple: keep the context window empty until the last possible second, then load the specific snippets required for the current line of code.

The underlying problem hasn't changed since the first chatbots. Context windows are limited. The terminology keeps expanding, but we're still solving the same problem: how to give the agent what it needs without exceeding its memory budget.

Tools: The Action Layer

A chatbot can only generate text. An agent can take action. Tools bridge the gap between thinking and doing. From an architectural perspective, everything beyond the prompt is a tool call.

Tools can be categorized in many ways. Here are a few:

The Actuators (File System & Terminal): These tools let the agent actually modify your world—writing files, creating directories, running shell commands for builds and tests.
The Navigators (LSP & Indexers): LLMs are great at thinking but terrible at finding where things are. They can waste tons of tokens reading file after file just to locate one function. LSP (Language Server Protocol) tools give the agent sharp insight into code syntax, letting it find the right function definition without reading everything.
The Executioners (Sandboxes): Modern agents often use code interpreters or isolated sandboxes. If an agent isn't sure about a logic block, it can write a small script, execute it in a sandbox, and see the real output before suggesting it to you.
The Researcher (Browsers & RAG): These tools let the agent step outside your local machine. A browser tool lets it read information created after the model was trained.

The Bridge: MCP (Model Context Protocol)

MCP is not a tool. It's the standardized interface that connects the agent to tools.

Before MCP, each tool implementation added maintenance burden to the developer team who owned the agent. This meant rebuilding wheels for the same resources over and over.

With MCP, the transport layer and tool spec are standardized. MCP server implementations become way more reusable, making the entire ecosystem plug-and-play.

Prompts: More than Just Talk

When you talk directly to an LLM, you're giving it a user prompt. System prompts work differently. User prompts tell the agent what you want. System prompts tell the agent how to behave.

There are many fancy terms for system prompts, but they're all about shaping how the AI thinks and acts. The key difference is when and how they load.

Base Instructions

Base instructions load when the session starts. These set the ground rules: what tools are available, what constraints exist, what background knowledge applies. Files like CLAUDE.md or AGENTS.md typically contain these. They're the foundation that everything else builds on. They can be global or per project.

Skills

Skills load only when needed. A skill usually contains:

Name
Description: a short piece of text used by the LLM to decide when to load the entire content
Body: detailed instructions

A debugging skill won't activate until you ask to debug something. A refactoring skill stays dormant until you mention refactoring. This lazy loading matters, it saves context by not loading domain expertise until it's actually needed.

Commands

Commands are shorthand for user prompts. When you type /refactor, you're not asking the agent to refactor in a general sense. You're triggering a pre-crafted prompt that says something like "Analyze the selected code and suggest a refactoring that improves readability while preserving functionality." The command is a shortcut for a specific prompt you'd otherwise have to type out.

Modes

Modes combine system prompts with tool configurations. Plan mode might load a more analytical system prompt and restrict tools to those useful for planning—reading files, analyzing code structure, understanding dependencies. Build mode might use a more action-oriented prompt and prioritize tools for writing code, running tests, and making changes. Modes are presets that bundle together a behavior and the tools that support it.

The Hierarchy of Prompts

The core idea follows the same principles as software development: lazy loading resources and making them reusable.

These prompts form a hierarchy:

Modes replace the entire configuration with a pre-baked set of prompts and tools
Base instructions are the foundation—they always apply
Skills layer on top, adding domain expertise when needed
Commands trigger specific user prompts on top of whatever system prompts are active

Every prompt terminology does the same thing: layering prompts to shape behavior. Some load early, some load late. Some replace others, some build on them. But they're all prompts.

Delegation: When Context Hits a Wall

This is where the three fundamentals intersect. Because context is limited, we try to split work among multiple agents.

Interestingly, even for humans, working with high-level planning and design doesn't require considering low-level details. Working with details doesn't require knowledge about the big picture beyond its own scope—as long as the spec is good enough.

Think of it as the architect agent calling a worker agent as a tool.

The architect identifies a task that requires deep focus (e.g., "Refactor this 2,000-line module")
Instead of doing it itself and bloating its own context, the architect delegates it to a subagent
The subagent starts with a fresh, empty context and a specific skill prompt for refactoring
Once the work is done, the subagent returns a concise summary to the architect

This recursive agency allows us to deal with bigger tasks without the main brain of the AI becoming a garbled mess of too much information.

Subagent delegation is just another tool. It's a tool that happens to spawn another agent with its own context. That mental model—thinking of subagents as tools—helps when working with coding agents.

Takeaways

The terminology will keep expanding at the speed of marketing, but the underlying mechanics of AI development stay the same.

The agent vocabulary in 2026 is noisy. But by focusing on these three things—context, tools, and prompts—you move from being a consumer of buzzwords to an architect of the technology. You gain the ability to see the same reliable patterns beneath every new interface that hits the market.

Turn Your Github Contribution Graph into Space Shooter 🚀

Zane Chen — Wed, 14 Jan 2026 02:45:45 +0000

Sharing the tool I recently having so much fun building - Github Space Shooter. It does not solve any problem, but turns your boring GitHub contribution graph into a generated space shooter game gif.

I just launched a web wrapper so you can generate your own galaxy instantly without any setup and watch your year of coding turn into a space battle.

Use the web version for one time generation.

Use the github action for have the space shooter updated on a scheduled basis.

And give the repo a star ⭐ if you enjoy.

Convincing Myself to "Vibe Code"

Zane Chen — Sat, 27 Dec 2025 03:14:32 +0000

Context: The Memory Budget

The different terminologies you see imply different strategies for managing this constraint.

Slash Commands (/commit, /explain): Reusable instructions. When you catch yourself typing the same prompt over and over, slash commands are the shortcut.
Context Compaction: The AI's long-term memory mechanism. When the chat gets bloated, the system summarizes previous turns. This keeps the conversation going, but you lose the granular details of why a specific decision was made.
Selective Loading: Load only what you need, when you need it. The idea is simple: keep the context window empty until the last possible second, then load the specific snippets required for the current line of code.

Tools: The Action Layer

A chatbot can only generate text. An agent can take action. Tools bridge the gap between thinking and doing. From an architectural perspective, everything beyond the prompt is a tool call.

Tools can be categorized in many ways. Here are a few:

The Actuators (File System & Terminal): These tools let the agent actually modify your world—writing files, creating directories, running shell commands for builds and tests.
The Navigators (LSP & Indexers): LLMs are great at thinking but terrible at finding where things are. They can waste tons of tokens reading file after file just to locate one function. LSP (Language Server Protocol) tools give the agent sharp insight into code syntax, letting it find the right function definition without reading everything.
The Executioners (Sandboxes): Modern agents often use code interpreters or isolated sandboxes. If an agent isn't sure about a logic block, it can write a small script, execute it in a sandbox, and see the real output before suggesting it to you.
The Researcher (Browsers & RAG): These tools let the agent step outside your local machine. A browser tool lets it read information created after the model was trained.

The Bridge: MCP (Model Context Protocol)

MCP is not a tool. It's the standardized interface that connects the agent to tools.

Before MCP, each tool implementation added maintenance burden to the developer team who owned the agent. This meant rebuilding wheels for the same resources over and over.

With MCP, the transport layer and tool spec are standardized. MCP server implementations become way more reusable, making the entire ecosystem plug-and-play.

Prompts: More than Just Talk

When you talk directly to an LLM, you're giving it a user prompt. System prompts work differently. User prompts tell the agent what you want. System prompts tell the agent how to behave.

There are many fancy terms for system prompts, but they're all about shaping how the AI thinks and acts. The key difference is when and how they load.

Base Instructions

Skills

Skills load only when needed. A skill usually contains:

Name
Description: a short piece of text used by the LLM to decide when to load the entire content
Body: detailed instructions

Commands

Modes

The Hierarchy of Prompts

The core idea follows the same principles as software development: lazy loading resources and making them reusable.

These prompts form a hierarchy:

Modes replace the entire configuration with a pre-baked set of prompts and tools
Base instructions are the foundation—they always apply
Skills layer on top, adding domain expertise when needed
Commands trigger specific user prompts on top of whatever system prompts are active

Every prompt terminology does the same thing: layering prompts to shape behavior. Some load early, some load late. Some replace others, some build on them. But they're all prompts.

Delegation: When Context Hits a Wall

This is where the three fundamentals intersect. Because context is limited, we try to split work among multiple agents.

Think of it as the architect agent calling a worker agent as a tool.

The architect identifies a task that requires deep focus (e.g., "Refactor this 2,000-line module")
Instead of doing it itself and bloating its own context, the architect delegates it to a subagent
The subagent starts with a fresh, empty context and a specific skill prompt for refactoring
Once the work is done, the subagent returns a concise summary to the architect

This recursive agency allows us to deal with bigger tasks without the main brain of the AI becoming a garbled mess of too much information.

Takeaways

The terminology will keep expanding at the speed of marketing, but the underlying mechanics of AI development stay the same.

The CSS Odyssey: Why I Turned back to CSS After Trying Everything Else

Zane Chen — Thu, 05 Jun 2025 23:19:53 +0000

TL;DR: This is a story of my journey through CSS solutions. Which led to my personal opinion that simpler tools often work better than complex abstractions. CSS-in-JS, zero-runtime CSS-in-JS, and Tailwind all taught me valuable lessons, but they all added build complexity that eventually became more trouble than benefit. And I eventually returned back to CSS Modules for a better maintainability and simplicity.

Start with Vanilla CSS

I started my web development journey the traditional way years back—HTML, CSS and JS in separate files. When I learned React, I kept the same approach without exploring the solutions ecosystem much. I'd create a .css file, import it into my .jsx file, and split stylesheets as they grew.

// .container {
//     width: 100%;
//     padding: 0 var(--spacing-block);
// }

function Container({children, className, ...others}) {
    return <div className={clsx(className, "container")}>
        {children}
    </div>
}

Encounter CSS-in-JS

Diving into CSS-in-JS wasn't really a technical choice. My wife, as a UX designer, had good words about Material Design, so I headed to MUI without thinking too much. At that time, Emotion was the first-class citizen there. Meanwhile, my company's UI component library chose styled-components for styling. Both are widely used CSS-in-JS libraries.

Most CSS-in-JS solutions promised something compelling: styling information and UI logic in one place.

const Container = styled("div")({
    width: "100%", 
    padding: "0 var(--spacing-block)"
})

Everything felt smooth. Styling information and UI logic co-located in one file. React merges HTML and JS into JSX, and now CSS joined them. Style conflicts weren't a problem anymore—the CSS-in-JS library handled styling definition order on the fly.

Although many complained about CSS-in-JS performance, the web projects I worked on seldom reached the scale where performance became a concern, so I took the benefits for granted.

What CSS-in-JS taught me: Style encapsulation is powerful. Instead of defining global styles that can conflict anywhere, scoped styles help avoid pollution and save hours of debugging. The co-location principle also makes refactoring much easier.

The Server-Side Reality Check: Zero-Runtime CSS-in-JS

The honeymoon ended when I migrated my SPA to Next.js. Next.js offered App Router and RSC (React Server Components), and I wanted to embrace their benefits.

CSS-in-JS libraries manipulate stylesheets at runtime in the browser, making them fundamentally incompatible with server-side rendering. I had to awkwardly separate components—styling on the client, data fetching on the server. Working with component libraries required extra boilerplate to get things working.

I wasn't alone facing this issue. Zero-runtime CSS-in-JS promised to solve it. Solutions like Linaria and Pigment-CSS (MUI's Emotion successor) extract CSS at build time, generating static stylesheets while preserving the CSS-in-JS developer experience.

From a usage perspective, nothing changed:

const Container = styled("div")({
    width: "100%", padding: "0 var(--spacing-block)"
})

The magic happened during transpilation. CSS content gets extracted to static files, and class names are injected back into JavaScript.

This sounded promising—the webpack plugin would handle everything. After using it for a while, the main drawback was the debugging experience. The tool became essentially a black box. Error messages were cryptic and interfered with other tooling. This became worse in Next.js context (Yeah, another black box).

Important lesson learned: Don't make things that should be static dynamic. Don't sacrifice runtime performance for developer experience, especially when the build complexity trade-off isn't worth it.

The Eventual Leave

The breaking point came when integrating with the unifiedjs ecosystem. After 8 hours of removing code piece by piece to isolate a build error—with completely non-descriptive error messages—I gave up.

I can only describe the issue as "build-time interference between unified and Pigment-CSS." Maybe it was about server/client side bundling, maybe ESM/CommonJS module conflicts. I wasn't experienced enough to tell.

Maybe It's Time to Join Tailwind

Tailwind is likely the most popular CSS solution library. There are massive utilities and plugins built around it. Popular UI component libraries like shadcn/ui use Tailwind by default, making it even more popular. With so many good words, why not give it a try?

Tailwind Itself Is a Language

Tailwind is an abstraction layer upon CSS, built by experienced and smart CSS developers.

It's great! I learned a lot by studying how they structure CSS code. One excellent example: when defining color token CSS variables, instead of --my-color: rgb(0 0 0);, we can do --my-color: 0 0 0;. Then when consuming: color: rgb(var(--my-color) / 50%);, which gives us easier opacity control.

However, migrating from CSS-in-JS to Tailwind brought quite a learning curve. It took time to memorize class naming conventions—p-1 means padding: 4px, pseudo-class effects like &:hover .class become group-hover:<...>.

Initially I thought Tailwind was simple—just a huge predefined stylesheet. Actually, it's more complex then I expected. It utilizes PostCSS to perform tree shaking and collect arbitrary classes during build time. Extra learning was required beyond basic usage. For example:

Config theme tokens in tailwind.config.js and use them correctly.
Tailwind doesn't handle style conflicts by itself. To solve this, There is another NPM package to install tw-merge.
Dynamic styling is not native. They all have to be whitelisted in safelist inside tailwind.config.js, or just fall back to CSS variables.

What Tailwind taught me: Systematic design thinking and utility-first patterns. The constraint-based approach forced better design decisions and taught me about consistent spacing systems and color schemes.

The Backfire of Tailwind

The real issue was readability. Tailwind made applying styles extremely easy—too easy. I found myself writing class strings like below and it keeps growing.

"group-hover:text-foreground text-foreground/75 transition-colors duration-500 col-span-1 min-w-[33%] text-right lg:text-right"

These strings kept growing, containing layout, colors, hover states, responsive breakpoints—everything mashed together without structure or hierarchy, not even indentation. Reading this is like parsing a dense command line with multiple flags and options all crammed together.

It felt like inline styles with extra steps—and arguably less readable than inline styles because of the abbreviated syntax.

At meantime, I found my self duplicating some set of class name very often. Tailwind docs suggested creating my own utility classes, using @apply.

.my-typography {
    @apply group-hover:text-foreground text-foreground/75 transition-colors duration-500 col-span-1 min-w-[33%] text-right lg:text-right;
}

At this point, I realized I was just writing CSS with an abstraction layer on top. What was the benefit over vanilla CSS?

CSS Module, The Final Frontier

Both CSS-in-JS and Tailwind increase build-time complexity, and add extra abstraction layers. It gets worse that when the solution create issues that involve more tools on top of them.

I eventually returned to my old friend CSS—but not the poorly structured CSS I started with. The experiments with CSS-in-JS and Tailwind taught me valuable patterns and techniques:

CSS Modules come with challenges, and I can't find optimal solutions for everything:

Style conflicts is one. Although CSS class definitions are placed in reverse import order, problems still occur in Next.js when some pieces only appear in page but not layout CSS bundles. Following BEM (Block Element Modifier) and "Composition over Extension" patterns to separate concerns helps avoid styling collisions significantly.

Media query has limitations. @media(min-width: var(--breakpoint-lg)) won't work. PostCSS plugins support custom media query @custom-media --small-viewport (max-width: 30rem);, then @media (--small-viewport). Still duplications, but at least I can have breakpoints all defined in one file.

Ending

This round trip helped me form my tool selection principle: minimize build process interference. Every abstraction promises to solve problems but adds its own complexity.

The goal is never finding the "perfect" CSS solution, but choosing tools that align with your project's constraints. For me, that means keeping the build process simple and letting things do what they should do.

Sometimes the best path forward takes you back to where you started, armed with everything you learned along the way.

5 WTF Moments in Python

Zane Chen — Mon, 05 May 2025 23:27:10 +0000

1. It Is Not the Function I Called!

I encountered this issue when implementing the Decorator Pattern in python.

callbacks = [
    callback1,
    callback2,
    callback3,
]
wrapped = []

for callback in callbacks:
    def wrapped_callback(*args, **kwargs):
        print(f"{callback.__name__} is invoked.")
        callback(*args, **kwargs)

    wrapped.append(wrapped_callback)

for wrapped_cb in wrapped:
        wrapped_cb()

callback3 is invoked.
callback3 is invoked.
callback3 is invoked.

Surprised? This would likely break heads of developers famaliar with other languages. The rationale, however, is not complex. When defining function in Python, variables inside the closure are captured by reference, not by value. This means the values of callback in each wrapped_callback are resolved during execution time, not definition time. When the interpreter looks up the value of callback for each wrapped_callback, callback always holds the value of callback3, since it ended up with the value when exiting the loop.

To avoid this, simply avoid defining function inside loops.

callbacks = [
    callback1,
    callback2,
    callback3,
]

wrapped = []
def wrap_callback(callback):
    def wrapped(*args, **kwargs):
        print(f"{callback.__name__} is invoked.")
        callback(*args, **kwargs)

    return wrapped

for callback in callbacks:
    wrapped.append(wrap_callback(callback ))

for wrapped_cb in wrapped:
    wrapped_cb()

callback1 is invoked.
callback2 is invoked.
callback3 is invoked.

As a side note, be careful when using lambda functions in Python as well. They're convenient but can cause the same problem if used inappropriately.

funcs = [lambda: print(f"No.{i}") for i in range(3)]
for func in funcs:
    func()

No.2
No.2
No.2

2. Mutable Default Function Parameters Can Bite you

If you ever used default parameter in compiled languages like C#, the compiler forced the default value to be a compile time value. Although Python is an interpreted language, it still binds the default value at the function definition time, which means the default value got created only once. If the value is mutable and gets modified, subsequent calls will use the modified value.

def append_1_to_list(l = []):
    l.append(1)
    print(l)

append_1_to_list()  # [1]
append_1_to_list()  # [1, 1]

Solution? Avoid this pattern. If you really need this, make it default to None and intialize the value in function body.

3. “Finally” Is Literally Your Final Behavior

def will_throw():
    try:
        raise Exception()
    finally:
        return "Will you see me?"

will_throw() # 'Will you see me?'

Python silently eats the exception! This is more than confusing. I haven't found a satisfying explanation for why this happens. But the behavior here is that, the interpreter stores the error temporarily before the finally statement executed. If a return statement appears in finally, the exception will be discarded.

Similarly, finally is remarkably greedy, it will even discarded your previous return value if any.

def who_should_i_see():
    try:
        return "You should see me."
    finally:
        return "Will you see me?"

who_should_i_see()  # 'Will you see me?'

4. The Method Is not the Method

class MyClass:
    def the_method(self): pass

obj = MyClass()
obj.the_method is obj.the_method  # False

To understand this behavior, let's examine what happens under the hood when we use obj.the_method.

Instead of solving the puzzle directly, try answer another question, what is self meant for in the method parameter? We are taught that self representsthe object the method is bound to, which is why self doesn't appear in the method signature when we call methods on objects. Who fill the self parameter with the object? Magic, and it happened when the method is accessed or called.

This binding happens every time we access obj.the_method, creating a new method object from the function definition and the bound object every time. This explains why obj.the_method is obj.the_method evaluates to False.

While we won't dive deeper in this post, it's worth learning about this comprehensively. Python object attributes use something called Discriptor to control access behavior, which is where the magic happens. Then Python official doc is the best place to learn more.

5. True Is an Integer

isinstance(True, int)  # True
isinstance(True, bool)  # True

Surprise again! Booleans are integers! Both True and False and instances of both bool and int. You might wonder about the relationship between bool and int.

issubclass(bool, int)  # True
issubclass(int, bool)  # False

Yeah, bool is a subclass of int. It's hard to believe that a "modern language" would have this quirk, but remember that. But remember, Python is 32-year-old man, at least older than me. Python was created without a boolean type, just like old C, and developers historically use 0 and 1 instead. For the backward compatibility, bool became a subclass of int when it was introduced.