[Pouyanpi]

Description

Adds three agent skills under .agents/skills/, plus subtree contributor
docs, for the workflow around nemoguardrails/library/:

• add-library-rail: step-by-step contribution guide for a new rail.
  Manifest, actions returning RailOutcome, config schema, both Colang
  dialects, HTTP rules for vendor backends, optional dependencies, the three
  test layers, docs and examples, and a matrix for modifying an existing rail.
• review-library-rail: the reviewer counterpart. Runs the mechanical
  gates first, then fourteen judgment dimensions the gates cannot check
  (privacy honesty, retry semantics, fail-closed behavior, dialect coverage,
  cassette provenance, conformance drift, client ownership), then a security
  pass.
• recorded-tests: decides whether a change needs a recorded/VCR test and
  whether a test belongs in tests/recorded/ or tests/.

Also included: nemoguardrails/library/AGENTS.md as an always-loaded tripwire
for the rail subtree, and additions to tests/recorded/AGENTS.md and
tests/recorded/README.md.

Docs only. No runtime, public API, or test behavior changes.

Design notes worth a reviewer's attention

Skills are checklists, not principles. These enumerate concrete checks with
file paths and commands rather than stating goals. That is deliberate: in
evaluation, agents complied with what a skill named and missed what it omitted,
close to one for one. Where a gap is found, the fix is a named rule, not better
prose.

Anything mechanically checkable is a test, not skill text. The skills own
placement decisions and judgment calls; manifest completeness, the HTTP
transport boundary, flow-file validity, and cross-artifact conformance stay in
their existing gates. The review skill's first step is to run those gates and
then spend attention only on what they cannot prove.

Areas that need careful review

• Factual accuracy against develop. Every path, symbol, test name, marker,
  fixture, and CLI flag in these files is a checkable assertion, and an earlier
  draft of this branch described a state that never shipped. The dependency
  section, the verification loops, and the retry semantics paragraph were all
  rewritten to match develop specifically. Please spot-check anything that
  looks familiar from the manifest stack.
• add-library-rail Step 5 (packaging). The rule distinguishes the user
  install path from the test_integration dependency group. That distinction is
  load-bearing and easy to get wrong in either direction.
• The exemplars the skills tell contributors to copy. Two carry explicit
  do-not-copy caveats (clavata's test coverage, content_safety's refusal
  prose). If you disagree with either caveat, the skill text is the place to
  argue it.

Verification

Docs-only change, so CI is necessary but not sufficient. Beyond CI:

• uv run --locked pre-commit run --files <changed files>: passes.
• make test: 6277 passed, 178 skipped. Unaffected by this branch, run to
  confirm no incidental breakage.
• Multi-agent factual review of the skill text against the repository.
  Eight reviewers covering reference integrity, behavioral claims, exemplar
  validity, cross-skill consistency, command correctness, and public-surface
  coverage. Every finding required a file:line citation or a failing command.
  This produced the corrections in the middle of the commit range.
• Armed evaluation on a fresh vendor task. Three independent builder agents
  implemented a fictional vendor rail from these skills, in isolated worktrees,
  graded blind against a pre-registered rubric. All three passed the full suite
  (6346 / 6340 / 6349 passed) and resisted all twelve planted traps. The three
  convergent gaps they surfaced are fixed in the last four commits.

Checks not run, with residual risk:

• The evaluation measured the skills armed only. It shows they are usable and
  which traps they prevent; it does not measure marginal value over no skill,
  which would need a control arm.

AI Assistance

• No AI tools were used.
• AI tools were used; a human reviewed and can explain every change (tool: Claude Code).

Checklist

• I've read the CONTRIBUTING guidelines.
• This PR links to a triaged issue assigned to me.
• My PR title follows the project commit convention.
• I've updated the documentation if applicable.
• I've added tests if applicable. (Docs-only; no code paths changed.)
• I've noted any verification beyond CI and any checks I couldn't run.
• I did not update generated changelog files manually.
• I addressed all CodeRabbit, Greptile, and other review comments, or replied with why no change is needed.
• @mentions of the person or team responsible for reviewing proposed changes.

Summary by CodeRabbit

• Documentation
  • Added guidance for implementing, reviewing, and maintaining library rails.
  • Documented requirements for manifests, configuration, security, testing, telemetry, error handling, and validation.
  • Clarified when provider interactions require recorded tests versus deterministic unit tests.
  • Updated recorded-test guidance covering placement, markers, cassette workflows, snapshots, and replay behavior.

[greptile-apps]

Confidence Score: 5/5

[Low impact] The PR appears safe to merge; no actionable issue remains from this review.

Summary

Adds three agent skills for contributing rails, reviewing rails, and placing recorded tests.

• Rail contributors get a step-by-step guide for building and updating library rails.
• Rail reviewers get a checklist that pairs repository gates with focused judgment checks.
• Test authors get clearer rules for recorded-test placement and snapshot setup.
• The RailOutcome docs explain how consumers can use supported presentation hints.

_{Reviews (9) · Last reviewed commit: "docs(skills): point HTTP guidance to the..." · Reviewed by Greptile}

[coderabbitai]

📝 Walkthrough

Walkthrough

Added skills and subtree guidance for implementing, testing, and reviewing library rails. The changes also clarify recorded-test placement, cassette workflows, and inline snapshot behavior.

Changes

Library rail guidance

Layer / File(s)	Summary
Rail contribution workflow .agents/skills/add-library-rail/SKILL.md, nemoguardrails/library/AGENTS.md	Documents rail archetypes, package structure, manifests, actions, flows, configuration, dependencies, testing, synchronization, and verification commands.
Recorded test requirements .agents/skills/recorded-tests/SKILL.md, tests/recorded/AGENTS.md, tests/recorded/README.md	Defines when recorded tests are required, how to place and mark them, how to manage cassettes, and how inline snapshots behave.
Rail review procedure .agents/skills/review-library-rail/SKILL.md	Defines review scope, mechanical gates, completeness checks, security validation, review dimensions, evidence requirements, and verdict format.

Estimated code review effort: 2 (Simple) | ~10 minutes

Possibly related PRs

• NVIDIA-NeMo/Guardrails#2189: Documents implementation and review requirements for library rails.

🚥 Pre-merge checks | ✅ 6

✅ Passed checks (6 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly summarizes the documentation changes for rail contribution, review, and recorded-test skills.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Test Results For Major Changes	✅ Passed	The PR is documentation-only (1,119 Markdown additions; no runtime or test implementation changes), and its description documents pre-commit plus make test results: 6,277 passed and 178 skipped.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch pouyanpi/rail-library-stack-16-skills

---

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 3

🧹 Nitpick comments (1)

tests/recorded/AGENTS.md (1)

5-9: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Keep placement decisions in the recorded-tests skill.

This section repeats the placement rule, while lines 18-20 say the skill owns placement decisions. Keep this file as a pointer and keep the detailed criterion in .agents/skills/recorded-tests/SKILL.md so the copies do not drift.

Based on learnings: use tests/recorded/README.md for mechanics and .agents/skills/recorded-tests/SKILL.md for placement decisions; do not duplicate placement guidance in AGENTS.md.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@tests/recorded/AGENTS.md` around lines 5 - 9, Remove the duplicated
recorded-test placement rule from tests/recorded/AGENTS.md, leaving it as a
pointer to tests/recorded/README.md for mechanics and
.agents/skills/recorded-tests/SKILL.md for placement decisions. Preserve the
skill file as the single source of truth for the real-provider-request
criterion.

Source: Learnings

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In @.agents/skills/add-library-rail/SKILL.md:
- Around line 9-13: Narrow the introduction’s enforcement claim to say that
structural contracts are checked by conformance gates, while privacy, retry,
fail-closed, telemetry, documentation, cassette provenance, and other behavior
require focused tests or manual review. Update the workflow wording to preserve
the distinction between generic gates and rail-specific behavioral or recorded
end-to-end verification.

In @.agents/skills/review-library-rail/SKILL.md:
- Around line 31-40: Update the “Step 1: Run the mechanical gates” procedure to
run the repository’s locked pre-commit command before any make test or git diff
commands. Preserve the existing mechanical gate commands and ordering after
pre-commit, and use the project’s established locked pre-commit invocation
rather than inventing a new one.

In `@tests/recorded/AGENTS.md`:
- Around line 10-13: Align the marker guidance across
tests/recorded/AGENTS.md:10-13, .agents/skills/recorded-tests/SKILL.md:136-147,
and .agents/skills/add-library-rail/SKILL.md:455-459. Document the actual
behavior of tests/recorded/conftest.py, including that marker enforcement is not
performed at setup, and define one consistent policy for the rare
pure-runtime/public-API exception while accounting for existing non-VCR modules.
Update all three files consistently; no code change to conftest.py is requested.

---

Nitpick comments:
In `@tests/recorded/AGENTS.md`:
- Around line 5-9: Remove the duplicated recorded-test placement rule from
tests/recorded/AGENTS.md, leaving it as a pointer to tests/recorded/README.md
for mechanics and .agents/skills/recorded-tests/SKILL.md for placement
decisions. Preserve the skill file as the single source of truth for the
real-provider-request criterion.

🪄 Autofix

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: a754a4ad-d320-42b6-8762-4a6cdaf12f22

📥 Commits

Reviewing files that changed from the base of the PR and between d7b264f and 8fe2508.

📒 Files selected for processing (6)

• .agents/skills/add-library-rail/SKILL.md
• .agents/skills/recorded-tests/SKILL.md
• .agents/skills/review-library-rail/SKILL.md
• nemoguardrails/library/AGENTS.md
• tests/recorded/AGENTS.md
• tests/recorded/README.md

[tgasser-nv]

This needs updating to match the latest code, left individual comments. Some other comments:

• uv build will include nemoguardrails/library/AGENTS.md in the package. Recommend adding this to the pyproject.toml source-exclude list.

[github-actions]

Staged Fern docs preview: https://nvidia-preview-pr-2223.docs.buildwithfern.com/nemo/guardrails

[Pouyanpi]

uv build will include nemoguardrails/library/AGENTS.md in the package.

fixed in d634505, added the library AGENTS.md to source-exclude and verified it is absent from both the wheel and source distribution.

[Pouyanpi]

@tgasser-nv I've addressed your comments 👍

[tgasser-nv]

Looks good! Just a few nits to clean up prior to merge.