Skip to content

docs(skills): add messaging channel onboarding guide - #5501

Merged
cv merged 3 commits into
mainfrom
docs/messaging-onboard-skill
Jun 18, 2026
Merged

docs(skills): add messaging channel onboarding guide#5501
cv merged 3 commits into
mainfrom
docs/messaging-onboard-skill

Conversation

@sandl99

@sandl99 sandl99 commented Jun 16, 2026

Copy link
Copy Markdown
Collaborator

Summary

Adds a contributor skill for onboarding new messaging channels through NemoClaw's manifest-first messaging architecture. Adds a package-specific messaging AGENTS guide and links it from the repo instructions so future agents know where to start.

Related Issue

None.

Changes

  • Added nemoclaw-contributor-onboard-messaging-channel with progressive intake, upstream source analysis, implementation workflow, quality gates, and focused verification guidance.
  • Added src/lib/messaging/AGENTS.md to document messaging architecture, package boundaries, channel extension points, and testing expectations.
  • Updated the skills guide catalog/counts and root AGENTS.md package-guide pointer.

Type of Change

  • Code change (feature, bug fix, or refactor)
  • Code change with doc updates
  • Doc only (prose changes, no code sample modifications)
  • Doc only (includes code sample changes)

Verification

  • Git hooks passed during commit and push, or npx prek run --from-ref main --to-ref HEAD passes
  • Targeted tests pass for changed behavior
  • Full npm test passes (broad runtime changes only)
  • Tests added or updated for new or changed behavior
  • No secrets, API keys, or credentials committed
  • Docs updated for user-facing behavior changes
  • npm run docs builds without warnings (doc changes only)
  • Doc pages follow the style guide (doc changes only)
  • New doc pages include SPDX header and frontmatter (new pages only)

Verification details: npx prek run --files AGENTS.md src/lib/messaging/AGENTS.md .agents/skills/nemoclaw-contributor-onboard-messaging-channel/SKILL.md .agents/skills/nemoclaw-skills-guide/SKILL.md passed. Commit hooks and push hooks passed, including TypeScript (CLI) and Test (skills YAML). npm run docs passed, but Fern reported 2 warnings, so the no-warnings checkbox is intentionally left unchecked.


Signed-off-by: San Dang sdang@nvidia.com

Summary by CodeRabbit

  • Documentation
    • Added a comprehensive onboarding guide for messaging-channel contributions, including a progressive intake flow, manifest-first workflow, quality gates, and verification/testing guidance.
    • Updated the Skills Guide with a new contributor skill entry and adjusted contributor/maintainer included-skill counts.
    • Added messaging architecture documentation covering end-to-end plan flow, key invariants, where changes should be made, and related testing guidance.
    • Added cross-references to package-specific messaging guides in the main documentation.

@sandl99 sandl99 self-assigned this Jun 16, 2026
@coderabbitai

coderabbitai Bot commented Jun 16, 2026

Copy link
Copy Markdown
Contributor

Review Change Stack

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info
⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: ba5c76cb-002b-4ff8-b0f0-7ae461cb0eb2

📥 Commits

Reviewing files that changed from the base of the PR and between cd4c691 and dea5156.

📒 Files selected for processing (2)
  • .agents/skills/nemoclaw-contributor-onboard-messaging-channel/SKILL.md
  • .agents/skills/nemoclaw-skills-guide/SKILL.md
💤 Files with no reviewable changes (2)
  • .agents/skills/nemoclaw-contributor-onboard-messaging-channel/SKILL.md
  • .agents/skills/nemoclaw-skills-guide/SKILL.md

📝 Walkthrough

Walkthrough

Adds src/lib/messaging/AGENTS.md documenting the manifest-first messaging architecture, data flow, invariants, and testing guidance. Links it from the root AGENTS.md. Introduces a new nemoclaw-contributor-onboard-messaging-channel skill with a full intake and implementation workflow, and registers it in the skills guide with updated cumulative role counts. Updates markdownlint to support SPDX headers in markdown files.

Changes

Messaging Architecture Docs and Contributor Skill

Layer / File(s) Summary
Messaging architecture and root linkage
src/lib/messaging/AGENTS.md, AGENTS.md
Introduces src/lib/messaging/AGENTS.md with the manifest-first data flow (manifests → SandboxMessagingPlan → serialization/build/applier/persistence), core invariants, change-location conventions, testing commands, and doc placement rules. Adds a "Package-specific guides" bullet in the root AGENTS.md pointing to this file.
Onboarding skill, skill registration, and frontmatter support
.agents/skills/nemoclaw-contributor-onboard-messaging-channel/SKILL.md, .agents/skills/nemoclaw-skills-guide/SKILL.md, .markdownlint-cli2.yaml
Adds the complete SKILL.md for nemoclaw-contributor-onboard-messaging-channel covering progressive intake, source-analysis checklist, manifest/template-resolver/hooks/policy/agent-manifest workflow, quality gates, and verification commands. Updates the skills guide to register the new skill in the nemoclaw-contributor-* bucket, adds its catalog entry, and updates cumulative role skill counts for Contributor and Maintainer. Updates .markdownlint-cli2.yaml frontmatter regex to support SPDX-prefixed YAML headers preceding the markdown body.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~5 minutes

Possibly related PRs

  • NVIDIA/NemoClaw#5368: Both PRs are documentation-only changes that update AGENTS.md-style guidance for documentation and contributor workflows, making the new src/lib/messaging/AGENTS.md part of the same doc-guidance pattern.

Suggested labels

area: skills, area: docs, area: messaging

Suggested reviewers

  • cv

Poem

🐰 A channel awaits, a manifest to write,
Hop through the intake, one question at a time.
The architecture flows from manifests bright,
To sandbox plans built with reason and rhyme.
New skills in the guide, the counts all aligned —
A bunny who documents leaves nothing behind! ✨

🚥 Pre-merge checks | ✅ 5
✅ Passed checks (5 passed)
Check name Status Explanation
Description Check ✅ Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Title check ✅ Passed The title 'docs(skills): add messaging channel onboarding guide' directly reflects the primary change in the PR - introducing a new contributor skill guide for onboarding messaging channels. It is concise, specific, and accurately summarizes the main addition.
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.

✏️ Tip: You can configure your own custom pre-merge checks in the settings.

✨ Finishing Touches
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch docs/messaging-onboard-skill

Warning

Review ran into problems

🔥 Problems

Stopped waiting for pipeline failures after 30000ms. One of your pipelines takes longer than our 30000ms fetch window to run, so review may not consider pipeline-failure results for inline comments if any failures occurred after the fetch window. Increase the timeout if you want to wait longer or run a @coderabbit review after the pipeline has finished.


Comment @coderabbitai help to get the list of available commands and usage tips.

@github-actions

github-actions Bot commented Jun 16, 2026

Copy link
Copy Markdown
Contributor

E2E Advisor Recommendation

Required E2E: None
Optional E2E: None

Workflow run

Full advisor summary

E2E Recommendation Advisor

Base: origin/main
Head: HEAD
Confidence: high

Required E2E

  • None. No E2E is recommended. The PR changes only contributor/agent guidance Markdown and markdownlint configuration. It does not modify runtime TypeScript/JavaScript, blueprint/network-policy assets, installer/onboarding code, sandbox lifecycle code, credential handling, inference routing, deployment logic, or real assistant user flows.

Optional E2E

  • None.

New E2E recommendations

  • None.

@github-actions

github-actions Bot commented Jun 16, 2026

Copy link
Copy Markdown
Contributor

Vitest E2E Scenario Recommendation

Required Vitest E2E scenarios: None
Optional Vitest E2E scenarios: None

Workflow run

Full Vitest E2E advisor summary

Vitest E2E Scenario Advisor

Base: origin/main
Head: HEAD
Confidence: high

Required Vitest E2E scenarios

  • None. Changes are limited to agent guidance Markdown and markdownlint configuration; they do not affect the Vitest E2E scenario workflow, registry, runtime support, live tests, fixtures, or scenario behavior.

Optional Vitest E2E scenarios

  • None.

Relevant changed files

  • None.

@github-actions

github-actions Bot commented Jun 16, 2026

Copy link
Copy Markdown
Contributor

PR Review Advisor

Findings: 0 needs attention, 0 worth checking, 0 nice ideas
Since last review: 0 prior items resolved, 0 still apply, 0 new items found

Consider writing more tests for
  • **Acceptance clause:** New doc pages include SPDX header and frontmatter (new pages only) — add test evidence or identify existing coverage. `src/lib/messaging/AGENTS.md` includes SPDX comments. The new skill includes valid YAML frontmatter at the start, matching the skill parser requirement, but does not include SPDX comments; the PR checklist leaves this item unchecked and existing skill files show mixed SPDX placement.

Workflow run details

This is an automated advisory review. A human maintainer must make the final merge decision.

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 1

🧹 Nitpick comments (1)
.agents/skills/nemoclaw-contributor-onboard-messaging-channel/SKILL.md (1)

8-8: 💤 Low value

Hyphenate "end-to-end" in adjective position.

Line 8 uses "end to end" where it modifies "messaging channel" as a compound adjective; this should be hyphenated as "end-to-end".

✏️ Proposed fix
-Use this skill to add a messaging channel end to end without leaking channel-specific logic into core NemoClaw code.
+Use this skill to add a messaging channel end-to-end without leaking channel-specific logic into core NemoClaw code.
🤖 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 @.agents/skills/nemoclaw-contributor-onboard-messaging-channel/SKILL.md at
line 8, In the SKILL.md file on line 8, the phrase "end to end" is used as a
compound adjective modifying "messaging channel" and should be hyphenated.
Change "end to end" to "end-to-end" in the sentence to follow standard English
grammar rules for compound adjectives.

Source: Linters/SAST tools

🤖 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 `@src/lib/messaging/AGENTS.md`:
- Around line 1-2: Two Markdown skill files are missing SPDX license headers
that must appear at the very beginning of the file before any other content. In
`.agents/skills/nemoclaw-contributor-onboard-messaging-channel/SKILL.md` (lines
1-4), add the two SPDX header comment lines before the opening `---` of the YAML
frontmatter. Similarly, in `.agents/skills/nemoclaw-skills-guide/SKILL.md`
(lines 1-5), add the same two SPDX header comment lines at the very top before
the YAML frontmatter begins. The header to add is the two HTML comment lines for
SPDX-FileCopyrightText and SPDX-License-Identifier as shown in the anchor file
`src/lib/messaging/AGENTS.md` at lines 1-2, which already has the correct
format.

---

Nitpick comments:
In @.agents/skills/nemoclaw-contributor-onboard-messaging-channel/SKILL.md:
- Line 8: In the SKILL.md file on line 8, the phrase "end to end" is used as a
compound adjective modifying "messaging channel" and should be hyphenated.
Change "end to end" to "end-to-end" in the sentence to follow standard English
grammar rules for compound adjectives.
🪄 Autofix (Beta)

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: 79856411-218d-434a-abc0-edf5ea2f0463

📥 Commits

Reviewing files that changed from the base of the PR and between 6c0fb04 and 79dcca1.

📒 Files selected for processing (4)
  • .agents/skills/nemoclaw-contributor-onboard-messaging-channel/SKILL.md
  • .agents/skills/nemoclaw-skills-guide/SKILL.md
  • AGENTS.md
  • src/lib/messaging/AGENTS.md

Comment thread src/lib/messaging/AGENTS.md
Signed-off-by: San Dang <sdang@nvidia.com>
@github-code-quality

github-code-quality Bot commented Jun 16, 2026

Copy link
Copy Markdown
Contributor

Code Coverage Overview

Languages: TypeScript

TypeScript / code-coverage/plugin

The overall coverage in the docs/messaging-onboa... branch is 96%. Coverage data for the main branch is not yet available.

Show a code coverage summary of the most covered files.
File main docs/messaging-onboa... dea5156 +/-
nemoclaw/src/se...cret-scanner.ts 100%
nemoclaw/src/commands/slash.ts 100%
nemoclaw/src/li...bprocess-env.ts 100%
nemoclaw/src/bl...eprint/state.ts 98%
nemoclaw/src/onboard/config.ts 98%
nemoclaw/src/bl...int/snapshot.ts 97%
nemoclaw/src/bl...print/runner.ts 95%
nemoclaw/src/co...ration-state.ts 94%
nemoclaw/src/bl...ate-networks.ts 94%
nemoclaw/src/index.ts 94%

TypeScript / code-coverage/cli

The overall coverage in the docs/messaging-onboa... branch is 46%. Coverage data for the main branch is not yet available.

Show a code coverage summary of the most covered files.
File main docs/messaging-onboa... dea5156 +/-
src/lib/state/o...oard-session.ts 90%
src/lib/inference/local.ts 76%
src/lib/sandbox/config.ts 72%
src/lib/actions...dbox/rebuild.ts 67%
src/lib/onboard/preflight.ts 64%
src/lib/actions...licy-channel.ts 56%
src/lib/state/sandbox.ts 55%
src/lib/policy/index.ts 49%
src/lib/onboard...er-gpu-patch.ts 44%
src/lib/onboard.ts 18%

Updated June 16, 2026 10:01 UTC
Code Coverage is in Public Preview. Learn more and provide us with your feedback.

@sandl99 sandl99 added the area: messaging Messaging channels, bridges, manifests, or channel lifecycle label Jun 16, 2026
@sandl99
sandl99 requested a review from cv June 16, 2026 08:39
@cv
cv merged commit 9cb773e into main Jun 18, 2026
46 checks passed
@cv
cv deleted the docs/messaging-onboard-skill branch June 18, 2026 22:05
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

area: messaging Messaging channels, bridges, manifests, or channel lifecycle

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants