docs: add consumer integration skill and organize skills into tiers

.agents/skills/README.md

@@ -0,0 +1,51 @@
+<!--
+SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+SPDX-License-Identifier: Apache-2.0
+-->
+
+# NeMo Fabric Maintainer Skills
+
+This directory is the maintainer skill set for developing NeMo Fabric itself.
+Use these skills for repository work such as:
+
+- Contributing or changing public API surfaces across Rust, CLI, Python, schema,
+  and adapters.
+- Writing and validating Python tests and choosing the right validation matrix.
+- Maintaining CI workflows, packaging, versions, and release surfaces.
+- Reviewing documentation for NVIDIA style and preparing pull requests.
+
+These skills may reference repository internals, build and test commands, and
+contribution workflows.
+
+Consumer-facing integration skills live in the top-level
+[`skills/`](../../skills/README.md) directory so they can be exported separately
+for application developers and integrators. Keep external usage guidance out of
+this set.
+
+## Skills
+
+This table lists the maintainer skills in this set and what each covers.
+
+| Skill | Purpose |
+|---|---|
+| [`contribute-api`](contribute-api/SKILL.md) | Add a public API surface with Rust, CLI, Python, schema, adapter, and documentation parity. |
+| [`small-fix`](small-fix/SKILL.md) | Make a small, reviewable bug fix without widening scope. |
+| [`contribute-docs`](contribute-docs/SKILL.md) | Change documentation or examples in step with public behavior. |
+| [`review-doc-style`](review-doc-style/SKILL.md) | Review documentation and public text for NVIDIA technical-writing style. |
+| [`validate-change`](validate-change/SKILL.md) | Choose and run the right validation matrix for a change. |
+| [`python-tests`](python-tests/SKILL.md) | Write Python tests for Fabric. |
+| [`maintain-ci`](maintain-ci/SKILL.md) | Maintain GitHub Actions workflows with pinned actions and local validation. |
+| [`maintain-packaging`](maintain-packaging/SKILL.md) | Maintain package metadata, native artifacts, lockfiles, and release surfaces. |
+| [`update-project-version`](update-project-version/SKILL.md) | Bump and synchronize release versions across packaging. |
+| [`prepare-pr`](prepare-pr/SKILL.md) | Prepare, open, or edit a pull request with the right scope and review handoff. |
+| [`karpathy-guidelines`](karpathy-guidelines/SKILL.md) | Behavioral coding guidelines; use as a companion to the others. |
+
+## Discovery And Conventions
+
+- Coding agents auto-discover this set from `.agents/skills/`. For Claude Code,
+  `.claude/skills` is a symlink to this directory, exposing the same maintainer
+  set without mixing in consumer skills.
+- **Naming:** maintainer skills use descriptive, task-based names (for example
+  `contribute-api`, `validate-change`).
+- **Frontmatter:** each `SKILL.md` begins with YAML frontmatter containing at
+  least `name` and `description`.

.agents/skills/validate-change/SKILL.md

@@ -37,8 +37,10 @@ surfaces touched by a change.
 - If documentation or examples changed, run `just docs` when practical and
   verify documented commands against the current repository.
 - If code changes alter APIs, commands, paths, packaging behavior, telemetry
-  semantics, or documented best practices, update dependent maintainer skills
-  in the same branch.
+  semantics, or documented best practices, update dependent maintainer skills in
+  the same branch. Because the consumer skills under `skills/` restate SDK guide,
+  Pydantic model, and Rust type details, update them in parity whenever those
+  surfaces change.
 
 ## Start With the Change Shape
 

.claude/skills

@@ -0,0 +1 @@
+../.agents/skills

AGENTS.md

@@ -0,0 +1,57 @@
+<!--
+SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+SPDX-License-Identifier: Apache-2.0
+-->
+
+# AGENTS.md
+
+## Agent Skills
+
+NeMo Fabric ships two tiers of agent skills. Use the tier that matches your task:
+
+- **Consumer skills — `skills/`.** For integrating NeMo Fabric into an external
+  application, service, evaluation harness, or platform through the public Python
+  SDK. They are self-contained and exportable, depending only on supported public
+  SDK contracts and the published documentation, never on repository internals.
+  Start with [`skills/README.md`](skills/README.md).
+- **Maintainer skills — `.agents/skills/`.** For contributing to NeMo Fabric
+  itself: API, documentation, testing, CI, packaging, release, and PR
+  preparation. They may reference repository internals and contribution
+  commands. Start with [`.agents/skills/README.md`](.agents/skills/README.md).
+
+Keep the tiers separate: do not add consumer integration guidance to the
+maintainer set, or repository-internal contribution steps to the consumer set.
+Coding agents that auto-discover skills read the maintainer set from
+`.agents/skills/` (also exposed at `.claude/skills` for Claude Code); the
+consumer set under `skills/` is meant to be exported into a consumer's own
+project.
+
+Key conventions for the two tiers:
+
+- **Discovery wiring:** `.claude/skills` symlinks to `.agents/skills/` (the
+  maintainer set) for Claude Code; consumer skills under `skills/` are copied
+  into a consumer's own project rather than auto-discovered from this repository
+  (see [`skills/README.md`](skills/README.md)).
+- **Portability strategy:** consumer skills link to public GitHub documentation
+  and example URLs rather than a docs-site domain, so they keep working when
+  exported.
+- **Supported consumer surface:** the consumer tier currently ships one skill,
+  `nemo-fabric-integrate`, for typed Python SDK integration.
+
+## Documentation And Contribution Workflow
+
+These workflow notes keep public documentation, examples, and PR preparation aligned
+with repository expectations.
+
+- Update user-facing entry points when public behavior, the `nemo-fabric` package (imported as `nemo_fabric`), examples, or supported bindings change: `README.md`, the Fern docs under `docs/` (navigation in `docs/index.yml`, site config in `fern/docs.yml`), and the adapter/integration READMEs (`adapters/*/README.md`, `python/src/nemo_fabric/integrations/*/README.md`, `examples/README.md`).
+- Keep the Python/Rust binding contract current when the public API changes: `docs/sdk/python.mdx`, the JSON Schema notes in `schemas/SCHEMA.md`, the generated references under `docs/reference/api/`, and the consumer skills under `skills/` (which restate SDK guide, model, and type details and must be kept in parity). Regenerate docs with `just docs` after changing the docs site.
+- Keep release- and packaging-process details in maintainer surfaces (currently the `maintain-packaging` skill at `.agents/skills/maintain-packaging/SKILL.md`). Do not move release-history policy into user-facing docs. There is no `RELEASING.md` or `CHANGELOG.md` yet; add release-history policy there if those files are introduced rather than into user docs.
+- Keep the stable public wrapper `scripts/generate_api_docs.sh` at the `scripts/` root in docs and examples. Reference namespaced helper paths under `scripts/docs/` only when documenting internal maintenance work.
+- Use branch prefixes for your work: `feat/`, `fix/`, `docs/`, `test/`, or `refactor/`.
+- Name branches after the work, never the Linear ticket. Do not embed ticket IDs or slugs in the branch name (e.g. use `feat/notebooks-onboarding`, not `feat/fabric-70-notebooks-onboarding`). This rule has historically been overlooked, so double-check the branch name before pushing or opening a PR.
+- Use Conventional Commit PR titles (`<type>: <summary>`) as required by `.coderabbit.yaml` and the `prepare-pr` skill; reserve `fix` for actual product bugs, not CI, docs, or chores.
+- Use signed-off commits for PR work: `git commit -s`.
+- When creating a pull request from the current branch, target the upstream repository rather than a fork.
+- Before creating, opening, publishing, or editing a pull request, read `.github/pull_request_template.md` and use it as the PR body skeleton (or `gh pr create --template .github/pull_request_template.md`). Preserve its visible headings (`Overview`, `Where should the reviewer start?`, `Related Issues`) and its contribution checkboxes; fill the sections instead of replacing them with a generic summary.
+- If repo-local PR guidance such as the `prepare-pr` skill conflicts with generic GitHub connector or plugin guidance, follow the repo-local PR guidance for PR body format and review handoff details.
+- PR descriptions should include what changed, why, how it was tested, and any breaking changes within the repository template format.

CLAUDE.md

@@ -0,0 +1 @@
+AGENTS.md

README.md

@@ -186,6 +186,8 @@ the [Python SDK guide](docs/sdk/python.mdx). Exact signatures are in the
 
 - [Python SDK guide](docs/sdk/python.mdx): typed configuration, planning,
   diagnostics, requests, multi-turn runtimes, parallelism, results, and errors.
+- [Consumer integration skills](skills/README.md): repository-local coding-agent
+  skills for integrating Fabric into an application through the Python SDK.
 - [Getting Started overview](docs/getting-started/overview.mdx): interface
   selection and the end-to-end Fabric workflow.
 - [Harbor examples](examples/harbor/README.md): validate the integration with a

TODO.md

@@ -26,3 +26,19 @@ cleanup validation.
 - **Cleanup:** Replace the pinned source-install instructions with the released
   CLI installation, run the Codex Relay end-to-end test, update both affected
   documentation files, and remove this entry.
+
+## NeMo Fabric PyPI Availability
+
+- **Status:** Waiting for a published release
+- **Added:** July 16, 2026
+- **Affected documentation:** `skills/nemo-fabric-integrate/SKILL.md` (install
+  section)
+- **Reason:** `nemo-fabric` is not yet published on PyPI, so the consumer
+  integration skill installs from a source checkout (`just build-all`) or locally
+  built wheels (`just wheels` plus `uv pip install --find-links`).
+- **Upstream resolution:** NeMo Fabric's own first PyPI release (internal
+  milestone; no external dependency).
+- **Removal condition:** `nemo-fabric` and its adapter extras are published on
+  PyPI in a version the skill can target.
+- **Cleanup:** Replace the source and wheel install steps in the skill with the
+  published `pip install "nemo-fabric[...]"` instructions and remove this entry.

skills/README.md

@@ -0,0 +1,63 @@
+<!--
+SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+SPDX-License-Identifier: Apache-2.0
+-->
+
+# NeMo Fabric Consumer Skills
+
+These are user-facing skills for integrating NeMo Fabric into your own
+application, service, evaluation harness, or platform through the public Python
+SDK. They are intended for external application developers and integrators — not
+for developing NeMo Fabric itself.
+
+If you are contributing to NeMo Fabric — changing core, bindings, adapters,
+documentation, CI, or packaging — use the
+[maintainer skills](../.agents/skills/README.md) in `.agents/skills/` instead.
+
+## Portability
+
+Consumer skills are self-contained and exportable. Each skill depends only on
+supported public interfaces (the `nemo_fabric` Python package) and public
+documentation URLs, never on repository-internal paths.
+
+- Cross-links point to the published documentation and public example URLs on
+  GitHub, not to files inside this checkout. Skill-specific material is bundled
+  under each skill's own `references/`.
+- Skills do not depend on repository internals — their links are absolute or
+  bundled, so they resolve when copied out. A skill may still mention Fabric
+  build commands (`just …`, needed while Fabric is unpublished) or the maintainer
+  tier as guidance for contributors.
+
+## Using A Consumer Skill In Your Project
+
+Copy the skill directory — for example `nemo-fabric-integrate/`, including its
+`references/` — into the place your coding agent discovers skills **in your own
+project**. Do not rely on this repository's maintainer wiring (its `.claude/skills`
+symlink or `.agents/skills/` set); those serve Fabric's own contributors.
+
+- **Claude Code:** place it at `.claude/skills/nemo-fabric-integrate/` in your
+  project, or `~/.claude/skills/nemo-fabric-integrate/` to use it across
+  projects. Claude Code discovers `SKILL.md` files under those directories.
+- **OpenAI Codex:** place it at
+  `<your-project>/.agents/skills/nemo-fabric-integrate/` in your project, or
+  `$CODEX_HOME/skills/nemo-fabric-integrate/` to use it across projects.
+- **Other agents:** each skill is a portable `SKILL.md` bundle — put it wherever
+  your agent loads skills, or reference its `SKILL.md` directly from your agent
+  instructions. Confirm discovery with a prompt that should trigger the skill.
+
+## Start Here
+
+| Skill | Use it when |
+|---|---|
+| [`nemo-fabric-integrate`](nemo-fabric-integrate/SKILL.md) | You are adding NeMo Fabric to a consumer application, service, evaluation harness, or platform through the typed Python SDK — building an in-memory `FabricConfig`, choosing one-shot versus stateful-runtime execution, validating with `plan`/`doctor`, and consuming normalized results. |
+
+## Conventions
+
+- **Naming:** consumer skills are prefixed with the product name,
+  `nemo-fabric-<topic>`.
+- **Frontmatter:** each `SKILL.md` begins with YAML frontmatter containing at
+  least `name` and `description`. `SKILL.md` files do not carry an SPDX header;
+  every other file, including this README and bundled `references/`, does.
+- **Self-containment:** keep a skill usable outside this repository. Link to
+  public documentation and example URLs, and bundle any skill-specific reference
+  material under the skill's own `references/`.