Teaching Agents to Click: Inside opencode-skill

How a standardized Markdown package turns headless AI models into OS-level operators.

6 min read • View on GitHub • More from ericclemmons

A traditional wooden shipping crate pried open. Instead of gears or mechanical parts inside, it contains a glowing, perfectly structured manuscript being scanned by a mechanical eye on a multi-jointed arm. This represents the shift from installing code packages to installing structured knowledge for AI agents. — The transition from code-packages to knowledge-packages represents a fundamental shift in how we extend development environments.

Key Takeaways

The opencode-skill repository represents a shift from traditional package management to installing structured context for AI agents.
It defines a strict 'See-Do-See' loop that allows headless models to interact with complex OS interfaces without direct DOM access.
By enforcing boundaries through YAML frontmatter, the skill prevents AI hallucinations and ensures OpenCode-specific solutions are only applied when necessary.

The Knowledge Package Manager

For decades, developers used tools like npm to install executable code for compilers. We pulled down libraries, frameworks, and utilities to build our applications. The opencode-skill repository represents the next evolution: installing structured knowledge for AI agents. It is an operating manual written explicitly for non-human consumption.

This is the "Agent-in-an-Agent" pattern realized in a single Markdown repository. When a developer runs npx skills add, they aren't downloading executable code. They are downloading a "brain plugin" that teaches an AI how to break out of the terminal and directly manipulate a computer's operating system UI.

The See-Do-See Loop

The core of the opencode-skill is the technical workflow it teaches the AI. It replaces the traditional DOM-based interaction model with a spatial, visual approach. This is critical for navigating standard OS interfaces and Electron apps, which often expose minimal accessibility trees.

The four-step cycle that allows an AI to interact with a GUI without traditional DOM access.

The AI follows a strict cycle: snapshot -> read refs -> interact by ref -> re-snapshot. It captures the current screen state, parses the accessibility tree into actionable coordinates, executes a click or keystroke, and then verifies the state change. This is how a headless model learns to click.

The agent-native OpenCode skill is a pre-written instruction file that teaches AI coding assistants (OpenCode, Cursor, Windsurf, etc.) how to use agent-native effectively.

Documentation, Project Documentation · OpenCode skill - agent-native

Defining Boundaries of Competence

The intelligence of opencode-skill lies not just in what it teaches the AI to do, but in what it explicitly forbids. The repository's structure is optimized for LLM consumption, with SKILL.md acting as the primary orchestrator.

name: opencode
description: Reference for OpenCode... Use when the user asks about OpenCode CLI commands...
# Explicitly do NOT use for general coding tasks.

By using YAML frontmatter to establish strict boundaries of competence, the skill prevents the AI from hallucinating OpenCode-specific solutions for generic problems. It ensures the context is only applied when the developer is actually working within the OpenCode ecosystem.

WSJ hedcut-style portrait of Eric Clemmons, the creator of opencode-skill.

The Standardization of AI Context

To understand the significance of opencode-skill, we must look at the broader landscape. It is built on the Agent Skills Standard, an open format that is rapidly gaining traction across the industry.

The Agent Skills Standard is an open format originally developed by Anthropic for giving AI agents reusable capabilities. Released as an open standard at agentskills.io, it’s since been adopted by 12+ platforms including Claude Code, OpenCode, GitHub Copilot, Cursor, VS Code, Gemini CLI, and OpenAI Codex.

JP Caparas, Author · Anatomy of an Excellent OpenCode Skill

A split composition. On the left, a human developer is surrounded by messy stacks of thick, dog-eared reference manuals. On the right, a sleek robotic brain directly absorbs a single, perfectly formatted punch card. This contrasts traditional human documentation with streamlined, structured LLM context. — The shift from human-readable reference manuals to machine-consumable context modules.

While skills like the cloudflare-skill focus on deep API integration, managing hundreds of cloud bindings, opencode-skill is focused on OS-level interaction. It is the difference between giving an AI a remote control and giving it a physical pair of hands.

The pressure is mounting on core platforms to build these capabilities natively. As one user noted on the OpenCode repository:

So today OpenCode is better at **discovering** these objects than **self-guiding their creation**.

LanternCX, Issue Author · [FEATURE]: Add a built-in using-opencode skill

Until these platforms mature to feature parity with advanced standards, third-party skills like opencode-skill will serve as the crucial bridge, turning headless AI models into capable OS operators.