diff --git a/.agents/README.md b/.agents/README.md new file mode 100644 index 0000000..d332300 --- /dev/null +++ b/.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//SKILL.md`. +2. Create `.agents/skills/ -> ../../skills/`. +3. Add `skills//agents/openai.yaml`. +4. Run `task ai-integrations`. diff --git a/.agents/skills/shell b/.agents/skills/shell new file mode 120000 index 0000000..3244a71 --- /dev/null +++ b/.agents/skills/shell @@ -0,0 +1 @@ +../../skills/shell \ No newline at end of file diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 27c72fd..259f560 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -1,6 +1,6 @@ { "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)" }, @@ -8,9 +8,9 @@ { "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" } ] } diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json index 9720a83..906088d 100644 --- a/.claude-plugin/plugin.json +++ b/.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" ] } diff --git a/.codex-plugin/plugin.json b/.codex-plugin/plugin.json new file mode 100644 index 0000000..2cbec33 --- /dev/null +++ b/.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." + ] + } +} diff --git a/.codex/config.toml b/.codex/config.toml new file mode 100644 index 0000000..49d91e0 --- /dev/null +++ b/.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 diff --git a/.fdignore b/.fdignore index 0f590b5..22f21dc 100644 --- a/.fdignore +++ b/.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/ diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml index a31f257..74b493f 100644 --- a/.github/ISSUE_TEMPLATE/config.yml +++ b/.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 diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index f6cb55f..46dea3d 100644 --- a/.github/copilot-instructions.md +++ b/.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 diff --git a/.github/dependabot.yml b/.github/dependabot.yml index 1f8138f..919ff37 100644 --- a/.github/dependabot.yml +++ b/.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: diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index dca4dbb..ae2b280 100644 --- a/.github/workflows/ci.yml +++ b/.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 diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml deleted file mode 100644 index ea2187d..0000000 --- a/.github/workflows/release.yml +++ /dev/null @@ -1,27 +0,0 @@ -name: Release - -# Cut a GitHub release automatically when a v* tag is pushed. -# Tag a release with: git tag -a vX.Y.Z -m "..." && git push origin vX.Y.Z -on: - push: - tags: ["v*"] - -# Least-privilege: only the permission needed to create a release. -permissions: - contents: write - -jobs: - release: - name: create GitHub release - runs-on: ubuntu-24.04 - steps: - - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0 - - name: Create release from the tag - env: - GH_TOKEN: ${{ github.token }} - TAG: ${{ github.ref_name }} - run: | - gh release create "$TAG" \ - --title "shell-skill ${TAG#v}" \ - --generate-notes \ - --verify-tag diff --git a/.gitignore b/.gitignore index 8093bfc..6035b45 100644 --- a/.gitignore +++ b/.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/ diff --git a/.rgignore b/.rgignore index ee42a26..434e2fb 100644 --- a/.rgignore +++ b/.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/ diff --git a/AGENTS.md b/AGENTS.md index e10b94e..7cd27d9 100644 --- a/AGENTS.md +++ b/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//` | 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 | diff --git a/CHANGELOG.md b/CHANGELOG.md index 77cf314..6347e0a 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,6 +6,45 @@ follow [Semantic Versioning](https://semver.org/). ## [Unreleased] +### Changed + +- Tightened the README into a lighter product overview and moved registry and + ecosystem details into `REGISTRY.md`. +- Hid `.agents/skills` symlink duplicates from `rg` and `fd` searches while + keeping Codex repo-scope discovery intact. +- Rebuilt the social preview around the Shell Skill Kit name and added the SVG + source asset. +- Removed the process diary and folded duplicate registry drafts into + `REGISTRY.md` to keep the public tree sharp. + +## [0.2.0] - 2026-07-18 + +### Added + +- Codex plugin manifest at `.codex-plugin/plugin.json`, with public UI metadata + for Shell Skill Kit. +- ChatGPT/Codex companion instructions in `CHATGPT.md`, crawler-friendly + discovery in `llms.txt`, and `agents/openai.yaml` metadata for every skill. +- Codex repo-scope skill symlinks in `.agents/skills/`, trusted Codex defaults + in `.codex/config.toml`, and portable Serena setup in `.serena/`. +- Registry submission drafts for AgenticSkills and Awesome Codex Plugins. +- JSON Schema modelines for tracked YAML-like files plus `task yaml-schemas` and + `task ai-integrations` gates that enforce the agent metadata contract. + +### Changed + +- Repositioned the project publicly as **Shell Skill Kit** while keeping the + package/repo name `shell-skill`. +- Simplified hosted GitHub Actions to one Ubuntu quality gate that runs + `task ci` plus the hook mirror; macOS verification remains documented as a + local maintainer check. +- Updated Claude plugin metadata, citation metadata, README, contributing docs, + and agent instructions for the 0.2.0 release. + +### Removed + +- Automatic GitHub release workflow; releases are now cut manually from tags. + ## [0.1.0] - 2026-07-13 Initial public release. @@ -27,5 +66,36 @@ Initial public release. - Community health files: `README`, `CONTRIBUTING`, `SECURITY`, `CODE_OF_CONDUCT`, issue/PR templates, and Dependabot. -[Unreleased]: https://github.com/posidoni/shell-skill/compare/v0.1.0...HEAD +[Unreleased]: https://github.com/posidoni/shell-skill/compare/v0.2.0...HEAD +[0.2.0]: https://github.com/posidoni/shell-skill/compare/v0.1.0...v0.2.0 [0.1.0]: https://github.com/posidoni/shell-skill/releases/tag/v0.1.0 + +## 0.3.0 + +### Changed — breaking + +- **Seven skills collapsed into one.** `bash`, `zsh`, `posix-sh`, `nushell`, + `shebang`, `streams` and `shell-standards` are no longer separate skills; there is + now a single `shell` skill that routes into `reference/` on demand. Anything + referencing `shell-skill:bash` (or the other six) must now use `shell-skill:shell`. + + Why: seven sibling skills competed for the same request, and an agent had to choose + a dialect *before* knowing which shell it was about to write — so in practice it + chose none. The `reference/` files, which held the real content, are unchanged. + +- **Descriptions are trigger-first.** Each old description opened with what the skill + *contained* ("Bash-specific practices beyond the shared standards — error + handling..."), and buried the activation cue at the end or omitted it. Skill + selection weights the opening, so the kit sat unused while agents wrote unsafe + shell. The new description leads with when to load it. + +### Added + +- `reference/pipelines.md` — the missing guidance on **not** writing shell: a + replacement table (`jq`/`yq`/`sd`/`fd`/`rg`/`nu`/Python over `awk`+`sed`), why + `sed -i` has no portable invocation across BSD and GNU, when `awk` is still + correct, and worked rewrites of a fragile pipeline into Nushell and Python. +- Interpreter-selection guidance in the skill body: macOS `/bin/bash` is 3.2 and + lacks `mapfile`, associative arrays and `${var^^}`, so `#!/usr/bin/env bash` alone + is not a portability strategy. + diff --git a/CHATGPT.md b/CHATGPT.md new file mode 100644 index 0000000..12503e9 --- /dev/null +++ b/CHATGPT.md @@ -0,0 +1,31 @@ +# CHATGPT.md + +ChatGPT and Codex companion instructions for this repository. The canonical +project contract remains [AGENTS.md](AGENTS.md); read it first. + +## What to load + +- Use `.codex-plugin/plugin.json` when packaging this repo as a Codex plugin. +- Use `.agents/skills/*` for Codex repo-scope discovery in trusted checkouts; + these entries are symlinks to the canonical `skills/` folders. +- Use `.codex/config.toml` for durable project defaults. It currently enables + multi-agent work only; sandbox, approval, and credentials stay user-local. +- Use `skills/*/SKILL.md` as portable Agent Skills. The `agents/openai.yaml` + files add ChatGPT/Codex UI metadata only; they do not replace `SKILL.md`. +- Use `reference/*.md` only when a task needs the cited rationale behind a rule. + +## How to work here + +- Keep skill bodies short and operational. Put depth in `reference/`. +- Preserve the good/bad example contract from `CONTRIBUTING.md`. +- Run `task ci` before handing back release work. +- Run `task hooks` before commits or pull requests. +- Run `task ai-integrations` after changing AI metadata or repo-scoped skills. +- Keep local tool state out of the release package. + +## Release packaging + +- Update both `.claude-plugin/plugin.json` and `.codex-plugin/plugin.json` for + versioned releases. +- Keep `README.md`, `CHANGELOG.md`, `CITATION.cff`, and registry notes in sync + with the public release name: Shell Skill Kit. diff --git a/CITATION.cff b/CITATION.cff index cd59933..2ee5e84 100644 --- a/CITATION.cff +++ b/CITATION.cff @@ -1,5 +1,6 @@ +# yaml-language-server: $schema=https://raw.githubusercontent.com/citation-file-format/citation-file-format/main/schema.json cff-version: 1.2.0 -title: shell-skill +title: Shell Skill Kit message: >- If you use this project, please cite it using the metadata below. type: software @@ -11,8 +12,8 @@ repository-code: "https://github.com/posidoni/shell-skill" url: "https://github.com/posidoni/shell-skill" abstract: >- A cited, test-enforced guide to writing safe, correct shell (Bash, Zsh, POSIX - sh, and Nushell) for humans and AI coding agents, packaged as Claude Code - skills. + sh, and Nushell) for humans and AI coding agents, packaged as portable Agent + Skills plus Claude Code and Codex plugin metadata. keywords: - shell - bash @@ -20,6 +21,8 @@ keywords: - nushell - shellcheck - agent-skills + - codex + - claude-code license: MIT -version: 0.1.0 -date-released: "2026-07-13" +version: 0.2.0 +date-released: "2026-07-18" diff --git a/CLAUDE.md b/CLAUDE.md index 6fd83f4..33b1ec2 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -11,8 +11,9 @@ applies here too. skill's full body only when its description matches the task (progressive disclosure), so keep descriptions precise. - The repo is packaged as an installable Claude Code plugin; see - [`.claude-plugin/`](.claude-plugin/). You can also point Claude at `skills/` - directly. + [`.claude-plugin/`](.claude-plugin/). It also ships Codex metadata in + [`.codex-plugin/`](.codex-plugin/) and ChatGPT notes in [CHATGPT.md](CHATGPT.md). + You can also point Claude at `skills/` directly. - Use the skills here — `shell-standards`, `bash`, `zsh`, `nushell` — whenever you write, review, or debug shell in this repository. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 87f7d68..7341840 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,13 +1,14 @@ # Contributing -Thanks for your interest in improving **shell-skill**. This repository teaches +Thanks for your interest in improving **Shell Skill Kit**. This repository teaches safe, correct shell through rules, runnable examples, and AI-agent skills. Every contribution is expected to hold that same bar: correct, safe, portable, and verified by the toolchain before it lands. ## Toolchain -You need six tools. They are the same ones CI uses. +You need six tools. Hosted CI installs them on Ubuntu; macOS developers can use +the Homebrew command below for the same local gate. | Tool | Purpose | |------|---------| @@ -28,10 +29,12 @@ brew install shellcheck shfmt nushell bats-core go-task lefthook [`tools/ci-install-linux.sh`](tools/ci-install-linux.sh); run it or copy the commands. -CI runs the shell suite on **both Linux and macOS** -([`tools/ci-install-macos.sh`](tools/ci-install-macos.sh)) — Bash, shfmt, and -ShellCheck genuinely behave differently across the two (see -[`reference/bash.md`](reference/bash.md)), so both are checked, not just one. +Hosted CI runs one lean Ubuntu quality gate plus the full hook mirror. macOS +portability still matters: run the Homebrew toolchain locally before touching +Darwin-sensitive examples or reference text. The helper remains in +[`tools/ci-install-macos.sh`](tools/ci-install-macos.sh) because Bash, shfmt, and +ShellCheck can differ across macOS and Linux; we just do not spend hosted macOS +minutes on every PR. Then install the git hooks once: @@ -46,8 +49,10 @@ entrypoint. The important ones: ```sh task fmt # format all shell scripts in place (shfmt -w) -task ci # everything CI runs: fmt-check, lint, examples, nushell, nushell-demo, test +task ci # core quality gate: fmt-check, lint, examples, nushell, nushell-demo, yaml-schemas, ai-integrations, test task hooks # run every git hook across the repo (lefthook) +task yaml-schemas # verify tracked YAML-like files declare a JSON schema +task ai-integrations # verify Codex/ChatGPT/plugin discovery surfaces ``` Why Task over Make? Task is a single, statically-linked Go binary that behaves @@ -88,6 +93,10 @@ runtime good/bad behaviour in the file or its README, not via the linter. 4. Commits follow [Conventional Commits](https://www.conventionalcommits.org/) (`feat:`, `fix:`, `docs:`, `test:`, `chore:`, `build:`, `ci:`). 5. No personal data, secrets, or machine-specific paths anywhere. +6. Every tracked YAML-like file (`*.yml`, `*.yaml`, `*.cff`) has a + `yaml-language-server` JSON Schema modeline. +7. `task ai-integrations` is green after changing skills, plugin manifests, + `.agents/`, `.codex/`, `CHATGPT.md`, or `llms.txt`. ## Reporting problems diff --git a/ENGINEERING.md b/ENGINEERING.md deleted file mode 100644 index 2e4eecd..0000000 --- a/ENGINEERING.md +++ /dev/null @@ -1,71 +0,0 @@ -# Engineering notes - -How this repository was actually built — for anyone curious about the process, -not just the output. - -## Enforcement-first, not asserted - -The organizing idea is that shell advice is usually folklore: unenforced, easy -to skip, quietly drifting from reality. Every rule here ships as a runnable -example CI checks on every push: - -- `*.good.sh` must run to exit 0 with no arguments and pass - `shellcheck --severity=warning` and `shfmt`. -- `*.bad.sh` must be safe to run and must trigger the exact ShellCheck code it - declares — [`tools/check-bad-examples.sh`](tools/check-bad-examples.sh) turns - "does the linter actually catch this?" into a tested claim instead of an - assertion. -- `*.nu` must pass `nu --ide-check` cleanly. - -If a rule and the code disagree, the build goes red. See -[CONTRIBUTING.md](CONTRIBUTING.md#the-example-contract) for the full contract. - -## Built with multi-agent research, not memory - -Several domains needed depth beyond what a single pass could responsibly -assert — the correctness bar here is "cite it or don't write it." Rather than -writing from recall, this repo's content was produced by dispatching parallel -research agents against primary sources, each required to cite a URL and -paraphrase rather than copy: - -- The Nushell parse-time/runtime model and its config load order came from a - fan-out over the official [Nushell Book](https://www.nushell.sh/book/) and - release notes. -- The zsh performance section — including *why* `$TTY` is correct and - `$(tty)` is not (fork cost, and `tty(1)` inspecting fd 0 rather than the - shell's controlling terminal) — came from a targeted pass over - [romkatv](https://github.com/romkatv)'s `zsh-bench` and `Powerlevel10k`. -- The shebang mechanics (the kernel's single-argument rule behind `env -S`, - the `BINPRM_BUF_SIZE` truncation limit) came from `execve(2)` and the GNU - `env` manual, plus a merged Linux kernel documentation fix by - [@alurm](https://github.com/alurm). -- The `printf`-over-`echo` and stream-handling rules came from a research pass - that also caught the repo's *own* tooling using `echo` — which was then - rewritten to `printf` throughout, so the rule and the practice agree. - -Every one of these went through an adversarial review pass (technical -accuracy, docs quality, publish-safety) before being committed — one finding -from that pass corrected an overclaim in the standards reference about which -ShellCheck severity actually enforces which rule. - -## Iterative, checkpointed, never committed red - -The repo was developed incrementally: each change is scoped to one concern, -verified locally (`task ci` and `task hooks` both green) before it is -committed, and pushed only once proven. Nothing here was committed on faith -that CI would catch it later — CI is the backstop, not the first check. - -## Transparent about how it was made - -Every commit keeps its `Co-Authored-By: Claude` trailer, by choice, rather -than being scrubbed for appearance — an accurate record beats a flattering -one. The scope, structure, and every publish decision were the maintainer's -calls throughout, including a hard boundary the agent respected without -exception: it could prepare, verify, and stage everything, but the decision to -make the repository public was never its call to make. - -## Result - -Six enforced skill domains, a CI-checked example contract, cross-platform -verification (Linux and macOS), and a written history where the claims and the -mechanism that checks them live in the same repository. diff --git a/README.md b/README.md index 8cd8125..aade501 100644 --- a/README.md +++ b/README.md @@ -1,193 +1,143 @@
-shell-skill +Shell Skill Kit -# shell-skill +# Shell Skill Kit -**A cited, test-enforced guide to writing safe, correct shell** — Bash, Zsh, POSIX `sh`, and Nushell — for humans and AI coding agents. +**Small, test-enforced shell rules for AI coding agents.** -[Why](#why-this-exists) · [Skills](#skills) · [Quick start](#quick-start) · [Example contract](#the-example-contract) · [Use with agents](#use-it-with-ai-coding-agents) · [Contributing](#contributing) +Bash, Zsh, POSIX `sh`, Nushell, shebangs, and streams, packaged as portable +Agent Skills plus Claude Code and Codex metadata. + +[Skills](#skills) | [Install](#install) | [Agent Surfaces](#agent-surfaces) | [Quality Gates](#quality-gates) | [Registry](REGISTRY.md)
--- -## The problem - -AI coding assistants now write a large share of the world's shell — and a lot of -it is quietly wrong: unquoted expansions, missing `set -euo pipefail`, `[ ]` -where `[[ ]]` belongs, real errors swallowed by a stray `|| true`. It works on -the happy path and fails silently everywhere else. And the usual advice ("quote -your variables") is folklore — unenforced, uncited, easy to skip. - -**shell-skill is the antidote.** It encodes the rules as cited references, -runnable examples that CI checks, and -[Agent Skills](https://code.claude.com/docs/en/plugins) you can load into Claude, -Codex, or Copilot — so the shell your tools (and you) produce is safe by default, -not by luck. - -> [!IMPORTANT] -> This repository enforces its own advice. `*.good.sh` examples must run to -> exit 0 and pass `shellcheck` + `shfmt`; `*.bad.sh` examples must trigger the -> exact ShellCheck codes they claim. If the docs drift from reality, CI goes red. - -## Why this exists - -- **Enforced, not asserted.** The example contract is checked in CI, so the - guidance cannot rot without breaking the build. -- **Portable by default.** Guidance calls out macOS Bash 3.2 and BSD-vs-GNU - differences instead of assuming Linux + GNU coreutils — and CI runs the - suite on both Linux and macOS, so that claim is checked, not just asserted. -- **Judgment, not just syntax.** It also covers - [when *not* to use shell](reference/meta-guidance.md) — reach for Python or Go - before a 300-line Bash script. -- **Agent-ready.** Ships `AGENTS.md`, `CLAUDE.md`, Copilot instructions, and an - installable Claude Code plugin so the rules travel with your tools. +## What It Is -## Skills +Shell Skill Kit is a lightweight rule pack for one risky place in AI coding: +generated shell. -| Skill | Covers | Reference | Examples | -|-------|--------|-----------|----------| -| [shell-standards](skills/shell-standards/SKILL.md) | strict mode, quoting, `[[ ]]`, arrays, traps, error handling | [reference](reference/shell-standards.md) | [examples](examples/standards/) | -| [shebang](skills/shebang/SKILL.md) | `#!/usr/bin/env`, `env -S` flags, absolute paths, dialect | [reference](reference/shebang.md) | [examples](examples/shebang/) | -| [streams](skills/streams/SKILL.md) | stdin/stdout/stderr, `>&2`, `read -r`, redirection order, here-docs | [reference](reference/streams.md) | [examples](examples/streams/) | -| [bash](skills/bash/SKILL.md) | error handling, macOS/BSD portability, arrays, temp files | [reference](reference/bash.md) | [examples](examples/bash/) | -| [posix-sh](skills/posix-sh/SKILL.md) | no `local`, no arrays, `[ ]` not `[[ ]]`, `set -eu` without `pipefail` | [reference](reference/posix-sh.md) | [examples](examples/posix-sh/) | -| [zsh](skills/zsh/SKILL.md) | word-splitting, 1-indexed arrays, `emulate`, globbing | [reference](reference/zsh.md) | prose | -| [nushell](skills/nushell/SKILL.md) | structured data, config load order, parse-time `source` | [reference](reference/nushell.md) | [examples](examples/nushell/) | +It is deliberately not a framework. The repo ships four things: -> [!NOTE] -> ShellCheck and shfmt do not support zsh, so the zsh guidance is prose only — -> itself a reason to prefer Bash for portable, lintable scripts. +- short `SKILL.md` files that agents can load on demand; +- cited references for the reasoning behind each rule; +- runnable good/bad examples that CI checks; +- provider metadata for Codex, ChatGPT, Claude Code, Copilot, and other + skill-aware tools. -## Quick start +The design contract is simple: **tiny skill bodies, deep references, executable +claims**. If a shell rule cannot be cited or tested, it stays out. -Install the toolchain (macOS): +## Why It Exists -```sh -brew install shellcheck shfmt nushell bats-core go-task lefthook -``` +AI assistants often produce shell that works once and fails quietly later: +unquoted expansions, wrong dialects, swallowed errors, stdout polluted with +diagnostics, or Bash code hiding under `#!/bin/sh`. -
-Linux (pinned versions) +Shell Skill Kit makes those failure modes harder to ship. `*.good.sh` examples +must run and lint cleanly. `*.bad.sh` examples must trigger the exact ShellCheck +codes they claim. Nushell examples must parse with `nu --ide-check`. When docs +and reality drift, the build goes red. -Use the versions CI installs — see -[`tools/ci-install-linux.sh`](tools/ci-install-linux.sh), which fetches pinned -`shfmt`, `nushell`, and `task` binaries and installs `shellcheck` + `bats` from -apt. +## Skills -
+| Skill | Use it for | +|-------|------------| +| [shell](skills/shell/SKILL.md) | **The single entry point.** Loads before you write any shell — picks the right tool first (often not shell), then applies the safety rules. | -Then: +It routes into these on demand, so only what you need enters context: -```sh -task # list every entrypoint -task ci # fmt-check, lint, examples, nushell, nushell-demo, test -task hooks # run every git hook across the repo (lefthook) +| Reference | Covers | Examples | +|-----------|--------|----------| +| [cli-cheatsheets](reference/cli-cheatsheets.md) | how to check a tool (`--help` → `man` → context7), plus cached gotchas for fd/rg/sd/nu/jq/yq | prose | +| [pipelines](reference/pipelines.md) | replacing `awk`/`sed`/`cut`, BSD-vs-GNU `sed -i`, worked rewrites | prose | +| [shell-standards](reference/shell-standards.md) | strict mode, quoting, arrays, traps, `printf`, `[[ ]]` | [examples](examples/standards/) | +| [bash](reference/bash.md) | Bash error handling, arrays, macOS/BSD portability, bash-3.2 traps | [examples](examples/bash/) | +| [posix-sh](reference/posix-sh.md) | real `/bin/sh`, dash, no arrays, no bashisms | [examples](examples/posix-sh/) | +| [zsh](reference/zsh.md) | zsh functions, options, globbing, no-fork performance | prose | +| [nushell](reference/nushell.md) | structured pipelines, parse-time config, typed commands | [examples](examples/nushell/) | +| [shebang](reference/shebang.md) | `env`, `env -S`, interpreter paths, dialect choice | [examples](examples/shebang/) | +| [streams](reference/streams.md) | stdin/stdout/stderr, redirection order, exit codes | [examples](examples/streams/) | + +ShellCheck and shfmt do not support zsh, so zsh guidance is prose plus +`zsh -n` syntax checking. For portable, lintable scripts, prefer Bash. + +## Install + +Claude Code plugin: + +```text +/plugin marketplace add posidoni/shell-skill +/plugin install shell-skill@shell-skill ``` -This project uses [Task](https://taskfile.dev), not Make — a single -cross-platform binary with plain-YAML, self-documenting tasks. See -[CONTRIBUTING.md](CONTRIBUTING.md) for the rationale. +Portable skill clients: -## The example contract +```sh +git clone https://github.com/posidoni/shell-skill +ln -s "$PWD/shell-skill/skills/shell" "$YOUR_SKILLS_DIR/shell" +``` -Examples live in `examples//` as paired files: +Local development toolchain on macOS: -- **`NN-slug.good.sh`** — the correct pattern; self-contained, no arguments, - exits 0, clean under `shellcheck --severity=warning` and `shfmt`. -- **`NN-slug.bad.sh`** — a safe-to-run anti-pattern carrying one directive: - `# expect-shellcheck: SC####` (codes ShellCheck must report) or - `# expect-shellcheck: none` (a style-guide-only pitfall). +```sh +brew install shellcheck shfmt nushell bats-core go-task lefthook +task ci +task hooks +``` -Nushell examples are `*.nu`, verified with `nu --ide-check`. +Linux CI installs pinned versions through +[tools/ci-install-linux.sh](tools/ci-install-linux.sh). -## Use it with AI coding agents +## Agent Surfaces -| Agent | Entry point | -|-------|-------------| -| Codex, Cursor, general | [`AGENTS.md`](AGENTS.md) | -| Claude Code | [`CLAUDE.md`](CLAUDE.md), or install the plugin (below) | -| GitHub Copilot | [`.github/copilot-instructions.md`](.github/copilot-instructions.md) | +| Surface | Entry point | +|---------|-------------| +| Codex / ChatGPT Cowork | [.codex-plugin/plugin.json](.codex-plugin/plugin.json), [.agents/skills/](.agents/skills/), [.codex/config.toml](.codex/config.toml), [CHATGPT.md](CHATGPT.md) | +| Claude Code | [CLAUDE.md](CLAUDE.md), [.claude-plugin/plugin.json](.claude-plugin/plugin.json), [agents/shell-reviewer.md](agents/shell-reviewer.md) | +| GitHub Copilot | [.github/copilot-instructions.md](.github/copilot-instructions.md) | +| Generic agents and crawlers | [AGENTS.md](AGENTS.md), [llms.txt](llms.txt), `skills/*/SKILL.md` | -Install the Claude Code plugin: +See [REGISTRY.md](REGISTRY.md) for directory listings, ecosystem notes, and +copy-ready submission text. -``` -/plugin marketplace add posidoni/shell-skill -/plugin install shell-skill@shell-skill +## Quality Gates + +```sh +task --list # discover entrypoints +task ci # core quality gate +task hooks # lefthook pre-commit mirror across the repo +task ai-integrations # Codex, ChatGPT, plugin, and skill metadata ``` -The plugin also ships a [`shell-reviewer`](agents/shell-reviewer.md) -subagent: it reviews Bash/POSIX sh/Zsh/Nushell changes strictly against -this repo's own cited rules, running `shellcheck`/`shfmt`/`nu --ide-check` -itself rather than eyeballing style. +`task ci` runs formatting, shell linting, example checks, Nushell parsing, YAML +schema-modeline checks, AI integration checks, and the bats suite. -## Repository map +## Repository Map -| Path | What | -|------|------| -| `skills/` | Agent Skills (`SKILL.md` per domain) | -| `reference/` | in-depth references with citations | -| `examples/` | runnable good/bad pairs | -| `tools/`, `tests/` | verification scripts and the bats suite | -| `.github/workflows/` | CI (ShellCheck, shfmt, bats, Nushell, lefthook) | -| `.claude-plugin/` | plugin + marketplace manifests | -| `Taskfile.yml` | task runner entrypoints | +| Path | Purpose | +|------|---------| +| `skills/` | portable Agent Skills | +| `reference/` | cited rule explanations | +| `examples/` | runnable good/bad contracts | +| `tools/`, `tests/` | verification scripts and bats tests | +| `.agents/`, `.codex-plugin/`, `.claude-plugin/` | AI provider packaging | +| `schemas/` | project-owned JSON Schemas | +| `REGISTRY.md` | listing drafts and discovery notes | ## Contributing -See [CONTRIBUTING.md](CONTRIBUTING.md) for the toolchain, the example contract, -and the PR checklist. Please also read the [Code of Conduct](CODE_OF_CONDUCT.md). -Security reports: [SECURITY.md](SECURITY.md). Curious how this was actually -built — the research process, the enforcement discipline? See -[ENGINEERING.md](ENGINEERING.md). - -## References - -The repository layout follows established Agent-Skills projects: - -- [anthropics/skills](https://github.com/anthropics/skills) — the official Agent - Skills repo; `SKILL.md` frontmatter and progressive disclosure. -- [Agent Skills specification](https://agentskills.io) — the open standard. -- [netresearch/skill-repo-skill](https://github.com/netresearch/skill-repo-skill) - — skill-repository layout, plugin packaging, and validation. - -Related projects and curated indexes of Agent Skills: -[addyosmani/agent-skills](https://github.com/addyosmani/agent-skills), -[hesreallyhim/awesome-claude-code](https://github.com/hesreallyhim/awesome-claude-code), -[travisvn/awesome-claude-skills](https://github.com/travisvn/awesome-claude-skills), -[ComposioHQ/awesome-claude-skills](https://github.com/ComposioHQ/awesome-claude-skills), -[rohitg00/awesome-claude-code-toolkit](https://github.com/rohitg00/awesome-claude-code-toolkit), -[VoltAgent/awesome-claude-code-subagents](https://github.com/VoltAgent/awesome-claude-code-subagents). - -### Shell references and inspiration - -The guidance draws on — and is indebted to — these sources: - -- [Google Shell Style Guide](https://google.github.io/styleguide/shellguide.html) - and the [ShellCheck wiki](https://www.shellcheck.net/wiki/) — the backbone of - the rules and codes. -- [Greg's Wiki — BashFAQ & BashPitfalls](https://mywiki.wooledge.org/) — the - definitive catalogue of shell gotchas. -- [dylanaraps/pure-bash-bible](https://github.com/dylanaraps/pure-bash-bible) — - pure-bash alternatives to external commands. -- [anordal/shellharden](https://github.com/anordal/shellharden) — a safety - auto-corrector and its precise "what you don't need to quote" rules. -- [koalaman/shellcheck](https://github.com/koalaman/shellcheck) — one page per - diagnostic; the model for machine-checkable rules. -- [romkatv/zsh-bench](https://github.com/romkatv/zsh-bench) & - [Powerlevel10k](https://github.com/romkatv/powerlevel10k) — the zsh - no-subprocess performance discipline. -- [The Nushell Book](https://www.nushell.sh/book/) — the Nushell chapters. -- Shebang mechanics: [`execve(2)`](https://man7.org/linux/man-pages/man2/execve.2.html) - and the merged Linux doc fix by [@alurm](https://github.com/alurm). +Read [CONTRIBUTING.md](CONTRIBUTING.md) for the example contract and PR checklist. +Read [AGENTS.md](AGENTS.md) before agent-assisted edits. Security reports go +through [SECURITY.md](SECURITY.md). ## License -[MIT](LICENSE) © 2026 Mikhail Kuznetsov ([@posidoni](https://github.com/posidoni)) - ---- +[MIT](LICENSE) (c) 2026 Mikhail Kuznetsov ([@posidoni](https://github.com/posidoni))
-Safe shell, for humans and the agents that write it. +Safe shell for humans and the agents that write it.
diff --git a/REGISTRY.md b/REGISTRY.md new file mode 100644 index 0000000..cab66a4 --- /dev/null +++ b/REGISTRY.md @@ -0,0 +1,65 @@ +# Registry And Discovery + +Shell Skill Kit is prepared for skill clients, plugin clients, and crawler-style +discovery without requiring a heavyweight runtime. + +## Published Surfaces + +| Surface | Files | +|---------|-------| +| Portable Agent Skills | `skills/*/SKILL.md` | +| Codex repo-scope skills | `.agents/skills/*` symlinks | +| Codex / ChatGPT plugin | `.codex-plugin/plugin.json` | +| Claude Code plugin | `.claude-plugin/plugin.json` | +| ChatGPT / Codex handoff | `CHATGPT.md`, `llms.txt`, `skills/*/agents/openai.yaml` | +| GitHub Copilot | `.github/copilot-instructions.md` | + +## Listing Drafts + +AgenticSkills: + +```text +Skill Name: Shell Skill Kit +GitHub Repository URL: https://github.com/posidoni/shell-skill +Category: Code Quality & Testing +Short Description: Test-enforced shell rules for AI agents: Bash, Zsh, POSIX sh, Nushell, shebangs, streams, and examples. +Tags: shell, bash, zsh, posix-sh, nushell, shellcheck, shfmt, agent-skills, codex, claude-code, ai-coding +Author Name: Mikhail Kuznetsov +Website or Twitter: https://github.com/posidoni +Email: maintainer email required at submission time +``` + +Awesome Codex Plugins: + +```md +- [Shell Skill Kit](https://github.com/posidoni/shell-skill) - Test-enforced Agent Skills for safe Bash, Zsh, POSIX sh, Nushell, shebangs, streams, and generated-script review. Ships portable `SKILL.md` folders plus Codex and Claude Code plugin metadata. +``` + +Live submission still needs the maintainer's explicit action. Keep hosted CI +lean unless a target registry requires a scanner gate for a listing PR. + +## Compatibility Notes + +- Keep the public product name **Shell Skill Kit**. +- Keep the stable technical id **shell-skill** for repository, plugin, and + package references. +- Keep `SKILL.md` frontmatter minimal and portable; provider-specific UI metadata + belongs in companion files such as `agents/openai.yaml`. +- Keep `.codex-plugin/` to `plugin.json` only. The actual skills stay in the + top-level `skills/` directory and are referenced from the manifest. +- Keep `.agents/skills/*` as symlinks to `../../skills/*`; do not duplicate skill + bodies for Codex repo-scope discovery. +- YAML, TOML, and Nushell are covered by repository gates (`task yaml-schemas`, + `task nushell`) rather than by editor tooling. + +## Ecosystem References + +- [Agent Skills specification](https://agentskills.io/specification) +- [AgenticSkills](https://agenticskills.io/) +- [Awesome Codex Plugins](https://github.com/hashgraph-online/awesome-codex-plugins) +- [anthropics/skills](https://github.com/anthropics/skills) +- [addyosmani/agent-skills](https://github.com/addyosmani/agent-skills) +- [hesreallyhim/awesome-claude-code](https://github.com/hesreallyhim/awesome-claude-code) +- [travisvn/awesome-claude-skills](https://github.com/travisvn/awesome-claude-skills) +- [ComposioHQ/awesome-claude-skills](https://github.com/ComposioHQ/awesome-claude-skills) +- [VoltAgent/awesome-claude-code-subagents](https://github.com/VoltAgent/awesome-claude-code-subagents) diff --git a/Taskfile.yml b/Taskfile.yml index 05a4db0..2738cae 100644 --- a/Taskfile.yml +++ b/Taskfile.yml @@ -1,3 +1,4 @@ +# yaml-language-server: $schema=https://taskfile.dev/schema.json # Taskfile — developer and CI entrypoints. Run `task` (or `task --list`) for the # menu. See https://taskfile.dev. # @@ -50,6 +51,16 @@ tasks: cmds: - ./tests/nushell-startup-demo.sh + yaml-schemas: + desc: Check every tracked YAML-like file declares a JSON schema + cmds: + - ./tools/check-yaml-schemas.sh + + ai-integrations: + desc: Validate Codex, ChatGPT, and plugin discovery surfaces + cmds: + - ./tools/check-ai-integrations.sh + test: desc: Run the bats behavioural suite cmds: @@ -61,11 +72,13 @@ tasks: - lefthook run pre-commit --all-files ci: - desc: Run everything CI runs + desc: Run the core quality gate cmds: - task: fmt-check - task: lint - task: examples - task: nushell - task: nushell-demo + - task: yaml-schemas + - task: ai-integrations - task: test diff --git a/assets/logo.svg b/assets/logo.svg index 862e472..6f203de 100644 --- a/assets/logo.svg +++ b/assets/logo.svg @@ -1,5 +1,5 @@ - shell-skill + Shell Skill Kit diff --git a/assets/social-preview.png b/assets/social-preview.png index 378136c..f952b28 100644 Binary files a/assets/social-preview.png and b/assets/social-preview.png differ diff --git a/assets/social-preview.svg b/assets/social-preview.svg new file mode 100644 index 0000000..59785f2 --- /dev/null +++ b/assets/social-preview.svg @@ -0,0 +1,35 @@ + + Shell Skill Kit social preview + Brand preview for Shell Skill Kit, a test-enforced shell rule pack for AI coding agents. + + + + + + + + + + + + + + + + + + + + + + Shell Skill Kit + test-enforced shell rules for AI coding agents + + Bash + Zsh + POSIX sh + Nushell + ShellCheck + Codex + + diff --git a/lefthook.yml b/lefthook.yml index 448a0e3..b5b1407 100644 --- a/lefthook.yml +++ b/lefthook.yml @@ -1,3 +1,4 @@ +# yaml-language-server: $schema=https://json.schemastore.org/lefthook.json # lefthook.yml — Git hooks via Lefthook (https://lefthook.dev). # # A single static Go binary, no Python runtime — consistent with this repo's @@ -40,6 +41,15 @@ pre-commit: glob: "*.nu" run: ./tools/check-nushell.sh + yaml-schemas: + glob: "*.{yml,yaml,cff}" + run: ./tools/check-yaml-schemas.sh + + # Codex/ChatGPT discovery surfaces. This is cheap and self-scans, so + # it runs on every pre-commit to catch extensionless repo-scope skill links. + ai-integrations: + run: ./tools/check-ai-integrations.sh + # JSON validity (replaces pre-commit's check-json), via nu — already required. json-valid: glob: "*.json" @@ -52,7 +62,7 @@ pre-commit: # Trailing whitespace and final newline (fail-only, no mutation; portable). # Markdown is excluded — it uses two trailing spaces for hard line breaks. whitespace: - glob: "*.{sh,bash,nu,json,yml,yaml}" + glob: "*.{sh,bash,nu,json,yml,yaml,cff}" run: | status=0 for f in {staged_files}; do diff --git a/llms.txt b/llms.txt new file mode 100644 index 0000000..ff7c555 --- /dev/null +++ b/llms.txt @@ -0,0 +1,34 @@ +# Shell Skill Kit + +> Test-enforced Agent Skills for safe shell: Bash, Zsh, POSIX sh, Nushell, +> shebangs, streams, and common generated-script failure modes. + +Repository: https://github.com/posidoni/shell-skill +License: MIT +Package name: shell-skill + +## Start Here + +- [README.md](README.md): public overview, install paths, and skill map. +- [AGENTS.md](AGENTS.md): canonical coding-agent instructions for this repo. +- [CHATGPT.md](CHATGPT.md): Codex and ChatGPT packaging notes. +- [CONTRIBUTING.md](CONTRIBUTING.md): example contract and verification gate. +- [REGISTRY.md](REGISTRY.md): provider compatibility and directory listings. +- [.agents/README.md](.agents/README.md): Codex repo-scope skill discovery notes. +- [.codex/config.toml](.codex/config.toml): trusted Codex project defaults. + +## Portable Skills + +- Codex repo-scope symlinks: [.agents/skills/](.agents/skills/) +- [skills/shell/SKILL.md](skills/shell/SKILL.md): the single entry point — tool selection (jq/yq/sd/nu/Python over awk+sed), interpreter choice, the Bash non-negotiables, then routes into reference/ per dialect. + +## References + +- [reference/shell-standards.md](reference/shell-standards.md) +- [reference/bash.md](reference/bash.md) +- [reference/posix-sh.md](reference/posix-sh.md) +- [reference/zsh.md](reference/zsh.md) +- [reference/nushell.md](reference/nushell.md) +- [reference/shebang.md](reference/shebang.md) +- [reference/streams.md](reference/streams.md) +- [reference/meta-guidance.md](reference/meta-guidance.md) diff --git a/reference/cli-cheatsheets.md b/reference/cli-cheatsheets.md new file mode 100644 index 0000000..e427019 --- /dev/null +++ b/reference/cli-cheatsheets.md @@ -0,0 +1,146 @@ +# CLI cheatsheets + +Cached essentials for the tools this kit sends you to. **Verified against installed +versions, not recalled** — the versions are recorded so a future reader knows when to +re-check. + +The point of this file is not to replace `--help`. It is to record the handful of +**defaults that silently do the wrong thing**, which `--help` states plainly but +nobody reads until after they have been bitten. + +Verified 2026-07-19: `sd 1.0.0` · `rg 15.2.0` · `fd 10.4.2` · `nu 0.114.1` · +`jq 1.7.1` · `yq 4.53.3`. + +## How to check anything here + +```sh + --help # first, always — matches the installed version +man -w # is there a man page at all? + --version # before trusting any remembered flag +``` + +`nu` and `sttr` ship **no** man page. `sd`, `rg`, `fd`, `jq`, `yq` do. + +--- + +## fd — find files + +```sh +fd pattern # regex by default +fd -g '*.log' # glob mode +fd -e db # by extension +fd -t f / -t d / -t l # files / dirs / symlinks +fd -x cmd {} # execute per result (parallel) +fd -X cmd # execute once with all results +``` + +**The gotcha that costs you an hour:** `fd` skips hidden files **and** honours +`.gitignore`, `.ignore`, `.fdignore` and the global ignore file. `-H` only fixes the +first half. + +```sh +fd -H -e db # 0 results — files were gitignored +fd -H -I -e db # 3 results ← -I / --no-ignore is the other half +``` + +A `.db` or `.env` you are hunting is *usually* gitignored, which is precisely why you +are hunting it. Reach for `-HI` when searching for state and data files. + +## rg — search contents + +```sh +rg pattern # recursive, respects .gitignore, skips hidden +rg -HI pattern # ...unless you say otherwise (same trap as fd) +rg -l pattern # filenames only +rg -o pattern # only the matched part +rg -U 'a\n.*b' # -U/--multiline: patterns may cross lines +rg -t py pattern # restrict by file type +rg --json pattern # structured output, parseable +rg -A3 -B1 pattern # context after / before +rg -c pattern # count per file +``` + +Same ignore semantics as `fd`. `rg --json` beats parsing `rg` text output. + +## sd — substitute (use instead of sed) + +```sh +sd 'find' 'replace' file.txt # in place, by default +sd -p 'find' 'replace' file.txt # -p/--preview: show, do not write +sd -F 'literal' 'replace' file # -F: no regex, treat as fixed string +sd -n 2 'find' 'replace' file # limit replacements per file +cat f | sd 'a' 'b' # reads STDIN when no file given +``` + +Captures are `$1`, `$2` — not `\1`. **`sd` writes in place by default**, so use `-p` +first on anything you cannot regenerate. + +Why `sd` and not `sed`: there is no `sed -i` invocation portable across BSD and GNU. +`sed -i 's/a/b/' f` works on GNU and errors on macOS; `sed -i '' 's/a/b/' f` works on +macOS and creates a file named `''` on GNU. `sd` behaves identically everywhere. + +## nu — structured shell + +```sh +nu -n -c '...' # agent/CI: -n = --no-config-file, deterministic +nu --stdin -c 'print $in' +nu --no-newline -c '...' # for command substitution +nu --ide-check 0 script.nu # parse + type check, no execution +``` + +Without `-n`, `nu -c` loads the user's `config.nu`/`env.nu` and inherits their +aliases, `$env`, and any parse-time `source`. See +[`nushell.md`](nushell.md) for the language itself. + +Useful shapes: + +```nu +ls **/*.log | where size > 10mb | sort-by size --reverse | first 10 +glob **/node_modules --no-file | each {|p| {path: $p, size: (du $p | get 0.apparent)} } +open data.json | get items | where active | select name id +ps | where cpu > 10 | select pid name cpu +^git status --short | complete | get stdout # ^ = external, complete = exit code +``` + +`$nu` has `home-path`? **No** — that was a wrong guess that cost two failed attempts. +Check `$nu | columns` before using any `$nu.*` field. + +## jq — JSON + +```sh +jq -r .field # -r: raw, no surrounding quotes +jq -c . # compact, one line — good for piping +jq -e '.x' # exit non-zero if null/false — usable in `if` +jq -s '.' # slurp multiple inputs into one array +jq --arg k "$v" '.[$k]' # pass a shell value in SAFELY, never interpolate +jq 'to_entries[] | "\(.key)=\(.value)"' +``` + +Never build a `jq` program by string-interpolating shell variables; use `--arg` / +`--argjson`. + +## yq — YAML / TOML / XML + +Mike Farah's Go `yq` (v4), not the Python wrapper — the syntaxes differ. + +```sh +yq '.field' file.yaml +yq -i '.version = "0.3.0"' file.yaml # -i: in place +yq -o json '.' file.yaml # convert +yq -p toml '.tool' file.toml # -p: input format +yq ea '. as $i ireduce ({}; . * $i)' *.yaml # merge multiple docs +``` + +## sttr — string transforms + +No `--help` and no man page in this install; run `sttr` with no arguments for its +interactive picker, or `sttr