Documentation

Build and maintain Agentic Tools

19 plugins, 21 plugin skills, 2 Pi-local skills, and 5 pi packages. This page focuses on repo structure, authoring rules, command wrappers, and release checks.

Need the public overview first? Start on the Agentic Tools page. Need a specific plugin or package? Jump to the registry. This page is the maintainer guide for working in the open-source repo.

Agentic Tools Overview Browse Registry Open CONTRIBUTING.md
Repository Shape

Where each layer lives

Skills are the instruction files, plugins are the Claude Code distribution units, and pi packages are Pi-native extensions. Each layer has a distinct directory shape.

The repo is configuration-first. Most edits happen in plugins/<plugin>/skills/, plugins/<plugin>/commands/, .claude-plugin/marketplace.json, and pi-packages/<package>/.

Skills Markdown instructions in SKILL.md.
Plugins Claude Code bundles: manifest + skills + slash-command wrappers.
Pi packages Pi-native extensions, local skills, tools, and TUI behavior.
repo-tree.txt 
.claude-plugin/marketplace.json
plugins/monty-code-review/
  .claude-plugin/plugin.json
  commands/code-review.md
  commands/test-hardening.md
  skills/monty-code-review/SKILL.md
  skills/monty-code-review/references/
  skills/monty-code-review/scripts/
pi-packages/dev-workflow/
  package.json
  README.md
  extensions/dev-workflow/
  skills/dev-workflow/SKILL.md
docs/
scripts/validate-skills.sh
SKILL.md

Write the skill first

The skill body is the source of truth. Command wrappers stay thin and distribution metadata stays in manifests.

plugins/repo-docs/skills/repo-docs-generator/SKILL.md 
---
name: repo-docs-generator
description: "Generate repository harness docs: a short AGENTS.md map, README.md, CLAUDE.md stub, and repo-local docs that make the codebase legible to agents."
---

# Repo Docs Generator

## When to Use This Skill
- Add or refresh repo-local harness docs
- Replace tribal knowledge with docs and guardrails
  • Required frontmatter : At minimum, keep name and description accurate and machine-readable.
  • Portable instructions : Put durable behavior in SKILL.md, not in a command wrapper or repo-only tribal knowledge.
  • 500-line budget : Move deep procedures into references/ and reusable helpers into scripts/.
  • Quote special YAML strings : Frontmatter with colons, commas, brackets, or quotes should be quoted.
  • Keep docs nearby : If the workflow changes, update the focused docs in docs/ instead of bloating CLAUDE.md.
Slash Commands

Wrappers are thin and namespaced

Every Claude Code skill needs at least one wrapper in plugins/<plugin>/commands/. The wrapper provides task-specific entrypoints; the real behavior stays in the skill.

plugins/monty-code-review/commands/code-review.md 
---
description: Hyper-pedantic backend Django code review using the monty-code-review Skill.
---

Use your `monty-code-review` Skill to perform a full backend Django code review
of the current change (PR, diff, or working tree), following the workflow,
severity tags, and checklists defined in its SKILL.md.
  • Location: plugins/<plugin>/commands/*.md
  • Convention: wrapper file names become Claude Code commands like /monty-code-review:code-review
  • One skill, many wrappers: a single skill can back multiple task-focused entrypoints
  • No duplication: do not paste the whole skill into the wrapper
  • Codex is different: Codex installs the skill directory directly and invokes with name: <skill-name>
Deep Docs

Browse by skill or Pi extension

Go deeper than bundle summaries: 21 plugin skills, 2 Pi-local skills, and 5 Pi extension pages now have dedicated docs.

Skills 23 pages

Individual skill docs cover when to use a skill, related commands, source paths, references, scripts, and runtime-specific invocation.

Browse Skill Docs
Pi Extensions 5 pages

Pi package docs focus on extension commands, LLM tools, environment variables, packaged skills, and extension file layout.

Browse Pi Docs
Docs Pipeline

How docs become pages

The high-level pages explain bundles, while the deeper routes explain individual skills and Pi extension surfaces. Those pages are generated from the repo’s real docs instead of a second website-only schema.

docs-pipeline.txt 
plugins/*/skills/*/SKILL.md        ─┐
pi-packages/*/README.md           ├─> src/data/site-docs.ts ──> /skills/* and /pi/* pages
pi-packages/*/skills/*/SKILL.md   ─┘

src/data/marketplace.json         ───────────────────────────> cards, counts, summaries
  • One source of truth: skill behavior still lives in SKILL.md; Pi extension behavior still lives in each package README.
  • Website pages are extracted views: src/data/site-docs.ts turns those repo files into structured data for /skills/* and /pi/*.
  • Why this matters: maintainers update the same repo docs they already own, then rebuild the site.
  • Keep it explainable: the extraction logic is deliberately conservative. If a page looks wrong, fix the source docs first, then teach the extractor the new pattern.

Maintainer rule of thumb: if you add or reshape a skill, edit the canonical markdown first, then confirm the generated deep docs.

bash 
# after changing SKILL.md, README.md, or commands
cd website
npm run build

# then smoke-check the new deep docs
open http://localhost:4321/skills
open http://localhost:4321/pi
Distribution

How the same repo reaches three runtimes

The same underlying content reaches Claude Code, Codex, and Pi through different installation surfaces.

Claude Code plugin bundle

Install a plugin, then invoke its namespaced slash commands inside Claude Code.

bash 
claude plugin marketplace add DiversioTeam/agent-skills-marketplace
claude plugin install repo-docs@diversiotech
/repo-docs:generate
Codex skill directory

Install one or more exact skill paths from GitHub, then invoke each skill by name.

bash 
CODEX_HOME="${CODEX_HOME:-$HOME/.codex}"
python3 "$CODEX_HOME/skills/.system/skill-installer/scripts/install-skill-from-github.py" \
  --repo DiversioTeam/agent-skills-marketplace \
  --path plugins/repo-docs/skills/repo-docs-generator

name: repo-docs-generator
Pi package install

Pi packages extend the harness directly. The skills-bridge package auto-discovers plugin skills and exposes them inside Pi. See pi.dev for the Pi project.

bash 
pi install git:github.com/DiversioTeam/agent-skills-marketplace
/reload

# skills-bridge makes plugin skills available in Pi
Validation

Run the guardrails before opening a PR

Some docs-only changes do not trigger every workflow, so run the matching local checks when you touch shared instructions or metadata.

bash 
bash scripts/validate-skills.sh
bash scripts/validate-skills.sh --all
jq -e . .claude-plugin/marketplace.json >/dev/null
jq -e . plugins/<plugin>/.claude-plugin/plugin.json >/dev/null
jq -e . pi-packages/<package>/package.json >/dev/null
printf '{"id":"cmds","type":"get_commands"}\n' | \
  PI_OFFLINE=1 pi --mode rpc --no-session --no-context-files --no-extensions \
  -e ./pi-packages/<package> --no-prompt-templates --no-skills
  • Version sync: plugin versions must match in plugins/<plugin>/.claude-plugin/plugin.json and .claude-plugin/marketplace.json
  • Structure sync: every changed skill should still have at least one wrapper
  • Package sync: keep package.json, package README files, and install docs aligned for pi packages
  • Skill size: changed SKILL.md files must stay at or below 500 lines
  • Fresh-eyes pass: after substantive edits, review adjacent docs and metadata for drift
Contribute

Contribute safely

Recommended flow: skill, wrapper, manifest sync, validation, PR.

  • Write SKILL.md : YAML frontmatter + Markdown. The skill is the canonical instruction file.
  • Add a thin wrapper : Create at least one command file in plugins/<plugin>/commands/.
  • Bump synced versions : Update the plugin manifest and the top-level marketplace manifest together.
  • Validate locally : Run validate-skills, jq checks, and Pi smoke tests when packages change.
  • Open a GitHub PR : Contribution review happens in the main repository on GitHub.

Keep the focused docs in sync when behavior changes: catalog, distribution runbook, and README.