OpenCode skill

Pre-built skill file for integrating agent-native with OpenCode and other AI coding assistants

What is the OpenCode skill?

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. It provides:

• Core workflow patterns (snapshot → interact → re-snapshot)
• Command reference with examples
• Best practices for reliable automation
• Common patterns for different app types

The skill follows the Agent Skills specification, making it compatible with OpenCode, Cursor, Claude Code, and other tools that support skill files.

Installation

Using npx skills (recommended)

If you have the skills CLI installed:

npx skills add ericclemmons/agent-native

This installs the skill globally so it’s available in all your projects.

Manual installation

You can also add the skill manually to your project:

1. Create a skills/ directory in your project or home directory
2. Download the skill file from the agent-native repository
3. Place it in skills/agent-native/SKILL.md

For OpenCode

OpenCode automatically discovers skills in:

• ~/.config/opencode/skills/
• ./skills/ (project-local)

Place the agent-native skill folder in either location.

For Cursor

Add the skill content to your .cursorrules file:

cat skills/agent-native/SKILL.md >> .cursorrules

What the skill provides

The skill teaches the AI agent:

1. Core workflow

Workflow: snapshot -> read refs -> interact by ref -> re-snapshot

agent-native open "System Settings"
agent-native snapshot "System Settings" -i    # Get interactive elements with @refs
agent-native click @n5                        # Interact using refs
agent-native snapshot "System Settings" -i    # Re-snapshot after UI changes

2. Command patterns

The skill includes all major commands with examples:

• Navigation: open, apps
• Inspection: snapshot, tree, find, inspect
• Interaction: click, fill, type, check, uncheck, select, focus, hover
• State reading: get text, get value, is enabled, is focused
• Keyboard: key, paste
• Screenshots: screenshot
• Waiting: wait

3. Electron app handling

Electron apps expose a minimal AX tree. When `snapshot -i` returns very few elements:

1. Use `key` for keyboard shortcuts:
   agent-native key Slack cmd+k
   agent-native key Slack "channel name" return

2. Use `screenshot` for visual aid

3. Use window title to confirm state:
   agent-native get title Slack

4. Best practices

• Always use -i with snapshot for interactive elements only
• Re-snapshot after navigation — old refs may not resolve
• Use --json for structured output when parsing in code
• Fall back to keyboard when AX tree is sparse

Usage with OpenCode

Once installed, OpenCode automatically knows how to use agent-native:

You: Toggle Wi-Fi off in System Settings

OpenCode: I'll use agent-native to control System Settings.

[Runs: agent-native open "System Settings"]
[Runs: agent-native snapshot "System Settings" -i]
[Parses output, finds Wi-Fi button at @n3]
[Runs: agent-native click @n3]
[Waits for navigation]
[Re-snapshots, finds Wi-Fi checkbox at @n8]
[Runs: agent-native uncheck @n8]

Done! Wi-Fi is now disabled.

Usage with Cursor

With the skill in .cursorrules, Cursor will:

1. Know to use agent-native for macOS app automation tasks
2. Follow the snapshot → interact → re-snapshot pattern
3. Handle errors and re-snapshot when needed
4. Fall back to keyboard shortcuts for Electron apps

Usage with other tools

Any AI coding assistant that supports:

• Shell command execution (runs agent-native commands)
• Instruction files (reads SKILL.md or similar)
• Multi-step reasoning (breaks tasks into steps)

can use the agent-native skill effectively.

Skill file structure

The skill file has these sections:

Structure

---
name: agent-native
description: When to use this skill
---

# agent-native

## Prerequisites
- What's needed to run agent-native

## Core Workflow
- The snapshot -> interact -> re-snapshot pattern

## Commands
- All commands organized by category
- Examples for each command
- Flags and options

## Tips
- Best practices
- Common patterns
- Electron app handling

Customizing the skill

You can customize the skill for your specific use cases:

Add project-specific patterns

## Custom: Our Slack workflow

1. Open Slack: `agent-native open Slack`
2. Switch to #general: `agent-native key Slack cmd+k "general" return`
3. Post message: `agent-native key Slack "message text" return`

Add app-specific shortcuts

## Custom: Figma shortcuts

- New frame: `agent-native key Figma cmd+opt+g`
- Export: `agent-native key Figma cmd+shift+e`
- Toggle grid: `agent-native key Figma cmd+'

Override default behavior

## Custom: Always use compact snapshots

For our project, always use:
`agent-native snapshot <app> -i -c`

The `-c` flag removes empty structural elements for cleaner output.

Viewing the skill source

The complete skill file is available at:

agent-native/SKILL.md

View the full skill source on GitHub

You can also read it locally after installation:

cat ~/.config/opencode/skills/agent-native/SKILL.md
# or
cat skills/agent-native/SKILL.md

Example: Teaching custom workflows

Create a project-specific skill that extends the base agent-native skill:

skills/custom-automation/SKILL.md

---
name: custom-automation
description: Custom macOS automation workflows for our team
---

# Custom Automation Workflows

Extends the agent-native skill with team-specific patterns.

## Daily standup in Slack

1. Open Slack and navigate to #standup:
   ```bash
   agent-native open Slack
   agent-native key Slack cmd+k "standup" return

2. Post standup message template:
   agent-native key Slack "Yesterday: ... Today: ... Blockers: ..." return
   

Screenshot and share

1. Capture Safari window:

   agent-native screenshot Safari /tmp/screenshot.png
   

2. Paste into Slack:

   agent-native paste Slack /tmp/screenshot.png
   

<Tip>
Project-specific skills help AI agents learn your team's workflows and conventions.
</Tip>

## Troubleshooting

### Skill not recognized

If the AI agent doesn't seem to know about agent-native:

1. **Check skill location**: Ensure the skill is in the correct directory
2. **Restart the agent**: Some tools require restart to pick up new skills
3. **Explicitly mention it**: Say "Use the agent-native skill to..."

### Agent not following patterns

If the agent uses agent-native incorrectly:

1. **Remind about re-snapshotting**: "Remember to re-snapshot after clicking"
2. **Point to skill section**: "Follow the Electron app patterns from the skill"
3. **Show an example**: Demonstrate the correct pattern once

### Skill outdated

To update the skill:

```bash
# Remove old version
rm -rf ~/.config/opencode/skills/agent-native

# Reinstall latest
npx skills add ericclemmons/agent-native

Next steps

JSON output

Learn about structured output for programmatic use

Best practices

Essential patterns for reliable automation