feat!: collapse seven skills into one router skill

[posidoni]

Why

The kit exported seven separate skills (bash, zsh, posix-sh, nushell, shell-standards, shebang, streams). An agent had to already know which one it needed — but the decision an agent actually faces is "should this be shell at all?", and that question was answered by none of them.

Worse, the seven descriptions competed with each other on load, so the most useful one frequently lost.

What changed

One router skill (skills/shell/). It answers "should this be shell?" first — usually the answer is jq, yq, sd, nu, Python or bun — then routes to the per-shell reference for whatever survives that question. The seven SKILL.md files collapse into one; their content moves to reference/, loaded on demand.

Trigger-first description. The description now fires on the act ("you are about to type awk, sed, cut, or a second pipe") rather than on a request to write shell. Skills lose to recency in a long context; a situational trigger fires when it matters.

New reference/cli-cheatsheets.md. Cached essentials for fd, rg, sd, nu, jq, yq, sttr — verified against installed versions, which are recorded so a reader knows when to re-check. It deliberately does not replace --help; it records the defaults that silently do the wrong thing:

• fd/rg honour .gitignore as well as hiding dotfiles. -H fixes only half — you need -I. This costs an hour every time, and the file you are hunting (.db, .env) is usually gitignored, which is precisely why you are hunting it.
• 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. Hence sd.
• $nu.home-path does not exist — check $nu | columns before using any $nu.* field.

New reference/pipelines.md. Replacement table, BSD-vs-GNU traps, worked rewrites. Hard stop: three or more pipeline stages, or any awk beyond {print $1}, means write a script file.

nu -n -c guidance. Without -n/--no-config-file, nu -c loads the user's config.nu/env.nu and inherits their aliases, $env, and any parse-time source — so the command stops being deterministic. Same argument as pinning an interpreter.

AI-integration surfaces. REGISTRY.md, llms.txt, JSON schemas for Codex plugin / OpenAI skill metadata / Serena project, plus tools/check-ai-integrations.sh and tools/check-yaml-schemas.sh wired into the Taskfile so the surfaces are checked, not just claimed.

Breaking

feat! — the six removed skill names no longer resolve. Anything referencing shell-standards, bash, zsh, posix-sh, nushell, shebang, or streams as a skill must now use shell. The content is not gone; it moved to reference/ behind the router.

Verification

task ci passes on this branch: ShellCheck across all non-bad scripts, the good-vs-bad example contract (every .bad.sh must produce its documented SC code), nu --ide-check on every .nu, the Nushell startup-order demo (all 3 cases), the bats suite, formatting, and the YAML-schema check.

🤖 Generated with Claude Code

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.

[gemini-code-assist]

Code Review

This pull request consolidates seven separate shell skills into a single, unified shell skill and introduces new integration gates and configurations for Codex, ChatGPT, Claude Code, and Serena. Key additions include JSON Schema modelines for YAML-like files, automated validation scripts for schemas and AI integrations, and updated documentation reflecting the new 'Shell Skill Kit' branding. Feedback on the changes suggests optimizing tools/check-yaml-schemas.sh by using the Bash builtin read -r instead of spawning sed subprocesses in a loop, and leveraging Nushell in tools/check-ai-integrations.sh to parse YAML frontmatter robustly instead of using a fragile awk script.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.

[gemini-code-assist]

Using sed in a loop to read the first line of each file creates a new subprocess for every file, which can significantly degrade performance when checking many files. Additionally, the unquoted regex pattern ^#\ yaml-language-server:\ \$schema= contains an unquoted $ inside double brackets, which can lead to parsing and portability issues across different shell versions and platforms.

We can optimize this by using the Bash builtin read -r to read the first line without forking a subprocess, and by storing the regex pattern in a variable to ensure robust and portable matching.

Suggested change

	status=0
	while IFS= read -r file; do
	if [[ ! -f "$file" ]]; then
	continue
	fi
	first_line=$(sed -n '1p' "$file")
	if [[ ! $first_line =~ ^#\ yaml-language-server:\ \$schema= ]]; then
	printf 'missing first-line YAML schema comment: %s\n' "$file" >&2
	status=1
	fi
	status=0
	schema_pattern='^# yaml-language-server: \$schema='
	while IFS= read -r file; do
	if [[ ! -f "$file" ]]; then
	continue
	fi
	first_line=""
	read -r first_line < "$file" || :
	if [[ ! $first_line =~ $schema_pattern ]]; then
	printf 'missing first-line YAML schema comment: %s\n' "$file" >&2
	status=1
	fi

[gemini-code-assist]

Since Nushell (nu) is already a required dependency of this repository and is used extensively in this script, we can leverage it to parse the YAML frontmatter of SKILL.md files robustly. This avoids relying on a complex and potentially fragile hand-rolled awk parser for YAML frontmatter, aligning perfectly with the repository's guideline: 'Structured data deserves a structured tool'.

Suggested change

	skill_name=$(awk '
	$0 == "---" { fence++; next }
	fence == 1 && $1 == "name:" {
	sub(/^name:[[:space:]]*/, "", $0)
	gsub(/^["'\'']|["'\'']$/, "", $0)
	print $0
	exit
	}
	' "$skill_md")
	skill_name=\$(nu -c "open '$skill_md' | split row '---' | get 1 | from yaml | get name")