feat!: collapse seven skills into one router skill

.agents/README.md

@@ -0,0 +1,15 @@
+# Codex Repo Skills
+
+This directory exposes the repository's portable `skills/` folders as
+repo-scoped Codex skills.
+
+OpenAI's Codex skill discovery scans `$REPO_ROOT/.agents/skills`. The real
+skill sources remain in `../skills`; entries here are symlinks so Claude Code,
+Codex, and generic Agent Skills clients share the same `SKILL.md` files.
+
+When adding a skill:
+
+1. Create `skills/<name>/SKILL.md`.
+2. Create `.agents/skills/<name> -> ../../skills/<name>`.
+3. Add `skills/<name>/agents/openai.yaml`.
+4. Run `task ai-integrations`.

.agents/skills/shell

@@ -0,0 +1 @@
+../../skills/shell

.claude-plugin/marketplace.json

@@ -1,16 +1,16 @@
 {
   "name": "shell-skill",
-  "description": "Skills for writing safe, correct shell — Bash, Zsh, POSIX sh, and Nushell — for humans and AI coding agents.",
+  "description": "Shell Skill Kit: test-enforced skills for safe Bash, Zsh, POSIX sh, and Nushell.",
   "owner": {
     "name": "Mikhail Kuznetsov (@posidoni)"
   },
   "plugins": [
     {
       "name": "shell-skill",
       "source": "./",
-      "description": "Skills for writing safe, correct shell — Bash, Zsh, POSIX sh, and Nushell.",
+      "description": "Shell Skill Kit: safe shell rules for AI coding agents.",
       "category": "development",
-      "version": "0.1.0"
+      "version": "0.3.0"
     }
   ]
 }

.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "shell-skill",
-  "version": "0.1.0",
-  "description": "Skills for writing safe, correct shell — Bash, Zsh, POSIX sh, and Nushell.",
+  "version": "0.3.0",
+  "description": "Shell Skill Kit: test-enforced skills for safe Bash, Zsh, POSIX sh, and Nushell.",
   "author": {
     "name": "Mikhail Kuznetsov",
     "url": "https://github.com/posidoni"
@@ -18,6 +18,10 @@
     "shellcheck",
     "shfmt",
     "safety",
-    "agent-skills"
+    "agent-skills",
+    "codex",
+    "chatgpt",
+    "claude-code",
+    "shell-safety"
   ]
 }

.codex-plugin/plugin.json

@@ -0,0 +1,53 @@
+{
+  "name": "shell-skill",
+  "version": "0.3.0",
+  "description": "Shell Skill Kit: test-enforced Agent Skills for safe Bash, Zsh, POSIX sh, and Nushell.",
+  "author": {
+    "name": "Mikhail Kuznetsov",
+    "url": "https://github.com/posidoni"
+  },
+  "repository": "https://github.com/posidoni/shell-skill",
+  "homepage": "https://github.com/posidoni/shell-skill#readme",
+  "license": "MIT",
+  "keywords": [
+    "shell",
+    "bash",
+    "zsh",
+    "nushell",
+    "posix",
+    "shellcheck",
+    "shfmt",
+    "agent-skills",
+    "codex",
+    "chatgpt",
+    "claude-code",
+    "cursor",
+    "ai-coding",
+    "shell-safety"
+  ],
+  "skills": "./skills/",
+  "interface": {
+    "displayName": "Shell Skill Kit",
+    "shortDescription": "Safe shell rules for AI coding agents",
+    "longDescription": "A portable, cited, test-enforced skill kit for writing and reviewing shell. Covers Bash, Zsh, POSIX sh, Nushell, shebangs, streams, and the failure modes that make generated scripts quietly unsafe.",
+    "developerName": "Mikhail Kuznetsov",
+    "category": "Development",
+    "capabilities": [
+      "Skills",
+      "Review",
+      "Linting"
+    ],
+    "websiteURL": "https://github.com/posidoni/shell-skill",
+    "brandColor": "#2563EB",
+    "composerIcon": "./assets/logo.svg",
+    "logo": "./assets/logo.svg",
+    "screenshots": [
+      "./assets/social-preview.png"
+    ],
+    "defaultPrompt": [
+      "Use Shell Skill Kit to review this shell script.",
+      "Write a portable Bash script with safe defaults.",
+      "Explain why this shell example is unsafe."
+    ]
+  }
+}

.codex/config.toml

@@ -0,0 +1,5 @@
+# Repo-scoped Codex defaults.
+# Loaded only for trusted checkouts; user security policy remains local.
+
+[features]
+multi_agent = true

.fdignore

@@ -7,3 +7,6 @@
 
 # Legal / changelog boilerplate is rarely a useful `fd` hit.
 LICENSE
+
+# Codex repo-scope skills are symlinks to skills/*; hide duplicate listings.
+.agents/skills/

.github/ISSUE_TEMPLATE/config.yml

@@ -1,3 +1,4 @@
+# yaml-language-server: $schema=https://json.schemastore.org/github-issue-config.json
 blank_issues_enabled: false
 contact_links:
   - name: Security report

.github/copilot-instructions.md

@@ -24,6 +24,8 @@ under [`skills/`](../skills/)).
   `shellcheck --severity=warning` and `shfmt`.
 - `*.bad.sh` must be safe to run and carry an `# expect-shellcheck:` directive.
 - Nushell `*.nu` must pass `nu --ide-check`.
+- Tracked YAML-like files (`*.yml`, `*.yaml`, `*.cff`) must start with a
+  `yaml-language-server` JSON Schema modeline.
 
 ## Verification
 

.github/dependabot.yml

@@ -1,3 +1,4 @@
+# yaml-language-server: $schema=https://json.schemastore.org/dependabot-2.0.json
 # Keep pinned GitHub Actions up to date. https://docs.github.com/code-security/dependabot
 version: 2
 updates:

.github/workflows/ci.yml

@@ -1,3 +1,4 @@
+# yaml-language-server: $schema=https://json.schemastore.org/github-workflow.json
 name: CI
 
 on:
@@ -14,39 +15,37 @@ concurrency:
   group: ci-${{ github.workflow }}-${{ github.ref }}
   cancel-in-progress: true
 
-env:
-  SHFMT_VERSION: v3.13.1
-  NU_VERSION: "0.114.1"
-  TASK_VERSION: "v3.52.0"
-  LEFTHOOK_VERSION: "v2.1.10"
-
 jobs:
-  shell:
-    name: shell (shellcheck + shfmt + bats)
+  quality:
+    name: quality gate
     runs-on: ubuntu-24.04
     steps:
-      # Third-party and first-party actions are pinned to a full commit SHA
-      # (with a human-readable version comment) per GitHub's security hardening
-      # guidance: https://docs.github.com/actions/security-guides/security-hardening-for-github-actions
       - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
       - name: Install toolchain
         run: ./tools/ci-install-linux.sh
-      - name: Format check (shfmt)
-        run: task fmt-check
-      - name: Lint (shellcheck)
-        run: task lint
-      - name: Example contract (bad examples)
-        run: task examples
-      - name: Behavioural tests (bats)
-        run: task test
-
-  shell-macos:
-    name: shell-macos (shellcheck + shfmt + bats on macOS)
+      - name: Run full local gate
+        run: task ci
+      - name: Run hook mirror
+        run: task hooks
+
+  # Portability signal, not version reproducibility. This kit's entire premise
+  # is that Bash, shfmt and ShellCheck behave differently on BSD and GNU (no
+  # portable `sed -i`; /bin/bash is 3.2 on macOS) -- a Linux-only gate cannot
+  # verify the thing this repo teaches. See tools/ci-install-macos.sh.
+  quality-macos:
+    name: quality gate (macOS)
     runs-on: macos-14
     steps:
       - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
       - name: Install toolchain (Homebrew)
         run: ./tools/ci-install-macos.sh
+      # Deliberately the shell gates only, NOT `task ci`. `task ci` also runs
+      # the nushell gate, and Homebrew's nu is unpinned -- the runner currently
+      # ships 0.113.1 against the 0.114.1 the Linux job pins, so the input/output
+      # signature in examples/nushell/03-typed-command.nu fails to parse there.
+      # That is version skew, not a platform difference: nu is one Rust binary
+      # and behaves the same on both. Linux owns the nushell gate at a pinned
+      # version; this job owns bash/shfmt/ShellCheck, which genuinely differ.
       - name: Format check (shfmt)
         run: task fmt-check
       - name: Lint (shellcheck)
@@ -55,25 +54,3 @@ jobs:
         run: task examples
       - name: Behavioural tests (bats)
         run: task test
-
-  nushell:
-    name: nushell (nu --ide-check + startup demo)
-    runs-on: ubuntu-24.04
-    steps:
-      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
-      - name: Install toolchain
-        run: ./tools/ci-install-linux.sh
-      - name: Static check (nu --ide-check)
-        run: task nushell
-      - name: Startup-order demo (parse-time source bug + fix)
-        run: task nushell-demo
-
-  lefthook:
-    name: lefthook (mirrors CI hooks)
-    runs-on: ubuntu-24.04
-    steps:
-      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
-      - name: Install toolchain
-        run: ./tools/ci-install-linux.sh
-      - name: Run hooks over all files
-        run: lefthook run pre-commit --all-files

.gitignore

@@ -34,3 +34,10 @@ id_ed25519
 .claude/settings.local.json
 .claude/ralph-loop.local.md
 .ralph/
+
+# Serena. Untracked entirely as of 2026-07-19 -- the six "curated memories"
+# that used to be whitelisted here were Serena's own auto-generated onboarding
+# output (conventions, tech_stack, suggested_commands...), not authored content,
+# and they duplicated README.md and the Taskfile while drifting from them.
+# Editor/agent integration state does not belong in a public repo.
+.serena/

.rgignore

@@ -7,5 +7,8 @@
 LICENSE
 CHANGELOG.md
 
+# Codex repo-scope skills are symlinks to skills/*; hide duplicate search hits.
+.agents/skills/**
+
 # Keep broad `rg` sweeps bounded (repo convention: never traverse VCS/data dirs).
 .git/

AGENTS.md

@@ -6,8 +6,9 @@ Cursor, and any other tool that reads an `AGENTS.md`. Humans should start with
 
 ## What this repository is
 
-`shell-skill` teaches safe, correct shell (Bash, Zsh, POSIX `sh`) and Nushell
+Shell Skill Kit teaches safe, correct shell (Bash, Zsh, POSIX `sh`) and Nushell
 through cited rules, runnable good/bad examples, and loadable agent skills.
+The stable technical id remains `shell-skill`.
 
 ## Golden rules
 
@@ -19,14 +20,18 @@ through cited rules, runnable good/bad examples, and loadable agent skills.
    Use `$HOME`/`~` generically.
 4. **Local-only by default:** do not `git push`, change remotes, or alter
    repository visibility unless the human explicitly asks.
+5. **YAML is schema-backed:** every tracked `*.yml`, `*.yaml`, and
+   `CITATION.cff` starts with a `yaml-language-server` JSON Schema modeline.
 
 ## Workflow
 
 ```sh
 task --list      # discover every entrypoint
 task fmt         # format shell scripts (shfmt -w)
-task ci          # fmt-check, lint, examples, nushell, nushell-demo, test
+task ci          # fmt-check, lint, examples, nushell, nushell-demo, yaml-schemas, ai-integrations, test
 task hooks       # lefthook run pre-commit --all-files
+task yaml-schemas # ensure YAML-like files declare JSON Schemas
+task ai-integrations # validate Codex/ChatGPT discovery
 ```
 
 ## The example contract
@@ -57,3 +62,9 @@ Nushell examples are `*.nu` and must pass `nu --ide-check`.
 | `examples/<domain>/` | runnable good/bad pairs |
 | `tools/`, `tests/` | verification scripts and the bats suite |
 | `Taskfile.yml` | task runner entrypoints |
+| `.agents/skills/` | Codex repo-scope skill symlinks to `skills/` |
+| `.codex/config.toml` | trusted Codex project defaults |
+| `.codex-plugin/`, `.claude-plugin/` | Codex and Claude Code plugin manifests |
+| `CHATGPT.md`, `llms.txt` | ChatGPT/Codex handoff and crawler-friendly index |
+| `REGISTRY.md` | directory compatibility notes and listing drafts |
+| `schemas/` | project-owned JSON Schemas |