Repository navigation
[FEA]: Introduce shared Claude and Codex skills and streamline repository agent guidance #3192
Description
Motivation
The discussion following PR #3151 identified a need for a repository-level test-authoring skill. That PR consolidated multiprocessing test helpers and added a small amount of helper-reuse guidance to cuda_core/tests/AGENTS.md.
A broader review of the repository's ten AGENTS.md files suggests a useful follow-up: establish shared skills for Claude Code and Codex, and organize the existing guidance so that repository constraints remain readily available while detailed procedures load when relevant.
The largest opportunities are the root instructions (367 lines), core package instructions (342 lines), and core test instructions (272 lines). Several other files are already concise and serve their current purpose well. This proposal concentrates the refactoring effort where it provides meaningful value.
The intended benefits are easier maintenance, clearer discovery of established workflows, consistent guidance across both agents, and less unrelated material in an agent's working context. The skill names, boundaries, and initial implementation scope below are proposed for team discussion.
Proposed division of responsibilities
| Location | Responsibility |
|---|---|
AGENTS.md |
Repository or package context, architectural boundaries, source-of-truth locations, essential constraints, and short pointers to relevant skills. |
| Skills | Task-specific procedures, checklists, helper selection, and routing to the references needed for a particular task. |
| Contributor documentation | Detailed design rationale, build documentation, and release instructions that remain useful to human contributors as well as agents. |
Essential safety requirements should remain explicit in the applicable AGENTS.md. Moving explanatory material into a skill should preserve the visibility of rules concerning CUDA contexts, resource ownership, pool sizing, generated files, and failure handling.
Skills should reference existing documentation and automation where they already provide the maintained implementation or explanation. Core API design guidance should retain its current advisory status.
The root file also contains substantial generic coding, planning, frontend, response-format, and tool-specific guidance. Its refactoring should focus on repository-specific information, with personal agent preferences maintained in user configuration.
Scope by directory
The assessment is based on cuda-python commit afa6249 and its pinned CCCL submodule.
| Instruction file | Proposed treatment |
|---|---|
AGENTS.md |
Retain the package map, repository-specific policies, concise test-provenance requirements, and skill routing. Reduce generic and tool-specific prompt material. |
cuda_core/AGENTS.md |
Retain architecture, version-coupling constraints, and concise runtime safety invariants. Extract detailed runtime/API procedures and dependency-update workflows, referencing existing design and release documentation. |
cuda_core/tests/AGENTS.md |
Retain brief requirements for CUDA contexts, cleanup, pool caps, helper reuse, and correct failure reporting. Move substantial recipes and explanations into test-authoring references. |
cuda_python/AGENTS.md |
Keep the metapackage's role and release coupling concise. Route procedures to existing release and documentation guidance. |
cuda_pathfinder/AGENTS.md |
Retain descriptor, cache, handle, and error contracts. Move detailed isolation, cache-aware testing, and validation recipes into package references. |
cuda_bindings_13/AGENTS.md |
Retain generated-source restrictions, architectural boundaries, and platform expectations. Extract substantial build and test procedures. |
benchmarks/cuda_bindings/AGENTS.md |
Keep its compact scope and README routing. |
benchmarks/cuda_core/AGENTS.md |
Keep its compact scope, shared-runner constraints, and benchmark-ID conventions. |
cuda_core/third_party/cccl/AGENTS.md |
Treat as upstream-owned submodule guidance. Consider any changes separately in NVIDIA/cccl. |
cuda_core/third_party/cccl/python/cuda_cccl/benchmarks/compute/AGENTS.md |
Keep its existing compact scope; changes belong upstream with CCCL. |
Candidate skills
| Proposed skill | Responsibilities |
|---|---|
cuda-python-test-authoring |
Shared test conventions and helper discovery, with package references for core resource/process handling, Pathfinder loader isolation and caching, and bindings conventions. |
cuda-python-validation |
Select and run appropriate builds, Python/Cython tests, samples, documentation checks, or benchmarks through maintained repository entrypoints. |
cuda-core-development |
Support runtime and public API changes and reviews, loading concurrency, ownership, failure-handling, and API references as relevant. |
cuda-python-versioning — possible later addition |
Guide toolkit and bindings-floor updates, tag-derived versioning, and release coupling through existing release checklists. |
The first test-authoring reference would cover the accumulated core test guidance: fixture and helper placement, capped/default/managed pools, cleanup at test boundaries, multiprocessing lifetimes and descriptor baselines, optional dependencies, capability probes, and partial-setup cleanup.
Runtime guidance should use _cpp/rt/DESIGN.md as an existing design reference. Release workflows should remain accessible through documents such as .github/RELEASE-core.md. These references can be loaded selectively rather than copied into every skill.
Shared Claude Code and Codex discovery
The repository already has a skills foundation in .agents/skills/create-cuda-python-pull-request. Extend that location with one canonical set of skill directories, exposed to Claude through relative symlinks under .claude/skills.
For example:
.agents/skills/
create-cuda-python-pull-request/ # existing
cuda-python-test-authoring/
SKILL.md
references/
core.md
pathfinder.md
bindings.md
.claude/skills/
cuda-python-test-authoring -> ../../.agents/skills/cuda-python-test-authoring
Use portable SKILL.md metadata, principally name and description, and tool-neutral Markdown instructions. Optional agent-specific metadata can remain separate. Supporting references should be added when they have a concrete use.
Codex documents discovery through .agents/skills and support for symlinked skill folders. Claude documents discovery through .claude/skills and symlinked skill folders. CCCL already provides a local precedent for sharing skills through a Claude discovery symlink. See the official OpenAI skill documentation, Claude skill documentation, and CCCL skill routing.
Instruction-file discovery also needs consistent coverage. The root and package CLAUDE.md files currently bridge to sibling AGENTS.md files; the core tests and first-party benchmark directories do not have equivalent bridges. Preserve and complete that coverage. Claude's documented @AGENTS.md import is an alternative to instruction-file symlinks, particularly for Windows checkouts. See Claude instruction discovery.
Suggested first increment
- Establish the shared skill layout and consistent instruction-file discovery for both agents.
- Simplify the root guidance while preserving repository policies and concise routing.
- Introduce
cuda-python-test-authoringand extract the substantial test-authoring procedures, starting with core. - Verify discovery and behavior in both agents before extending the pattern to validation and core development.
Validation should exercise realistic requests, including a CUDA multiprocessing/resource test, a Pathfinder loader test, and a documentation-only change. Check that each agent finds the appropriate guidance, selects relevant references, and preserves the essential local constraints. Include skill frontmatter/reference checks and verify the proposed discovery layout on supported contributor setups, including Windows.
Changes to the CCCL submodule and new release automation are outside the proposed first increment.
Questions for the team
- Does this division keep essential repository and package constraints sufficiently visible?
- Are the proposed skill boundaries useful, and is test authoring the right first extraction?
- Is
.agents/skillswith Claude discovery links an appropriate shared layout? - Is the suggested first increment a useful scope for implementation and review?
Generated from codex (GPT-6.1-Sol ultra) session ID: 01a16563-6da0-7302-b60c-533b766fd1a8
Activity