Plugin developer guide

Ship Agent Skills to Claude Code, Codex and other runtimes

By HOL · Reviewed by Michael Kantor on

Direct answer

Put each skill in its own folder with a SKILL.md whose frontmatter has a name and a description, then run hol-guard plugin check to catch missing frontmatter before a runtime ignores the skill. hol-guard plugin package --runtimes claude-code,codex,agent-skills writes a Claude Code plugin, a Codex plugin and the plain skills/<name>/ layout that skills installers read. MCP-only runtimes such as Cursor do not load skills.

Who this is for

Authors of Agent Skills who want the same skills installable in Claude Code, Codex and skills installers.

Good fit

  • A repository of standalone skills with no plugin manifest
  • A Claude Code plugin whose skills should also install in Codex
  • A team publishing skills that the Skills CLI can install

Not a fit

  • Runtimes that only read MCP config, such as Cursor, VS Code and OpenCode
  • Skills that depend on Claude Code hooks or subagents to work

Steps

  1. 1.Install HOL Guard

    The Plugin Kit ships inside HOL Guard 3.57 and newer. It needs Python 3.10 or newer and pipx. If Guard is already installed, upgrade it, then check that hol-guard --version reports 3.57 or newer.

    pipx install hol-guard
pipx upgrade hol-guard
hol-guard --version

  2. 2.Write the skill frontmatter

    Each SKILL.md starts with YAML frontmatter. Agents pick a skill by its description, so say when to use it, not only what it is.

    ---
name: pdf-tools
description: Use when the user asks to read, split or merge PDF files.
---

  3. 3.Check the skills

    The check lists every skill it found and fails when a SKILL.md has no frontmatter or no description. Starting from an empty folder, hol-guard plugin init --name my-skills scaffolds a minimal plugin with one skill.

    hol-guard plugin check .

  4. 4.Package the skills

    The Agent Skills output copies each skill to skills/<name>/. The Claude Code and Codex outputs wrap the same skills in each runtime's plugin manifest.

    hol-guard plugin package . --runtimes claude-code,codex,agent-skills --out dist/hol-plugin

  5. 5.Install from GitHub

    Once the repository is public, hol-guard plugin links prints the install commands, including the skills installer command for your repository.

    hol-guard plugin links .
npx [email protected] add your-org/your-skills

  6. 6.Connect the repository on HOL

    Open the connect page with your repository to verify ownership and claim the listing. hol-guard plugin links prints the same link with your repository filled in. Installing the Guard GitHub App on the repository verifies its listings automatically.

    hol-guard plugin links .

Where skills load

Source or runtimeOutputCarriesDrops
Claude Code.claude-plugin/plugin.json with skills/SkillsNothing
Codex.codex-plugin/plugin.json with skills/SkillsNothing
Agent Skills layoutskills/<name>/SkillsMCP servers
Cursor, VS Code, OpenCode, Gemini CLIMCP config onlyMCP serversSkills

Limitations

  • The Kit checks frontmatter and layout. It does not judge whether a skill's instructions work well.
  • Skills that call scripts still need those scripts to run on the user's machine.
  • A listing or a passing check is not a safety guarantee.

Questions

Do I need a plugin manifest to publish skills?

No. The Kit detects any SKILL.md with name and description frontmatter. Packaging for Claude Code or Codex writes the manifest for you.

Why does Gemini CLI not get my skills?

The Gemini CLI extension output carries MCP servers and a context file. The check lists skills as dropped for that runtime so the gap is visible before you publish.

Will packaging overwrite my existing skills folder?

No. The Kit writes to the output folder, refuses a non-empty one unless you pass --force, and never reads its own output back as source.

Sources

Related guides

List it on HOL

Connect the repository to verify ownership and claim the listing. New plugins can be submitted for free.

Connect your skills repository