Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/ericclemmons/agent-native/llms.txt

Use this file to discover all available pages before exploring further.

​
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

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
  1. 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

Build docs developers (and LLMs) love

Get started for freeTalk to us