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

# 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

<Info>
  The skill follows the [Agent Skills](https://github.com/vercel-labs/skills) specification, making it compatible with OpenCode, Cursor, Claude Code, and other tools that support skill files.
</Info>

## Installation

### Using npx skills (recommended)

If you have the `skills` CLI installed:

```bash theme={null}
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](https://github.com/ericclemmons/agent-native/blob/main/skills/agent-native/SKILL.md)
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:

```bash theme={null}
cat skills/agent-native/SKILL.md >> .cursorrules
```

## What the skill provides

The skill teaches the AI agent:

### 1. Core workflow

```markdown theme={null}
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

```markdown theme={null}
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:

```markdown Structure theme={null}
---
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

```markdown theme={null}
## 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

```markdown theme={null}
## 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

```markdown theme={null}
## 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:

<Card title="agent-native/SKILL.md" icon="github" href="https://github.com/ericclemmons/agent-native/blob/main/skills/agent-native/SKILL.md">
  View the full skill source on GitHub
</Card>

You can also read it locally after installation:

```bash theme={null}
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:

````markdown skills/custom-automation/SKILL.md theme={null}
---
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:
   ```bash theme={null}
   agent-native key Slack "Yesterday: ... Today: ... Blockers: ..." return
   ```

## Screenshot and share

1. Capture Safari window:
   ```bash theme={null}
   agent-native screenshot Safari /tmp/screenshot.png
   ```

2. Paste into Slack:
   ```bash theme={null}
   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

<CardGroup cols={2}>
  <Card title="JSON output" icon="code" href="/ai/json-output">
    Learn about structured output for programmatic use
  </Card>

  <Card title="Best practices" icon="lightbulb" href="/ai/best-practices">
    Essential patterns for reliable automation
  </Card>
</CardGroup>