| name | scaffold-cmake-cxx-sanitize-gtest-env |
| description | WHEN/WHERE/WHO: [Scheduling: Use when an AI Agent needs to bootstrap a C/C++ project with robust testing and security guardrails.] HOW: [Structural: Use this SKILL to inject a standardized CMakeLists.txt that auto-discovers Google Tests and supports Clang/GCC Sanitizers, and to generate a build guide.] WHY: [Scheduling: Ensures all C/C++ projects have a uniform, secure, and easily testable baseline environment without manual configuration.]
|
Scaffold CMake C++ Sanitize & GTest Environment
Who
AI Agents, C/C++ Developers, and Build Engineers setting up or upgrading a project repository.
What
Injects a battle-tested CMakeLists.txt template that enforces C11/CXX17 standards, provides compiler fallbacks (e.g., macOS Homebrew LLVM), configures Address/Thread/Memory/UndefinedBehavior Sanitizers, and uses a custom function to auto-discover and build Google Tests. It also generates a README_BuildRunTest.md guide for the project.
When
Invoke this skill when a user asks to "set up a C++ project", "configure CMake with GTest", "add sanitizers to this C project", or "scaffold the C++ testing environment".
Near-miss: Do not use this if the user explicitly wants to use a different build system like Bazel or Make.
Where
Applies to the root directory of a C or C++ codebase.
Why
Manually configuring CMake for cross-platform compilation, sanitizer flags, and GTest linkage is highly error-prone. Standardizing this via an agentic skill ensures that every codebase is immediately ready for secure, test-driven development.
Inputs
- Project Name: The name of the C/C++ project.
- Target Directory: The root directory of the project.
Output (Logical Evidence)
- A configured
CMakeLists.txt in the root directory.
- A
Test/ directory for unit tests.
- A
README_BuildRunTest.md explaining how to build and test the project.
- A
.vscode/settings.json file configuring CMake Tools and clangd.
Optimization Readiness
- Failure Signals: The scaffold overwrites existing build files without consent, sanitizer branches are missing, test discovery is manual, or the generated environment fails on the target platform.
- Evidence To Collect: Generated CMake files, build/run docs, VSCode settings, and examples where the scaffolded environment handled sanitizer and test setup correctly.
- Safe Mutation Boundaries: Refine template substitution, test-directory scaffolding, build-guide generation, and VSCode settings merging without changing the core CMake-plus-sanitizer bootstrap.
- Acceptance Criteria: Accept revisions only if the scaffolding is present, sanitizer flags are included, test discovery is automatic, and existing configuration is respected rather than overwritten blindly.
- Rejected Revision Handling: Record overwrite attempts, missing sanitizer branches, and brittle test-name assumptions so they are not repeated.
- Transfer Check: Verify the workflow still works for empty projects and for projects with an existing complex
CMakeLists.txt that require merge decisions.
- Stop Rule: If the project layout or merge strategy is unclear, stop and ask before writing build files.
Constraints (Logical Boundaries)
- Sanitizer Flags: The
CMakeLists.txt MUST include branches for DiagASAN, DiagTSAN, DiagUBSAN, DiagMSAN, and DiagLSAN.
- macOS Compatibility: MUST include the
-Wno-availability compiler option to suppress macOS system header warnings.
- Anti-Pattern Mapping:
- DO NOT hardcode test executable names manually in CMake; use the template's auto-discovery loop for
*.cxx files.
- DO NOT overwrite an existing
CMakeLists.txt without the user's explicit confirmation or taking a backup.
One More Thing
If the project already has a complex CMakeLists.txt, stop and ask the user if they want to merge the sanitizer/GTest logic into the existing file or replace it entirely.
How (The 4-Phase Refinement Protocol)
<Use imperative state-machine logic. Every phase must explicitly define branching (If/Then/Else).>
Phase 1: Environment Analysis
Input State: A target directory and project name.
- Check for the existence of an existing
CMakeLists.txt.
- Branch: If it exists, pause and ask the user how to proceed (merge or overwrite).
Output State: Clearance to write CMake configuration.
Phase 2: Scaffold CMakeLists.txt
Input State: Clearance to write.
- Read the template from
details/cmake-template.md.
- Replace the placeholder project name (
MyCraftCodes) with the user's Project Name.
- Write the resulting configuration to
CMakeLists.txt in the target directory.
Output State: A robust CMake configuration file created.
Phase 3: Scaffold Test Directory
Input State: CMake configured.
- Check if the
Test/ directory exists in the target directory.
- Branch: If it does not exist, create it.
Output State: A
Test/ directory ready to receive *.cxx files.
Phase 4: Generate Build/Run/Test Documentation
Input State: Scaffolding complete.
- Read the template from
details/readme-build-run-test-template.md.
- Replace any placeholders with the Project Name.
- Write the resulting markdown to
README_BuildRunTest.md in the target directory.
Output State: Project documentation generated.
Phase 5: Scaffold VSCode Configuration
Input State: Workspace prepared.
- Check if the
.vscode/ directory exists. If not, create it.
- Read the template from
details/vscode-settings-template.md.
- Write the configuration to
.vscode/settings.json (merging with existing settings if necessary).
Output State: VSCode environment fully configured for CMake and Sanitizers.
Validation (Verifiable Rewards)
- Verify that
CMakeLists.txt exists and contains the string DiagASAN.
- Verify that the
Test/ directory exists.
- Verify that
README_BuildRunTest.md exists.
- If verification passes, report successful scaffolding to the user.
