agent-skills-marketplace
Agent Skills marketplace for Diversio.
Agent Skills Standard
This repo follows the Agent Skills standard: an
open, tool-agnostic format for packaging capabilities and workflows for agents.
A skill is a directory with a required SKILL.md that contains YAML frontmatter
(name, description) and Markdown instructions, plus optional scripts/,
references/, and assets/.
Key points from the standard:
SKILL.md is required and starts with YAML frontmatter.name must match the skill directory and use lowercase letters, numbers, and hyphens.description should explain what the skill does and when to use it.- Optional frontmatter fields include
license, compatibility, metadata, and experimental allowed-tools (space-delimited string).
- Keep
SKILL.md focused; link to longer guidance in references/ or helpers in scripts/.
Skills are designed for progressive disclosure: agents read metadata first,
load the full SKILL.md when invoked, and open references/ or scripts/
only if needed.
Compatibility (Codex + Claude Code)
To keep Skills portable across both OpenAI Codex and Claude Code:
- Prefer only
name + description in YAML frontmatter; treat other fields as optional/ignored by many runtimes.
- Keep
description single-line and ≤500 chars (Codex validates this at startup).
- Avoid
anthropic/claude in Skill names and don’t include XML tags in name/description (Claude).
- Keep
SKILL.md reasonably small (≈<500 lines); move deep docs into references/.
SKILL.md Size Guardrail (CI-Enforced)
To keep Skills reliable and LLM-friendly, treat SKILL.md as an orchestrator, not a dump:
- Hard limit: each changed
SKILL.md in a PR/push must stay at or below 500 lines (CI fails above this).
- Keep only activation workflow, core priorities, and output contract in
SKILL.md.
- Move long procedures/examples into
references/*.md.
- Move reusable command logic into
scripts/.
- Keep reference depth shallow (one level deep where possible) for progressive disclosure.
Run the guard locally before opening a PR:
bash scripts/validate-skills.sh
This default mode validates changed and untracked SKILL.md files in your working tree.
Use bash scripts/validate-skills.sh --all for a full-repo audit.
Working on Skills (LLM checklist)
- Start with
AGENTS.md (source of truth); CLAUDE.md only includes it.
- Required structure:
plugins/<plugin>/skills/<skill-name>/SKILL.md with YAML frontmatter (name, description).
- Ensure the skill directory name matches
name and stays in kebab-case.
- Add or update a corresponding
plugins/<plugin>/commands/*.md entrypoint.
- Keep
SKILL.md focused; put deep docs in references/ and helpers in scripts/.
- After substantive edits, do a fresh-eyes self-review of the changed skill,
adjacent commands/docs, and version metadata, then fix obvious issues before
stopping.
- If you change a plugin, bump its version in
plugins/<plugin>/.claude-plugin/plugin.json
and keep .claude-plugin/marketplace.json in sync.
Overview
This repository hosts Diversio-maintained Agent Skills and plugin manifests so
the same skills can be distributed via the Claude Code marketplace or other
channels.
Documentation Philosophy
The repo-docs plugin is now explicitly informed by OpenAI's February 11,
2026 article Harness engineering: leveraging Codex in an agent-first
world.
The practical takeaway for this repo is:
- Keep
AGENTS.md as a short routing map, not a giant handbook.
- Put durable detail in focused repo-local docs.
- Treat repeated failures as harness gaps to encode in docs, wrappers, or CI.
Repository Structure