feat: publish user-facing OpenShell skills separately

Problem Statement

OpenShell currently stores all agent skills under .agents/skills/, although they serve two different audiences:

OpenShell users and operators who need help using the CLI, writing policies, or troubleshooting deployments.
OpenShell contributors who develop, review, test, and release the project.

Because the Agent Skills CLI discovers .agents/skills/, running:

npx skills add NVIDIA/OpenShell

currently exposes repository-development workflows alongside the four skills intended for OpenShell users:

openshell-cli
generate-sandbox-policy
debug-inference
debug-openshell-cluster

OpenShell should provide a clear public skill collection while keeping contributor workflows associated with the repository.

Proposed Design

Separate skills by audience

Move the four user-facing skills to a top-level skills/ directory:

skills/
├── debug-inference/
├── debug-openshell-cluster/
├── generate-sandbox-policy/
└── openshell-cli/

Keep contributor and maintainer skills under .agents/skills/.

Mark contributor-only skills with:

metadata:
  internal: true

The Agent Skills CLI discovers both directories, so this metadata is required to exclude contributor workflows from ordinary public discovery. It is a discovery filter, not an access-control boundary.

Each skill should have one canonical location. Do not duplicate or bridge public skills under .agents/skills/.

Make public skills portable

The four public skills must work when installed outside an OpenShell source checkout.

Public skills should:

Use openshell --help as the authoritative source for installed CLI syntax.
Link to published OpenShell documentation for product concepts, configuration schemas, and operational guidance.
Avoid dependencies on repository-relative files under docs/, architecture/, and crates/.
Avoid source-build and E2E instructions unless they are relevant to product users.
Keep files under references/ only when they contain skill-specific reasoning or worked interactions that are not canonical product documentation.

Published documentation should remain the single source of truth. Command references, policy schemas, architecture documentation, and other product documentation should not be copied into skills.

For example, the existing openshell-cli/cli-reference.md largely duplicates CLI help and should be replaced with CLI self-discovery and links to published documentation. Policy-generation examples should remain only if they provide skill-specific guidance not already covered by the product docs.

Update documentation and validation

Update repository guidance to explain the two locations:

skills/ contains public, installable OpenShell skills.
.agents/skills/ contains repository contributor workflows.

Update relevant references in README.md, AGENTS.md, CONTRIBUTING.md, published contributor documentation, and other skills.

Extend sync-agent-infra to validate:

Public versus contributor skill placement.
Internal metadata on contributor skills.
Unique skill names.
Documentation inventories and cross-skill references.
Reference files and links.
That skill references do not duplicate canonical product documentation.

Contributor skills that rely on public skill content should reference its canonical path under skills/.

Definition of Done

The four user-facing skills live under skills/.
Contributor skills remain under .agents/skills/ and are marked internal.
npx skills add NVIDIA/OpenShell offers only the four public skills.
Public skills work outside an OpenShell checkout.
Public skills use published docs and CLI help instead of duplicating product documentation.
Contributor workflows use the new canonical skill paths where needed.
Documentation and skill-infrastructure validation reflect the new layout.

Alternatives Considered

Not applicable. This reorganizes the existing skill inventory by audience without changing product behavior.

Agent Investigation

Reviewed the existing issue inventory and found no matching proposal.
Reviewed the architecture index and current contributor guidance.
The repository currently contains 22 skills under .agents/skills/; four are primarily intended for users and operators.
The Agent Skills CLI currently exposes all 22.
A simulated split with internal metadata exposed only the intended four public skills.
Some public skills currently assume an OpenShell checkout or reference repository-level documentation and therefore need a portability pass.

Checklist

I've reviewed existing issues and the architecture docs
This is a design proposal, not a "please build this" request

🏗️ build-plan

Implementation Plan

Issue type: feat
Complexity: Medium
Confidence: High — current discovery behavior and the required filtering mechanism are verified

Summary

Separate OpenShell skills by audience: four portable user/operator skills will live under skills/, while contributor workflows remain under .agents/skills/ with internal metadata. Update skill content, documentation, cross-references, and validation so public installation exposes only the intended four skills without requiring a source checkout.

Scope

skills/: move and make portable openshell-cli, generate-sandbox-policy, debug-inference, and debug-openshell-cluster.
.agents/skills/: mark all contributor skills internal and update canonical public-skill references.
.agents/skills/sync-agent-infra/SKILL.md: validate both inventories, placement, metadata, unique names, references, links, and portability.
README.md, AGENTS.md, CONTRIBUTING.md: document the public-versus-contributor split and installation workflow.
docs/CONTRIBUTING.mdx, docs/get-started/quickstart.mdx: align published contributor and user guidance.

Implementation Steps

Move the four public skills to skills/, delete duplicated CLI reference material, and add metadata.internal: true to the 18 contributor manifests.
Make each public skill portable by using installed openshell --help as command authority, replacing repository-relative product references with published documentation, and removing source-build/E2E-only diagnostics.
Update canonical cross-references and expand sync-agent-infra checks for the two-directory model.
Update repository and published documentation, including npx skills add NVIDIA/OpenShell in the README.
Validate inventory, uniqueness, portability, local Agent Skills CLI discovery, documentation links, and pre-commit checks.

Test Plan

Unit tests: N/A — no executable product code changes.
Integration tests: Validate frontmatter, path/link inventories, public-skill portability, and local npx -y skills add . --list discovery of exactly four public skills.
E2E tests: N/A — gateway, sandbox, policy runtime, and compute-driver behavior are unchanged.

Risks & Open Questions

Preserve useful operator diagnostics while removing repository build and E2E implementation details from debug-openshell-cluster.
Retain worked policy examples only where they add skill-specific reasoning rather than duplicate canonical documentation.
Remote repository discovery cannot reflect the branch until merge; validate the branch locally.

Documentation Impact

Update README.md, AGENTS.md, CONTRIBUTING.md, docs/CONTRIBUTING.mdx, and docs/get-started/quickstart.mdx. No gateway configuration or compute-driver reference update is required.

Platform Compatibility

No SELinux or AppArmor impact; the change only affects Markdown, YAML frontmatter, and repository paths.

Revision 1 — initial plan

🏗️ build-from-issue-agent

Implementation Complete

PR: #2899

What was built

Separated four portable user/operator skills into skills/, marked 18 repository contributor workflows internal, removed duplicated and source-checkout-dependent public content, and updated validation and documentation for the two audiences.

Tests

Public discovery: exactly 4 skills found by the Agent Skills CLI
Inventory and portability checks: passed
Pre-commit: passed
Published docs validation: passed
Full local CI: passed
Unit tests added: N/A (content and metadata change)
Integration: local Agent Skills discovery and inventory validation
E2E: N/A (no runtime behavior changed)

Docs updated

README.md
AGENTS.md
CONTRIBUTING.md
docs/CONTRIBUTING.mdx
docs/get-started/quickstart.mdx

The issue will auto-close when the PR is merged.

feat(skills): separate public and contributor workflows

feat(skills): separate public and contributor workflows (NVIDIA#2899)

Navigation Menu

Repository navigation

feat: publish user-facing OpenShell skills separately #2736

Problem Statement

Proposed Design

Separate skills by audience

Make public skills portable

Update documentation and validation

Definition of Done

Alternatives Considered

Agent Investigation

Checklist

Implementation Plan

Summary

Scope

Implementation Steps

Test Plan

Risks & Open Questions

Documentation Impact

Platform Compatibility

Implementation Complete

What was built

Tests

Docs updated

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

feat: publish user-facing OpenShell skills separately #2736

Description

Problem Statement

Proposed Design

Separate skills by audience

Make public skills portable

Update documentation and validation

Definition of Done

Alternatives Considered

Agent Investigation

Checklist

Activity

johnnygreco commented on Aug 23, 2026

Implementation Plan

Summary

Scope

Implementation Steps

Test Plan

Risks & Open Questions

Documentation Impact

Platform Compatibility

johnnygreco commented on Aug 23, 2026

Implementation Complete

What was built

Tests

Docs updated

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions