Using the Traverse OPML Agent Skill

The Traverse OPML Agent Skill gives compatible AI agents instructions for creating, inspecting, and safely editing Traverse outlines. It explains the parts of the OPML format that are specific to Traverse, including stable identifiers, metadata, custom attributes, Type, Fountain, tasks, links, numbering, and hierarchy.

The skill download is a Traverse Pro resource. It is available inside Traverse to people with an active Pro subscription or lifetime purchase.

Built-in AI and the Agent Skill

Traverse Pro already includes a focused Generate with AI feature on supported Macs with Apple Intelligence enabled. It uses Apple's on-device model to turn a prompt into an editable starting outline, with optional Fountain formatting for film and screenplay work.

Generate with AI is designed for a new blank outline. It does not inspect or revise an existing document, search your library, or work across several files.

The Agent Skill is different. It teaches an external, file-capable agent how to work with the OPML documents that you deliberately make available to it. And of course, you can also have it create brand new Traverse outlines too. The agent and its permissions are provided by a third-party product such as Codex, Claude Code, Cursor, GitHub Copilot, or Gemini CLI.

What the skill helps an agent understand

A general-purpose agent may understand XML without understanding the meaning Traverse gives to it. The skill instructs the agent to:

Preserve existing document and node identifiers.
Identify nodes by their traverse-id rather than relying on titles that may not be unique.
Preserve unknown metadata and attributes instead of simplifying the file.
Maintain hierarchy and sibling order unless the requested change requires them to move.
Preserve notes, URLs, marks, task state, numbering choices, timestamps, and document settings.
Create valid internal traverse:// links.
Keep native task fields in agreement when completing or reopening a task.
Define custom attributes before adding their values and avoid reserved internal keys.
Use well-formed XML, validate the result, and make the smallest requested change.

For Type, the agent understands Body, Heading, Blockquote, Code block, Bullet, Numbered bullet, Divider, and standalone Note nodes. It can build a semantically structured document without storing Markdown punctuation merely to imitate the eventual export.

For Fountain, it understands sections, scene headings, action, synopsis, notes, characters, dialogue, parentheticals, lyrics, transitions, centred text, page breaks, and shots. It also knows that Dialogue, Parenthetical, and Lyrics nodes normally belong directly beneath a Character node.

See Smart typing with Type and Fountain for the corresponding features inside Traverse.

What you can do with it

The exact possibilities depend on the agent and the files you allow it to access. Examples include:

Create a new outline: Build a project plan, research map, course outline, meeting structure, checklist, or reusable document from a description.
Turn source material into OPML: Restructure notes, Markdown, plain text, or a transcript as an editable Traverse outline.
Develop a Type document: Create or revise an article, report, or documentation outline using semantic Type roles.
Develop a Fountain document: Turn a treatment into acts, scenes, synopsis nodes, characters, dialogue, and other screenplay elements.
Edit existing work: Add material, move a branch, update task state, or define and apply custom attributes while preserving unrelated content.
Review without editing: Find duplicate identifiers, invalid links, inconsistent task state, undefined custom attributes, incomplete tasks, or recurring themes across several outlines.

Useful requests include:

Use the Traverse OPML skill to turn these research notes into a Type-based outline. Preserve every source URL.
Move the unresolved questions beneath Further work. Do not change any other branches, IDs, or attributes.
Create a Fountain outline from this treatment. Put dialogue and parentheticals beneath their Character nodes.
Review these Traverse files for duplicate node IDs, invalid internal links, and inconsistent task state. Report the findings without changing anything.

Download the skill

Open Traverse.
Choose Traverse > Settings.
Select the AI tab.
Under Agent Skills, click Download Skills Folder.
Choose where to save traverse-opml.zip.

The Download Skills Folder button is inactive unless Traverse currently has an active Pro unlock. The skills file may evolve over time so check the last updated date at regular intervals to ensure you are working with the latest version.

Expand the ZIP and keep the complete traverse-opml folder together. Its main file is SKILL.md; the agents folder contains optional display information for agents that support it.

For each installation location below, move the downloaded traverse-opml folder into the parent skills directory. For example, moving it into ~/.agents/skills/ leaves the main file at ~/.agents/skills/traverse-opml/SKILL.md.

Install for OpenAI Codex

For a personal installation, use ~/.agents/skills/. For a repository-specific installation, use .agents/skills/ within the repository. Codex detects skill changes automatically; restart it if the skill does not appear.

Codex can choose the skill when a request clearly involves Traverse OPML, or you can invoke it explicitly with $traverse-opml. For example: Use $traverse-opml to create a Type-based Traverse outline from these notes.

See OpenAI's Build skills documentation.

Install for Claude Code

For a personal installation, use ~/.claude/skills/. For a project-specific installation, use .claude/skills/. Claude Code can choose the skill automatically or you can invoke it with /traverse-opml.

See Anthropic's Extend Claude with skills documentation.

Install for Cursor

For a personal installation, use ~/.cursor/skills/ or ~/.agents/skills/. For a project-specific installation, use .cursor/skills/ or .agents/skills/. Cursor can load a relevant skill automatically or let you select /traverse-opml in Agent chat.

See the Cursor Agent Skills documentation.

Install for GitHub Copilot in VS Code

For a personal installation, use ~/.copilot/skills/ or ~/.agents/skills/. For a repository-specific installation, use .github/skills/ or .agents/skills/.

Open Copilot Chat in Agent mode and use /skills to view the available skills. See the VS Code Agent Skills documentation.

Install for Gemini CLI

For a personal installation, use ~/.gemini/skills/ or ~/.agents/skills/. For a workspace-specific installation, use .gemini/skills/ or .agents/skills/.

Inside Gemini CLI, use /skills reload after installation and /skills list to check that the skill was discovered. Gemini may ask for permission when it activates a skill. See the Gemini CLI Agent Skills guide.

Agents without installable skills

If an agent does not support a persistent skill folder, attach SKILL.md alongside the OPML file and ask it to follow those instructions. A chat-only agent may be able to review an uploaded outline or generate a new file for you to download, but it may not have the tools or permissions needed to work directly with files on your Mac.

Give the agent access deliberately

Installing the skill does not give an agent automatic access to your Traverse library. You still decide which files or folders it can see and whether it may make changes.

For a first test, use a copy of an outline rather than an important live document. When working with a live library:

Name the document or files that are in scope.
Say whether you want a review, a proposed plan, or an actual edit.
Avoid editing the same document simultaneously in Traverse and another tool.
Review any conflict or reload message shown by Traverse.
Ask the agent to summarise the files and branches it changed.
Keep normal backups and review important changes in Traverse.

See Library, OPML files, and importing for more about how Traverse stores documents, and Free and Pro for the features included with each level.