feat: add code-explainer skill with docs, pipeline, and publishing setup

Author: baboonzero

.github/workflows/ci.yml

@@ -0,0 +1,34 @@
+name: ci
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  validate:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+
+      - name: Install Mermaid CLI
+        run: npm install -g @mermaid-js/mermaid-cli
+
+      - name: Compile scripts
+        working-directory: code-explainer
+        run: python -c "import glob,py_compile; [py_compile.compile(f, doraise=True) for f in glob.glob('scripts/*.py')]; print('compiled')"
+
+      - name: Smoke test
+        working-directory: code-explainer
+        run: python scripts/analyze.py analyze --source . --output .ci-out --mode standard --audience nontech --enable-web-enrichment false
+

.gitignore

@@ -0,0 +1,14 @@
+# Python
+__pycache__/
+*.py[cod]
+
+# Skill local outputs
+code-explainer/.out*/
+code-explainer/.out-gh/
+
+# OS/editor
+.DS_Store
+Thumbs.db
+.vscode/
+.idea/
+

LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

PUBLISHING.md

@@ -0,0 +1,59 @@
+# Publishing and Distribution
+
+## 1) Publish to GitHub
+
+From repository root:
+
+```bash
+git add .
+git commit -m "feat: add code-explainer skill"
+git remote add origin https://github.com/<your-org-or-user>/code-explainer.git
+git push -u origin main
+```
+
+## 2) Verify Install from GitHub
+
+Use the Skills CLI install pattern:
+
+```bash
+npx skills add https://github.com/<your-org-or-user>/code-explainer --skill code-explainer
+```
+
+Or with Codex system installer script:
+
+```bash
+python ~/.codex/skills/.system/skill-installer/scripts/install-skill-from-github.py \
+  --repo <your-org-or-user>/code-explainer \
+  --path code-explainer
+```
+
+Dependency note for downstream users:
+
+- Python 3.10+
+- Node.js 18+ and npm
+- Git
+- Mermaid CLI (`@mermaid-js/mermaid-cli`) for full SVG/PNG rendering
+
+Point users to:
+
+- `README.md` -> "Dependencies (Required for Skill Installation/Use)"
+- `code-explainer/SKILL.md` -> "Dependencies"
+
+## 3) `skills.sh` Listing Expectations
+
+- `skills.sh` tracks install activity from `npx skills` usage.
+- The site updates roughly every 12 hours.
+- Removed/unavailable repos can be pruned from listings.
+
+Practical implication:
+
+1. Publish repo publicly.
+2. Ensure install command works.
+3. Have users install via `npx skills ...` so the skill becomes discoverable through ecosystem tracking.
+
+## 4) Increase Discoverability
+
+1. Add GitHub topics: `agent-skill`, `codex`, `mermaid`, `codebase-analysis`, `onboarding`.
+2. Add a short demo GIF in README showing generated overview + deep docs.
+3. Publish a GitHub release with example outputs.
+4. Share in developer communities with install command and sample output links.

README.md

@@ -0,0 +1,171 @@
+# code-explainer
+
+`code-explainer` is an open-source skill that analyzes either a local repository folder or a GitHub URL and produces onboarding explainers for PMs, designers, and engineers.
+
+Outputs include:
+
+- Crisp top-level overview (`OVERVIEW.md`)
+- Linked deep explainers (architecture, modules, flows, dependencies, glossary)
+- Mermaid source diagrams (`.mmd`)
+- Rendered SVG and PNG diagrams
+- Confidence, attribution, and quality reports (`meta/*.json`)
+
+## Repository Layout
+
+```text
+code-explainer/
+  SKILL.md
+  agents/openai.yaml
+  scripts/
+  references/
+  assets/templates/
+```
+
+## Dependencies (Required for Skill Installation/Use)
+
+Install these before using the skill:
+
+- Python `3.10+`
+- Node.js `18+` and npm
+- Git
+
+For high-fidelity diagram rendering (`SVG` + `PNG` via Mermaid CLI):
+
+- Mermaid CLI (`mmdc`) from `@mermaid-js/mermaid-cli`
+
+If `mmdc` is missing, the skill still runs but uses fallback rendering and reports it in `meta/render_report.json`.
+
+## Install Runtime Dependencies
+
+### Windows (PowerShell)
+
+```powershell
+powershell -ExecutionPolicy Bypass -File .\code-explainer\scripts\install_runtime.ps1
+```
+
+### macOS/Linux
+
+```bash
+bash ./code-explainer/scripts/install_runtime.sh
+```
+
+## Troubleshooting Dependencies
+
+### 1) `mmdc` is not recognized
+
+If you see: `mmdc: command not found` or `The term 'mmdc' is not recognized`
+
+Run:
+
+```bash
+npm install -g @mermaid-js/mermaid-cli
+mmdc --version
+```
+
+If it still fails:
+
+1. Open a new terminal session.
+2. Check global npm bin path:
+
+```bash
+npm bin -g
+```
+
+3. Ensure that path is on your `PATH` environment variable.
+
+### 2) Mermaid rendering fails with Chromium/Puppeteer errors
+
+If you see browser launch errors from `mmdc`:
+
+1. Reinstall Mermaid CLI:
+
+```bash
+npm uninstall -g @mermaid-js/mermaid-cli
+npm install -g @mermaid-js/mermaid-cli
+```
+
+2. Re-run:
+
+```bash
+mmdc --version
+```
+
+3. If still blocked, the skill will continue with fallback rendering and report it in `meta/render_report.json`.
+
+### 3) `npm install -g` permission errors
+
+- Windows: run PowerShell as Administrator and retry.
+- macOS/Linux: avoid `sudo npm install -g` if possible; use Node version managers (`nvm`, `fnm`, `asdf`) and retry.
+
+### 4) `python` command not found
+
+Confirm Python install:
+
+```bash
+python --version
+```
+
+If unavailable on Windows but `py` exists:
+
+```powershell
+py --version
+```
+
+Install Python 3.10+ and ensure it is added to `PATH`.
+
+### 5) `git` command not found for GitHub URL analysis
+
+Install Git and verify:
+
+```bash
+git --version
+```
+
+Local folder analysis can still run without Git, but GitHub URL source mode requires it.
+
+## Install Sequence (Fresh Machine)
+
+1. Install runtime dependencies (section above).
+2. Install skill into Codex:
+
+```powershell
+powershell -ExecutionPolicy Bypass -File .\install_to_codex.ps1
+```
+
+3. Restart Codex to load the new skill.
+
+## Run
+
+```bash
+cd code-explainer
+python scripts/analyze.py analyze \
+  --source <local_path_or_github_url> \
+  --output <output_dir> \
+  --mode standard \
+  --audience nontech \
+  --enable-web-enrichment true
+```
+
+## Install Into Codex
+
+Use the installer script:
+
+```powershell
+powershell -ExecutionPolicy Bypass -File .\install_to_codex.ps1
+```
+
+Or copy manually to:
+
+```text
+~/.codex/skills/code-explainer
+```
+
+Then restart Codex so it picks up the new skill.
+
+## Open-Source Publishing
+
+1. Initialize git in this repository.
+2. Commit files.
+3. Push to GitHub.
+4. Add `topics` such as: `codex-skill`, `agent-skill`, `mermaid`, `codebase-analysis`, `onboarding`.
+5. Submit/list the repository on skill directories (see notes in your assistant response).