skillspec visibility — Harness-Native Skill Visibility

skillspec visibility manages harness-native skill visibility for Codex and Claude Code. It writes native visibility controls — Codex agents/openai.yaml policy files, Claude settings.json skillOverrides, and Claude SKILL.md frontmatter disable-model-invocation flags — and produces a reversible manifest so any change can be undone precisely. Visibility controls affect whether a harness offers a skill implicitly (no explicit invocation needed), only when explicitly named, by name only, or not at all. This is distinct from the router: visibility controls harness-native discovery behavior, while the router adds active routing and selection logic on top of the discovered skill set.

`visibility plan`

Shows the planned visibility changes without applying them. Use this to preview what apply would do.

skillspec visibility plan \
  --roots <path>... \
  [--profile router-managed] \
  [--json]

Flag	Description
`--roots <path>...`	Harness skill root directories to scan. Required. Repeatable.
`--profile router-managed`	Visibility profile to plan. `router-managed` is the only named profile.
`--json`	Emit JSON plan report.

skillspec visibility plan \
  --roots ~/.agents/skills ~/.claude/skills \
  --json

`visibility apply`

Applies native harness visibility controls and writes a reversible manifest.

skillspec visibility apply \
  --roots <path>... \
  --manifest <path> \
  [--profile router-managed] \
  [--dry-run] \
  [--json]

Flag	Description
`--roots <path>...`	Harness skill root directories to scan. Required. Repeatable.
`--profile router-managed`	Visibility profile to apply. `router-managed` is the only named profile.
`--manifest <path>`	Path for the reversible visibility manifest. Required.
`--dry-run`	Plan without writing files.
`--json`	Emit JSON apply report.

For each skill, apply writes or updates:

Codex — <skill-dir>/agents/openai.yaml with policy.allow_implicit_invocation: true/false.
Claude (repo-local) — .claude/settings.json with a skillOverrides.<skill-name> entry.
Claude (shared .agents root) — SKILL.md frontmatter disable-model-invocation flag.

Always run visibility plan first to review planned changes before running visibility apply.

# Preview first
skillspec visibility plan \
  --roots ~/.agents/skills \
  --json

# Apply and record a reversible manifest
skillspec visibility apply \
  --roots ~/.agents/skills \
  --manifest ~/.skillspec/router/visibility-manifest.json \
  --json

`visibility restore`

Restores exact file snapshots from a visibility manifest. Does not infer previous state — it reads the before_content snapshots recorded by apply and writes them back exactly.

skillspec visibility restore \
  --manifest <path> \
  [--dry-run] \
  [--json]

Flag	Description
`--manifest <path>`	Path to the visibility manifest written by a previous `apply`.
`--dry-run`	Preview the restore without writing files.
`--json`	Emit JSON restore report.

# Preview the restore
skillspec visibility restore \
  --manifest ~/.skillspec/router/visibility-manifest.json \
  --dry-run \
  --json

# Restore
skillspec visibility restore \
  --manifest ~/.skillspec/router/visibility-manifest.json \
  --json

Workspace install visibility policies

The skillspec workspace install command accepts a --visibility-policy flag that controls which packages receive implicit versus manual-only visibility when --apply-visibility is used. These values are not skillspec visibility --profile values — they apply only to workspace install.

Policy	Description
`entry-implicit`	Entry packages remain implicit; shared, helper, and wrapper packages are manual-only. This is the default when `--apply-visibility` is used during workspace install.
`all-implicit`	All workspace packages set to implicit invocation.
`all-manual`	All workspace packages set to manual-only invocation.
`none`	No visibility changes applied during workspace install.

The skillspec visibility command itself uses --profile router-managed as its profile selector. For standalone visibility management outside of workspace install, pass --profile router-managed to visibility plan and visibility apply.

When the router is installed and enabled, visibility is managed automatically by router install, router enable, router disable, and router index refresh. Use skillspec visibility directly only for standalone visibility management outside the router lifecycle, or when you need fine-grained control over individual skill visibility.

Visibility values and harness mapping

Visibility value	Codex (`agents/openai.yaml`)	Claude (`settings.json`)
`implicit`	`allow_implicit_invocation: true`	`skillOverrides.<name>: "on"`
`manual-only`	`allow_implicit_invocation: false`	`skillOverrides.<name>: "user-invocable-only"`
`name-only`	`allow_implicit_invocation: false` + manifest note	`skillOverrides.<name>: "name-only"`
`off`	`allow_implicit_invocation: false` + manifest note	`skillOverrides.<name>: "off"`

Codex has no native name-only or off state. The manifest records these values for the router so they survive a restore.

Visibility manifest

The manifest is a JSON file with schema skillspec/visibility-manifest/v1. It records:

Each changed skill’s name, paths, harness kind, before and after visibility states.
File-level snapshots of every modified file with before and after content.

The manifest is additive: subsequent apply calls merge new changes rather than overwriting the record of prior changes. This means restore always reverts to the state before the first apply for each skill, not the state before the most recent one.

Distinction from the router

	Visibility	Router
What it controls	Whether the harness offers a skill natively	Whether requests are actively routed to a specific skill
Files modified	`agents/openai.yaml`, `settings.json`, SKILL.md frontmatter	Router skill package, guard hook, index
Effect on skill list	Affects what the harness presents to the model	Affects which skill is loaded for a given task
Required for routing	No, but router install applies it automatically	Yes

skillspec router install — Install the router; automatically manages visibility.
skillspec router index refresh — Refresh the router index and reapply router-managed visibility.
skillspec skills set-visibility — Set visibility for a single skill.
skillspec status — View current visibility state alongside router and skill installation state.

Runtime Commands

Authoring Commands

Installation & Discovery

skillspec visibility — Harness-Native Skill Visibility

`visibility plan`

`visibility apply`

`visibility restore`

Workspace install visibility policies

Visibility values and harness mapping

Visibility manifest

Distinction from the router

​visibility plan

​visibility apply

​visibility restore

​Workspace install visibility policies

​Visibility values and harness mapping

​Visibility manifest

​Distinction from the router

​Related commands

`visibility plan`

`visibility apply`

`visibility restore`

Workspace install visibility policies

Visibility values and harness mapping

Visibility manifest

Distinction from the router

Related commands