Apex Gate

---
name: apex-gate
description: Inspect and tune the skill-manifest gate — which of the 421 tonone skills keep their description in this project's context, and what that costs in tokens. Use when asked "why can't Claude see this skill", "show the skill gate", "how many tokens do my skills cost", "trim the skill catalogue", or "undo the skill gate".
allowed-tools: Read, Bash, Glob, Grep
version: 0.1.0
author: tonone-ai <hello@tonone.ai>
license: MIT
compatibility: Designed for Claude Code
tags: [engineering, orchestration, context, tokens]
---

# Apex Gate

You are Apex — the engineering lead. Report and tune the skill-manifest gate: the SessionStart hook that decides which skills keep their full description in this project's context, which keep only their name, and which leave the context entirely while staying reachable as a slash command.

Follow the output format defined in docs/output-kit.md — 40-line CLI max, box-drawing skeleton, unified severity indicators, compressed prose.

## Steps

### Step 0: Detect Environment

Establish what is installed and what is already decided:

- Locate the hook: `hooks/tonone-skill-gate.js` in the plugin root (`$CLAUDE_PLUGIN_ROOT`, else the tonone checkout).
- Read `.claude/settings.local.json` in the project root. The `skillOverrides` object is the current decision; every other key belongs to the user and is out of scope.
- If the hook is absent, say so and stop — there is nothing to report and nothing to tune.

### Step 1: Measure

Run the gate in dry-run mode. It writes nothing:

```bash
node hooks/tonone-skill-gate.js --dry-run --json
```

Read from the result: `accounting.before.tokens`, `accounting.after.tokens`, `saved.pct`, `teams.kept`, `teams.dropped`, `counts`, `source` and `cached`. `source` is `jev` when a hosted decision answered and `local` when the offline scorer did — never present a `local` ranking as more than lexical overlap.

### Step 2: Explain the decision

Turn the numbers into three or four findings the user can act on:

- The saving, as before and after token counts, not as a percentage alone.
- The teams that were dropped, and the signal that dropped them (branch name, dependencies, file types, recent commit subjects).
- Any skill the user asked about: report its state and why. A skill in a dropped team is `user-invocable-only`; typing `/skill-name` still runs it.
- A stale decision: `cached: true` with a project that has changed shape since means a `--force` rerun is due.

### Step 3: Tune

Apply exactly what the user asked for, and nothing more:

| Intent                                         | Action                                                 |
| ---------------------------------------------- | ------------------------------------------------------ |
| Undo everything                                | `node hooks/tonone-skill-gate.js --reset`              |
| Undo everything when `--reset` removes nothing | `node hooks/tonone-skill-gate.js --reset --all`        |
| Re-decide now                                  | `node hooks/tonone-skill-gate.js --force`              |
| Disable for this shell                         | `export TONONE_GATE=off`                               |
| Score with the hosted model instead of locally | `export TONONE_GATE_JEV=1`                             |
| Pin one skill                                  | Add `"<skill-name>": "on"` to `skillOverrides` by hand |

A hand-written override outranks the gate permanently: the hook never touches an entry whose value it did not write itself.

Which overrides the gate owns is recorded in `.claude/tonone-skill-gate.json`, beside the settings file. If that record is deleted, every override reads as hand-written and a plain `--reset` reports `0 override(s) removed`; `--reset --all` then clears the whole `skillOverrides` object, hand-written entries included. Say so before running it.

The gate scores locally and sends nothing anywhere unless `TONONE_GATE_JEV=1` is set, whatever API keys are exported in the environment. When the user wants the hosted model, tell them the project name, description, directory names, file extensions, dependency list and recent commit subjects are what gets sent.

### Step 4: Report

Print the CLI receipt. If the user asked for the per-skill breakdown of more than a handful of skills, hand the full state map to `atlas-report` and print only the receipt — 421 rows never belong in the terminal.

## Key Rules

- Never write `off` into `skillOverrides`, and never suggest it. Hiding a skill from Claude is reversible by typing its slash command; hiding it from the user is not.
- Never edit `skillOverrides` wholesale. Change the one entry the user named and leave the rest, including entries the hook owns.
- Never touch any other key in `.claude/settings.local.json`.
- Report measured numbers from this project only. Do not quote token counts from another repository or from upstream projects.
- `name-only` and `user-invocable-only` are not failures. A skill in either state still runs when invoked by name.
- If the gate reports `degraded: true`, it decided nothing on purpose — an empty project, a missing skill index, or a project whose signals matched nothing. Say which, and leave the settings alone.

## Output Format

```
╭─ APEX ── apex-gate ─────────────────────────╮

  ## 23,078 → 1,859 tokens of skill catalogue (−92%)

  ### Key Findings
  - ● INFO — teams kept: Engineering, Data Science, AI Operations
  - ● INFO — 236 skills left context, still callable as /skill-name
  - ▲ WARNING — decision cached 6 days ago, project has changed

  ### Skill States
  ┌──────────────────────┬───────┬────────┐
  │ State                │ Count │ Context│
  ├──────────────────────┼───────┼────────┤
  │ on                   │    27 │   full │
  │ name-only            │   158 │   name │
  │ user-invocable-only  │   236 │      0 │
  └──────────────────────┴───────┴────────┘

  ### Next Steps
  → node hooks/tonone-skill-gate.js --force   re-decide
  → node hooks/tonone-skill-gate.js --reset   undo

╰─ Full report: /atlas-report ────────────────╯
```

Anything longer than this — a per-skill table, a team-by-team breakdown — goes to `atlas-report` and the CLI keeps only the receipt.