docs(skills): align public and contributor guidance

Signed-off-by: Johnny Greco <jogreco@nvidia.com>

Author: johnnygreco

.agents/skills/sync-agent-infra/SKILL.md

@@ -14,7 +14,7 @@ Detect and fix drift across the agent-first infrastructure files. These files re
 | `AGENTS.md` | Project identity, workflow chains, architecture overview, issue/PR conventions, skill maintenance pointer |
 | `CONTRIBUTING.md` | Skills table, workflow chains, "When to Open an Issue" guidance, skill references |
 | `CONTRIBUTING.md` issue lifecycle section | Human-facing issue states, roadmap decisions, acceptance signals, and direct-versus-queued agent ownership |
-| `README.md` | "Built With Agents" section, "Explore with your agent" skill references |
+| `README.md` | "Use OpenShell with Your Agent" and "Built With Agents" sections |
 | `.github/ISSUE_TEMPLATE/bug_report.yml` | Skill name references in diagnostic guidance |
 | `.github/ISSUE_TEMPLATE/feature_request.yml` | Skill name references in investigation guidance |
 | `.github/ISSUE_TEMPLATE/config.yml` | Contact link text referencing skills |
@@ -150,7 +150,7 @@ For each file in the table above, check for the following inconsistencies:
 3. **Unique names** — Parse the `name` field from every `SKILL.md` under both roots. Every name must be globally unique and match the documented inventory.
 4. **Local references** — Every relative Markdown link and referenced file in a skill must resolve within that installed skill directory unless the reference is an explicit published URL.
 5. **Canonical paths** — Contributor skills that name the source location of a public skill must use `skills/<name>/...`, never `.agents/skills/<name>/...`.
-6. **Public portability** — Public skills must not require repository-relative files under `docs/`, `architecture/`, `crates/`, `deploy/`, or `.agents/`; source builds; `mise`; or repository E2E workflows. Use installed `openshell --help` for command syntax and `https://docs.nvidia.com/openshell/latest/` links for product documentation.
+6. **Public portability** — Public skills must not require repository-relative files under `docs/`, `architecture/`, `crates/`, `deploy/`, or `.agents/`; source builds; `mise`; or repository E2E workflows. Use installed `openshell --help` for command syntax and Markdown endpoints under `https://docs.nvidia.com/openshell/latest/` (URLs ending in `.md`) for product documentation.
 7. **No canonical documentation copies** — Review public reference files and large command/schema blocks. Remove material that merely copies CLI help, policy schemas, architecture docs, or published operational documentation; retain only skill-specific reasoning and worked interactions.
 8. **Discovery** — Run `npx -y skills add . --list` from a clean checkout or disposable copy. It must list exactly the four public skills. Remove any generated lock file or installed directory after the check.
 

AGENTS.md

@@ -56,6 +56,7 @@ These pipelines connect skills into end-to-end workflows. Individual skill files
 | `crates/openshell-driver-docker/` | Docker compute driver | In-process `ComputeDriver` backend for local Docker sandbox containers |
 | `crates/openshell-driver-podman/` | Podman compute driver | In-process `ComputeDriver` backend for local Podman sandbox containers |
 | `crates/openshell-driver-vm/` | VM compute driver | Standalone libkrun-backed `ComputeDriver` subprocess (embeds its own rootfs + runtime) |
+| `crates/openshell-driver-mxc/` | Microsoft MXC compute driver | In-process Windows AppContainer and isolation-session compute backend |
 | `crates/openshell-prover/` | Policy prover | Policy verification and proof generation |
 | `crates/openshell-server-macros/` | Server macros | Compile-time helpers for gateway RPC authorization |
 | `crates/openshell-supervisor-middleware/` | Middleware runtime | Generic middleware registry, remote service integration, and chain execution |
@@ -70,7 +71,7 @@ These pipelines connect skills into end-to-end workflows. Individual skill files
 | `docs/` | Published docs | MDX pages, navigation, and content assets |
 | `fern/` | Docs site config | Fern site config, components, and theme assets |
 | `skills/` | Public agent skills | Installable workflows for using and operating OpenShell |
-| `.agents/skills/` | Agent skills | Workflow automation for development |
+| `.agents/skills/` | Contributor agent skills | Repository-aware workflows for developing OpenShell |
 | `.agents/agents/` | Agent personas | Sub-agent definitions (e.g., reviewer, doc writer) |
 | `architecture/` | Architecture docs | Design decisions and component documentation |
 

CONTRIBUTING.md

@@ -442,7 +442,8 @@ These are the primary `mise` tasks for day-to-day development:
 | `fern/`         | Fern site config, components, and theme assets |
 | `architecture/` | Architecture docs and plans                   |
 | `rfc/`          | Request for Comments proposals                |
-| `.agents/`      | Agent skills and persona definitions          |
+| `skills/`       | Public skills for using and operating OpenShell |
+| `.agents/`      | Contributor skills and persona definitions    |
 
 ## RFCs
 

README.md

@@ -16,7 +16,7 @@
 
 OpenShell is the safe, private runtime for autonomous AI agents. It provides sandboxed execution environments that protect your data, credentials, and infrastructure — governed by declarative YAML policies that prevent unauthorized file access, data exfiltration, and uncontrolled network activity.
 
-OpenShell is built agent-first. The project ships with agent skills for everything from gateway troubleshooting to policy generation, and we expect contributors to use them.
+OpenShell is built agent-first. It ships public agent skills for using and operating OpenShell, plus separate repository-aware workflows for contributors and maintainers.
 
 ## Quickstart
 
@@ -225,7 +225,7 @@ OpenShell is developed using the same agent-driven workflows it enables. Contrib
 - **Security review:** `review-security-issue` produces a severity assessment and remediation plan. `fix-security-issue` implements it.
 - **Repository maintenance:** `sync-agent-infra`, `update-docs-from-commits`, and other internal workflows keep code, documentation, and agent infrastructure consistent.
 
-All agent implementation work is human-gated: maintainers explicitly request a plan, agents propose it, maintainers approve it, and agents build. See [AGENTS.md](AGENTS.md) for the full workflow chain documentation.
+Agent implementation is human-directed: a user may request a phase directly, or maintainers may use the optional `agent:*` workflow to queue and approve planning and implementation. See [AGENTS.md](AGENTS.md) for the full workflow chain documentation.
 
 ## Getting Help
 
@@ -248,7 +248,7 @@ All agent implementation work is human-gated: maintainers explicitly request a p
 
 ## Contributing
 
-OpenShell is built agent-first. Issues should include a user story, problem statement, impact, and acceptance criteria. The impact should explain the consequences of the current behavior and why existing workarounds are insufficient. Feature requests also require a workflow-level proposed design and alternatives; bug reports add reproduction steps, environment details, and relevant logs. Once maintainers accept work, contributors should use the skills in `.agents/skills/` to investigate the current code and behavior, implement the change, and verify it. If an issue contains earlier diagnostics, verify them rather than relying on them. See [CONTRIBUTING.md](CONTRIBUTING.md) for the full agent skills table, contribution workflow, and development setup.
+OpenShell is built agent-first. Issues should include a user story, problem statement, impact, and acceptance criteria. The impact should explain the consequences of the current behavior and why existing workarounds are insufficient. Feature requests also require a workflow-level proposed design and alternatives; bug reports add reproduction steps, environment details, and relevant logs. Once work is authorized through the project workflow or a direct request, contributors should use the skills in `.agents/skills/` to investigate the current code and behavior, implement the change, and verify it. If an issue contains earlier diagnostics, verify them rather than relying on them. See [CONTRIBUTING.md](CONTRIBUTING.md) for the full agent skills table, contribution workflow, and development setup.
 
 ## Telemetry
 

skills/debug-openshell-cluster/SKILL.md

@@ -13,7 +13,7 @@ Use `openshell` first to identify the active endpoint. Then use the platform too
 
 The target deployment flow is:
 
-1. Operator starts or deploys the gateway with system packages, systemd, Helm, or a development task. The CLI does not start, stop, or destroy gateway services.
+1. Operator starts or deploys the gateway with system packages, systemd, or Helm. The CLI does not start, stop, or destroy gateway services.
 2. Operator configures the compute driver.
 3. Operator provides the CLI and supervisor authentication material required by the deployment mode: edge or OIDC user auth, optional CLI mTLS, and gateway-minted sandbox JWTs.
 4. The CLI registers a reachable gateway endpoint with `openshell gateway add`.
@@ -427,17 +427,15 @@ kubectl -n openshell get endpoints openshell
 For local port-forward testing:
 
 ```bash
-mise run helm:k3s:forward
-openshell gateway list
-openshell status
+kubectl -n openshell port-forward service/openshell 8080:8080
 ```
 
-The forwarding task always exposes the collector on ports `4317` and `18888`.
-It exposes the gateway on port `8090` only when the `openshell` Service exists,
-so collector-only Docker or Podman development remains valid before a Skaffold
-deployment. A successful plaintext `helm:skaffold:run` registers the local
-gateway and selects it as active; the forwarding task does not modify gateway
-metadata.
+Leave the port forward running. In another terminal, register the local endpoint if needed and verify it:
+
+```bash
+openshell gateway add http://127.0.0.1:8080 --local --name local-kubernetes
+openshell status
+```
 
 If the gateway is healthy but sandbox creation fails:
 

skills/generate-sandbox-policy/SKILL.md

@@ -64,7 +64,7 @@ The user provides full API documentation. Accepted formats:
 
 | Format | How to consume |
 |--------|----------------|
-| **URL** | Fetch with `WebFetch` and parse the endpoint list |
+| **URL** | Fetch with the agent's web access and parse the endpoint list |
 | **File path** | Read the file (OpenAPI JSON/YAML, markdown, etc.) |
 | **Pasted text** | Parse inline from the conversation |
 | **OpenAPI/Swagger spec** | Extract `paths` object for all method+path combinations |
@@ -128,9 +128,9 @@ When the user mentions a recognizable API host but hasn't provided docs, and the
 **How to do it:**
 1. Tell the user: "I can look up the REST API docs for [service] to help generate a more precise policy. Want me to do that?"
 2. If the user agrees (or hasn't declined), search for the docs:
-   - Use `WebSearch` with a query like `"[service name] REST API documentation endpoints"` or `"[service name] OpenAPI spec"`
+   - Search the web with a query like `"[service name] REST API documentation endpoints"` or `"[service name] OpenAPI spec"`
    - Look for official documentation URLs in the results
-3. Fetch the docs page with `WebFetch` and extract the endpoint inventory (method + path pairs)
+3. Fetch the documentation page and extract the endpoint inventory (method + path pairs)
 4. Use the discovered endpoints to offer tighter scoping: "I found [N] endpoints in the [service] API. Based on your intent, I can narrow the policy to just [subset]. Want me to do that, or keep the broader preset?"
 
 **When to skip:**

skills/generate-sandbox-policy/examples.md

@@ -138,8 +138,8 @@ Same preset applied to multiple hosts in one policy because the binary set is th
 1. Recognize `api.openai.com` as a well-known service
 2. Ask: "I can look up OpenAI's REST API docs to generate a more precise policy. Want me to do that, or should I use a broad preset?"
 3. User says: "Yeah go ahead"
-4. `WebSearch` for "OpenAI REST API documentation endpoints"
-5. `WebFetch` the docs page, extract endpoints:
+4. Search the web for "OpenAI REST API documentation endpoints"
+5. Fetch the documentation page and extract endpoints:
    - `POST /v1/chat/completions`
    - `POST /v1/embeddings`
    - `GET /v1/models`
@@ -748,7 +748,7 @@ An exact IP is treated as `/32` — only that specific address is permitted.
       - { path: /usr/bin/curl }
 ```
 
-The agent uses `StrReplace` to insert after the last existing policy in the `network_policies` block. All other sections (`filesystem_policy`, `landlock`, `process`) are untouched.
+The agent inserts the new entry after the last existing policy in the `network_policies` block. All other sections (`filesystem_policy`, `landlock`, `process`) are untouched.
 
 ---
 

skills/openshell-cli/SKILL.md

@@ -9,7 +9,7 @@ Guide agents through using the `openshell` CLI for sandbox and platform manageme
 
 ## Overview
 
-The OpenShell CLI (`openshell`) is the primary interface for managing sandboxes, providers, policies, settings, exposed services, inference routes, and gateway registrations. Gateway service lifecycle is handled outside the CLI by packages, systemd, Helm, or development tasks. This skill teaches agents how to orchestrate CLI commands for common and complex workflows.
+The OpenShell CLI (`openshell`) is the primary interface for managing sandboxes, providers, policies, settings, exposed services, inference routes, and gateway registrations. Gateway service lifecycle is handled outside the CLI by packages, systemd, or Helm. This skill teaches agents how to orchestrate CLI commands for common and complex workflows.
 
 **Companion skill**: For creating or modifying sandbox policy YAML content (network rules, L7 inspection, access presets), use the `generate-sandbox-policy` skill. This skill covers the CLI *commands* for the policy lifecycle; `generate-sandbox-policy` covers policy *content authoring*.