backend-pr-workflow

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