# Pin shortcuts

> Create and remove standalone harness shortcuts (for example `/audit`) that redirect to `/impeccable <command>` across discovered skill directories.

- Repository: pbakaus/impeccable
- GitHub: https://github.com/pbakaus/impeccable
- Human docs: https://grok-wiki.com/public/docs/pbakaus-impeccable-adadc04d8de4
- Complete Markdown: https://grok-wiki.com/public/docs/pbakaus-impeccable-adadc04d8de4/llms-full.txt

## Source Files

- `skill/scripts/pin.mjs`
- `skill/SKILL.src.md`
- `skill/scripts/command-metadata.json`
- `scripts/lib/utils.js`
- `tests/pin.test.mjs`

---

---
title: "Pin shortcuts"
description: "Create and remove standalone harness shortcuts (for example `/audit`) that redirect to `/impeccable <command>` across discovered skill directories."
---

`skill/scripts/pin.mjs` creates and removes lightweight standalone skill shims so a design sub-command can appear as its own harness skill (for example `/audit` or `$audit`) while still executing the full `/impeccable <command>` or `$impeccable <command>` workflow. The Impeccable skill routes pin requests through this script; it is not an `npx impeccable` CLI sub-command.

## What a pin is

A pin is a one-file skill directory named after a valid design sub-command:

```text
<project-root>/<harness>/skills/<command>/SKILL.md
```

That file is a redirect shim, not a second implementation of the command. When the harness loads the pinned skill, the model is instructed to invoke `impeccable <command>` with the same arguments and follow that workflow.

| Property | Value |
|---|---|
| Source script | `skill/scripts/pin.mjs` (shipped into each provider skill tree as `…/impeccable/scripts/pin.mjs`) |
| Metadata source | Sibling `command-metadata.json` (`description`, `argumentHint`) |
| Safety marker | `<!-- impeccable-pinned-skill -->` |
| Scope | Project root only; every discovered harness that already has Impeccable installed |
| Not pinnable | Utility routes such as `doctor` and `hooks` (they are not in `VALID_COMMANDS`) |

## Prerequisites

1. Impeccable is installed under at least one harness skills directory as `impeccable` or the legacy prefixed name `i-impeccable`.
2. The process runs from (or under) a project root that has `package.json`, `.git`, or `skills-lock.json` (the script walks up from `cwd` to find one).
3. Node can execute the installed script path.

If no harness directory contains Impeccable, pin prints `No harness directories with impeccable installed found.` and exits `0` without writing files.

## Usage

### Via the skill (agent path)

SKILL source instructs the agent:

```bash
node <scripts_path>/pin.mjs <pin|unpin> <command>
```

`<scripts_path>` is the provider-local path to the installed skill scripts (for example `.claude/skills/impeccable/scripts` or `.cursor/skills/impeccable/scripts`). After the agent runs the script, it should report the script result concisely and relay stderr verbatim on error.

### Direct invocation

From a project that already has Impeccable installed under one or more harness dirs:

```bash
node .claude/skills/impeccable/scripts/pin.mjs pin audit
node .claude/skills/impeccable/scripts/pin.mjs unpin audit
```

Any copy of the script under an installed harness works; the script discovers **all** eligible harnesses from the project root, not only the harness that owns the script path.

### Arguments

| Argument | Required | Values |
|---|---|---|
| action | yes | `pin` or `unpin` |
| command | yes | One of `VALID_COMMANDS` (see below) |

Missing arguments, an unknown action, or an unknown command exit with code `1` and print usage or the available command list.

## Pinnable commands

`VALID_COMMANDS` in `pin.mjs` (23 names):

| Build / setup | Evaluate | Refine | Enhance | Fix | Iterate |
|---|---|---|---|---|---|
| `craft`, `init`, `extract`, `document`, `shape` | `critique`, `audit` | `polish`, `bolder`, `quieter`, `distill`, `harden`, `onboard` | `animate`, `colorize`, `typeset`, `layout`, `delight`, `overdrive` | `clarify`, `adapt`, `optimize` | `live` |

These are the design sub-commands under the single `impeccable` skill. Maintenance utilities (`doctor`, `hooks`, pin itself) are intentionally excluded so they do not expand the harness skill menu.

Descriptions and `argument-hint` values for pinned frontmatter come from `skill/scripts/command-metadata.json`. If a key is missing there, the generated description falls back to `Shortcut for <prefix>impeccable <command>.` and the hint falls back to `[target]`.

## Harness discovery

`HARNESS_DIRS` scanned under the project root:

```text
.claude  .cursor  .gemini  .codex  .agents  .agent  .github  .grok
.trae  .trae-cn  .pi  .opencode  .kiro  .rovodev  .vibe  .qoder
```

For each harness, the script only acts when:

```text
<harness>/skills/impeccable
```

or

```text
<harness>/skills/i-impeccable
```

exists. Empty harness folders without Impeccable are ignored.

### Command prefix per harness

| Harnesses | Prefix written into the pin body |
|---|---|
| `.codex`, `.agents` | `$` (for example `$impeccable audit`) |
| All other harnesses in the list | `/` (for example `/impeccable audit`) |

`tests/pin.test.mjs` asserts this split when pinning `audit` into `.claude`, `.cursor`, `.agents`, and `.codex`.

## Pin behavior

For each eligible `…/skills` directory:

1. Build `SKILL.md` from metadata and the harness command prefix.
2. If `<skills>/<command>/` already exists and its `SKILL.md` does **not** contain the pin marker, log `SKIP: … (non-pinned skill already exists)` and leave it alone.
3. Otherwise create the directory and write (or overwrite) the pinned `SKILL.md`.
4. Log `+ <skillDir>` for each write.

When at least one location is written:

```text
Pinned '<command>' as a standalone shortcut in N location(s).
Use the pinned command directly in each harness.
```

Re-pinning an already pinned skill is allowed: the marker identifies it as owned by Impeccable, so the file is rewritten with current metadata.

### Generated pin shape

```yaml
---
name: audit
description: "Run technical quality checks across accessibility, performance, theming, responsive design, and anti-patterns. …"
argument-hint: "[area (feature, page, component...)]"
user-invocable: true
---

<!-- impeccable-pinned-skill -->

This is a pinned shortcut for `/impeccable audit`.

Invoke /impeccable audit, passing along any arguments provided here, and follow its instructions.
```

On Codex / Agents harnesses the body uses `$impeccable audit` instead of `/impeccable audit`.

## Unpin behavior

For each eligible harness:

1. Require `<skills>/<command>/SKILL.md` to exist.
2. Require the pin marker in that file; otherwise log `SKIP: … (not a pinned skill)` and do not delete.
3. Remove the entire skill directory recursively.
4. Log `- <skillDir>`.

Outcomes:

| Case | Message | Exit |
|---|---|---|
| One or more pins removed | `Unpinned '<command>' from N location(s).` | `0` |
| Nothing removed | `No pinned '<command>' shortcut found.` | `0` |

## Exit codes and messages

| Situation | Exit | Notes |
|---|---|---|
| Missing action/command | `1` | Prints usage and available commands |
| Unknown action | `1` | `Unknown action: … Use 'pin' or 'unpin'.` |
| Unknown command | `1` | Lists `VALID_COMMANDS` |
| Pin with no Impeccable harnesses | `0` | Message only; no files written |
| Pin success | `0` | Even if some dirs were skipped as non-pinned |
| Unpin with nothing to remove | `0` | Message only |

## Workflow

<Steps>
  <Step title="Install Impeccable into the harnesses you use">
    Install or link the skill so at least one of `<harness>/skills/impeccable` or `…/i-impeccable` exists in the project.
  </Step>
  <Step title="Pin a frequent command">
    Ask the agent to pin (or run the script directly), for example:

```bash
node .claude/skills/impeccable/scripts/pin.mjs pin audit
```

  </Step>
  <Step title="Verify the shim">
    Confirm `<harness>/skills/<command>/SKILL.md` exists, contains `<!-- impeccable-pinned-skill -->`, and names the correct `<prefix>impeccable <command>` redirect.
  </Step>
  <Step title="Use the shortcut">
    In the harness command menu, invoke the short name (`/audit`, `$audit`, and so on). The agent should load the pin and then run the full Impeccable sub-command with your arguments.
  </Step>
  <Step title="Unpin when finished">
```bash
node .claude/skills/impeccable/scripts/pin.mjs unpin audit
```
    Only directories that still carry the pin marker are removed.
  </Step>
</Steps>

## Safety and constraints

- **User skills are preserved.** Pin never overwrites a pre-existing skill directory whose `SKILL.md` lacks the pin marker. Unpin never deletes such a directory.
- **No global install scan.** Only project-root harness trees are considered.
- **No design logic in the pin.** The pin file does not load `reference/<command>.md`; it only redirects to the main skill.
- **Menu cost.** Each pin adds another top-level skill entry in every eligible harness. Prefer pinning high-frequency commands rather than every sub-command.
- **Not a package CLI.** `npx impeccable pin` is not defined; use the skill script path.

## Maintainer notes

When adding a new design sub-command that should be pinnable:

1. Add the command to the router / skill surface (`skill/SKILL.src.md`, `IMPECCABLE_SUB_COMMANDS` or related build lists as required by the new-command checklist).
2. Add metadata to `skill/scripts/command-metadata.json`.
3. Add the name to `VALID_COMMANDS` in `skill/scripts/pin.mjs`.
4. Keep `doctor` and similar maintenance tools out of `VALID_COMMANDS` unless product intent changes.

Regression coverage lives in `tests/pin.test.mjs` (provider command-prefix rendering for pin content).

## Troubleshooting

| Symptom | Likely cause | Fix |
|---|---|---|
| `No harness directories with impeccable installed found.` | Skills not installed under any listed harness | Install/link Impeccable into the project harnesses you use |
| `SKIP: … (non-pinned skill already exists)` | A real skill already owns that name | Rename or remove the conflicting skill, or choose a different pin |
| `Unknown command: …` | Name not in `VALID_COMMANDS` | Use a design sub-command from the table above |
| Pin created but harness still shows only `/impeccable …` | Harness cache or skill discovery lag | Restart the harness / reload skills for that project |
| `$` vs `/` mismatch | Expected: `.codex` / `.agents` use `$` | Use the prefix for that harness; do not hand-edit pins across providers |
| Unpin left a skill behind | File lacked the pin marker | Inspect `SKILL.md`; if it is user-authored, remove it manually only if intentional |

## Related pages

<CardGroup>
  <Card title="Commands and routing" href="/commands-and-routing">
    Single `/impeccable` skill, sub-command table, and Setup load order that pins redirect into.
  </Card>
  <Card title="Skill commands reference" href="/skill-commands-reference">
    Catalog of pinnable sub-commands, argument hints, and reference files.
  </Card>
  <Card title="Provider harnesses" href="/provider-harnesses">
    Harness directories, install aliases, and command-prefix differences across providers.
  </Card>
  <Card title="Installation" href="/installation">
    Install paths that place `impeccable` under harness `skills/` trees pin.mjs discovers.
  </Card>
  <Card title="Contributing" href="/contributing">
    Checklist for adding commands, including updating `VALID_COMMANDS` in `pin.mjs`.
  </Card>
</CardGroup>