feat: publish user-facing OpenShell skills separately

[johnnygreco]

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