shell-integration · git:20261110.bb488e2 · 2026-11-10 · sha256 1a7e4f4eb7ee9c97

shell-integration git:20261110.bb488e2A

Immutable. This exact content never changes and is served at /api/v1/blob/1a7e4f4eb7ee9c97.

No tool to install first
claude plugin marketplace add https://markdownregistry.com/mp/a/art_e4yia7x7w4jlbnjx/1a7e4f4eb7ee9c9731292e5314fd285c59e6832962e8fa09315cdb6c0a930cec.json

Then /plugin install shell-integration@markdownregistry-e4yia7x7w4jlbnjx in Claude Code. It installs this exact version, the one graded A here, pinned to the commit it was graded at, and leaves it there.

---
name: shell-integration
description: |-
    Use this skill whenever the resolved task scope includes shell code—including `domlib`, Fish configuration, `home/.local/bin` scripts, and `.hooks`—or adds or reconsiders a command entrypoint in this repository, including whether a Git helper should be a plain alias or a `home/.local/bin/git-*` script.

    Do not use it merely because the task runs terminal commands.

metadata:
    internal: true
---

# Domfiles Shell Integration

Use this skill as the canonical source for domfiles-specific shell integration, invariants, and validation.

For every Fish target, load `fish-shell-scripting` for portable language policy and workflow. For every POSIX shell target, load `posix-shell-scripting`. Apply this skill as the narrower domfiles layer when either language skill governs the same task.

## Investigate Tasks

1. Classify each in-scope shell file from its hashbang and syntax rather than its extension alone, then apply `fish-shell-scripting` or `posix-shell-scripting`.
2. Evaluate `home/.config/fish/functions/clone.fish` against the [Fish `clone` argument contract](../../PROJECT.md#fish-clone-argument-contract). Don’t report the absence of Git option parsing, option rejection, or reliable follow-up directory changes for unsupported option-bearing invocations.

For every non-Fish shell target and whenever the task touches `domlib`, a Fish `__domfiles_*` helper, shared `$DOMFILES_*` state, or command suppression, follow [`domlib` Integration](references/domlib-integration.md).

## Check Supported Environment Compatibility

- Evaluate every in-scope domfiles shell script’s interpreter, external commands, options, `PATH`, architecture, and default-shell assumptions against the [supported environment](../../PROJECT.md#supported-environment).
- Judge each requirement at its intended lifecycle stage—fresh bootstrap, synchronization, post-sync runtime, or development—and account for prerequisites that `domfiles sync` provisioned earlier.
- Place `__is_ci` and `__domfiles_is_ci` checks, including negations, last among predicates in compound conditions so CI detection doesn’t short-circuit the other checks. Preserve boolean grouping and keep CI-guarded actions conditional.
- Treat `domfiles dependencies` as the user-facing readiness check defined by [dependency status labels](../../PROJECT.md#dependency-status-labels). Add a row only for an established user-facing synchronization or runtime contract. Agent-only use or installation by synchronization alone doesn’t qualify a dependency.

## Apply Domfiles Shell Wording Constraints

Use the applicable language skill for semantic requirements and composition with `human-facing-writing`. Apply these domfiles-specific constraints after that workflow:

- Avoid first-person and subjective wording.
- Omit final punctuation from script comments and user-facing strings passed to `__print*`.
- Treat standalone headings and status labels as labels rather than sentences. Allow sentence case or title case, and do not require imperative voice.
- Use sentence case imperative voice for action and section comments.

## Manage Cache Variables

When a function stores a result in a global variable to avoid recomputing it on later calls, prefix the variable name with `__domfiles_cache_`. Treat that variable as private to its owning function. Callers must use the function’s output or exit status rather than read, query, or modify its cache.

## Choose Command Form and Location

Don’t report an existing command solely because another supported form could express it, except when [Git helper form](references/command-form-and-location.md#choose-git-helper-form) applies.

Before adding a command entrypoint or explicitly reconsidering an existing command’s form or location, follow [Command Form and Location](references/command-form-and-location.md).

Before reviewing a `home/.local/bin/git-*` entrypoint, follow [Git helper form](references/command-form-and-location.md#choose-git-helper-form).

## Evaluate Duplication and Reuse

- Don’t report the language-specific `home/.local/bin/domfiles-dev-lint-*` entrypoints as duplication merely because each retains its own default scope and lint command. Shared discovery and execution belong in `domlib`. See [development lint wrapper architecture](../../PROJECT.md#development-lint-wrapper-architecture) for the rationale.
- Consolidate shell implementations when they duplicate a substantial, virtually identical behavior pipeline that must remain aligned.
- Don’t report `__string_*` helpers or equivalent inline string operations as reimplementations.

## Apply Domfiles Fish Conventions

- Write unquoted command substitutions as `(…)` as an exception to `fish-shell-scripting`’s `$(…)` template. Use `"$(…)"` only inside double quotes, where `(…)` does not expand.

## Apply Domfiles POSIX Conventions

- Allow argumentless `echo` to print a blank line as an exception to `posix-shell-scripting`’s `printf` requirement.
- Report `find` commands that place `-maxdepth` anywhere other than immediately after the search path.

## Validate Changes

After editing, follow [Validate Shell Changes](references/validate-shell-changes.md) for lint, formatting, and shell integration checks.

## Validate Shell Audits, Diagnoses, and Reviews

Run the applicable language skill’s read-only validation and [check integration contracts](references/validate-shell-changes.md#check-integration-contracts). When invoked through `audit`, select checks and interpret their results under its [read-only audit boundary](../audit/references/repository-audit.md#keep-audits-read-only).