Imported from analyticalmonk/explain-this (AGENTS.md). Install upstream with npx skills add analyticalmonk/explain-this. Copyright stays with the author.

Repository Guidelines

Project Structure & Module Organization

This repository is a Claude Code and Codex plugin plus Agent Skills package. Plugin metadata lives in .claude-plugin/ for Claude Code and .codex-plugin/plugin.json for Codex. The three skills live under skills/<skill-name>/SKILL.md; keep that layout flat (one skill folder per name, SKILL.md directly inside) - it is what the skills.sh CLI (npx skills add) and OpenClaw discover. Codex UI metadata lives in skills/*/agents/openai.yaml. Deeper guidance is kept in skills/*/references/, and reusable article scaffolding is in skills/creating-explainers/assets/article-template.html. Human-facing installation and usage docs are in README.md, while CLAUDE.md captures maintainer guidance for Claude Code. Planning and design notes belong in docs/, and evaluation prompts are centralized in evals/evals.json.

Build, Test, and Development Commands

There is no package manager, build step, or dependency install for this repo. Useful local commands are:

• rg "term" skills docs README.md - search skill and documentation content.
• python3 -m http.server 8000 - serve a generated explainer directory that contains index.html for browser inspection.
• python3 /home/analyticalmonk/.codex/skills/.system/plugin-creator/scripts/validate_plugin.py . - validate Codex plugin metadata.
• git diff --check - catch whitespace issues before committing.

Generated articles must remain standalone HTML with inline CSS and JavaScript.

Coding Style & Naming Conventions

Use Markdown for skill and reference instructions. Keep SKILL.md files focused on trigger rules and workflow; put long, situational guidance in references/ so it loads lazily. Use lowercase kebab-case for skill and reference names, for example creating-explainers and voice-and-style.md. Keep agents/openai.yaml short and aligned with the skill frontmatter. Avoid em dashes in repository prose and templates. Produced article code should stay vanilla HTML/CSS/JS with no npm, React, D3, Tailwind, or shared build tooling.

Testing Guidelines

There is no automated test runner. Validate changes by running the relevant prompt from evals/evals.json against the edited skill and inspecting the generated article or report. For article output, check the sticky two-column layout, sidebar scroll tracking, responsive behavior at mobile widths, Canvas figures, and the fact-checking gate. Any factual explainer change should preserve source-backed claims only.

Commit & Pull Request Guidelines

Recent history uses concise Conventional Commit-style subjects, such as feat: add creating-explainers hub skill and docs: clarify install instructions. Follow that pattern with feat:, docs:, chore:, or similar prefixes.

Pull requests should describe the changed skill or document, explain why the change is needed, list any eval prompt used for validation, and include screenshots or generated article paths when visual output changes. Keep README.md, .claude-plugin/, .codex-plugin/, skill metadata, and marketplace metadata in sync when skill names, descriptions, or install behavior change.