AGENTS.md

Agent Skills

NeMo Fabric ships two tiers of agent skills. Use the tier that matches your task:

• Integration skills — skills/. For integrating NeMo Fabric into an external application through the public Python SDK or building a third-party adapter through the published adapter contract. They are self-contained and exportable, depending only on supported public contracts and documentation, never on repository internals. Start with 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.

Keep the tiers separate: do not add external integration guidance to the maintainer set, or repository-internal contribution steps to the integration set. Coding agents that auto-discover skills read the maintainer set from .agents/skills/ (also exposed at .claude/skills for Claude Code); the integration set under skills/ is meant to be exported into another project.

Key conventions for the two tiers:

• Discovery wiring: .claude/skills symlinks to .agents/skills/ (the maintainer set) for Claude Code; integration skills under skills/ are copied into another project rather than auto-discovered from this repository (see skills/README.md).
• Portability strategy: integration skills link to public GitHub documentation and example URLs rather than a docs-site domain, so they keep working when exported.
• Supported integration surface: the integration tier ships skills/nemo-fabric-integrate for typed Python SDK integration and skills/nemo-fabric-build-adapter for third-party adapter authoring. Future integration skills also live directly under skills/ so they can be validated and published independently; repository-internal adapter maintenance stays in .agents/skills/.

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, adapters/*/README.md, adapters/*/*/README.md, sdk/python/nemo-fabric-runtime/src/nemo_fabric/integrations/*/README.md, examples/README.md).
• Keep public bindings current when the API changes: docs/sdk/python.mdx for the Python SDK; adapter-contract/python/ and adapter-contract/typescript/ for the southbound adapter contract; the JSON Schema notes in schemas/SCHEMA.md; the generated references under docs/reference/api/; and the integration skills under skills/ (which restate public contracts and must be kept in parity). Regenerate docs with just docs after changing the docs site.
• Keep release policy and the end-to-end maintainer workflow in RELEASING.md; keep packaging implementation guidance in .agents/skills/maintain-packaging/SKILL.md. Do not move release-history policy into user-facing docs or add a duplicate CHANGELOG.md.
• 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: chore/, 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.