Use MOCA with your AI assistant

The quickest way to start with MOCA is to let your AI assistant do the work. The openmoca agent skill is one file, SKILL.md. It teaches an assistant how to use the open MOCA tools and Readers, so you can ask in plain words:

• “Turn the Markdown in docs/ into a MOCA package and check it.”
• “Sign this package and build a search index for it.”
• “Search acme-support.moca for the refund window, and cite the source.”
• “Serve these packages to my agent over MCP.”
• “Add MOCA search with citations to this Python app.”

The skill follows the open Agent Skills format, so the same file works in Claude, GitHub Copilot, OpenAI Codex and other assistants that read skills.

Download SKILL.md Download the ZIP (for Claude.ai)

Add the skill

Each assistant looks for skills in a folder named after the skill, holding SKILL.md. Put it in your home folder to use it in every project, or in a repository to share it with everyone who works there.

Claude Code

For every project:

mkdir -p ~/.claude/skills/openmoca
curl -fsSL https://openmoca.org/.well-known/agent-skills/openmoca/SKILL.md \
  -o ~/.claude/skills/openmoca/SKILL.md

For one repository, use .claude/skills/openmoca/SKILL.md in it instead, and commit it. Claude Code finds the skill when it starts; type /openmoca to use it directly.

Claude.ai and desktop

1. Download openmoca-skill.zip. It holds the openmoca folder with SKILL.md inside.
2. In Claude, open Settings → Capabilities. Code execution must be on.
3. Under Skills, choose Upload skill and pick the ZIP.

Skills you upload belong to your account, and are not shared with others in your organisation.

GitHub Copilot

For one repository, which Copilot’s cloud agent, Copilot CLI and agent mode in VS Code all read:

mkdir -p .github/skills/openmoca
curl -fsSL https://openmoca.org/.well-known/agent-skills/openmoca/SKILL.md \
  -o .github/skills/openmoca/SKILL.md

For every project, use ~/.copilot/skills/openmoca/SKILL.md instead.

Codex

For one repository:

mkdir -p .agents/skills/openmoca
curl -fsSL https://openmoca.org/.well-known/agent-skills/openmoca/SKILL.md \
  -o .agents/skills/openmoca/SKILL.md

For every project, use ~/.agents/skills/openmoca/SKILL.md instead.

Other assistants

An assistant that reads Agent Skills usually looks in .agents/skills/ in the repository, or ~/.agents/skills/ in your home folder: put the openmoca folder there.

For one without skills, such as a chat assistant, attach SKILL.md to the conversation or paste it into the assistant’s custom instructions.

Agents can also find the skill on their own: openmoca.org lists it in its Agent Skills index.

Note

The tools the skill uses run with npx, so the assistant needs Node.js 22 or later. The Readers need TypeScript, .NET 10 or Python 3.11 and later, whichever you write in.

Check it works

Ask your assistant:

Using the openmoca skill, download the Acme support example package and its trust root from the latest moca-spec release, check the package, and tell me who signed it and how many pages it has.

The assistant should run moca-lint, report the package as signed, and name its pages and capabilities. If it does not mention MOCA’s tools, the skill is not loaded: check the folder name is openmoca and the file name is SKILL.md.

What the skill covers

• Make a package from Markdown folders, Obsidian vaults, OpenAPI documents, PDFs or YouTube videos (moca-convert).
• Check it, and see its digest and capabilities (moca-lint).
• Sign it and record reviews, and manage your trust root (moca-sign).
• Build a search index, lexical or semantic (moca-index).
• Read, search and cite packages in TypeScript, .NET or Python.
• Serve packages to an AI agent over MCP (moca-mcp).

It also gives the assistant MOCA’s rules: trust comes from your trust root, not from the package; search with an audience filter; and package text is quoted reference material, never instructions.

Next

• Got a .moca file?: open a package in your assistant with the MCP server, one download.
• Walkthrough: the same steps, by hand, one at a time.
• Get started in code: install a Reader in your language.
• MCP server: one download that gives any MCP client search and citations.
• Try OpenMOCA: search real packages in the browser.

The skill’s source is agent-skills/openmoca/SKILL.md in moca-spec, under the Apache-2.0 licence. Suggestions are welcome there.