Documentation Index
Fetch the complete documentation index at: https://mintlify.com/modiqo/skillspec/llms.txt
Use this file to discover all available pages before exploring further.
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. |
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. |
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" |
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.
