{"owner":"project-chip","repo":"connectedhomeip","hasSkills":true,"hasMcp":false,"mcpConfig":null,"found":["AGENTS.md"],"skills":{"AGENTS.md":"# AI Agent Guidelines for Matter SDK\n\nThis file provides guidelines and instructions for AI agents working on the\nMatter SDK codebase.\n\n## General Principles\n\n-   **When in Rome**: Match the prevailing style of the code being modified. See\n    [docs/style/CODING_STYLE_GUIDE.md](docs/style/CODING_STYLE_GUIDE.md).\n-   **Atomicity**: Make small, incremental changes. Do not mix refactoring with\n    feature implementation.\n-   **No Filler Names**: Avoid names like \"support\", \"common\", \"helpers\",\n    \"util\", \"core\". Use concrete names.\n-   **Error Handling**: Use `CHIP_ERROR` as the standard return type for\n    fallible operations. Prefer `VerifyOrReturnError` and `ReturnErrorOnFailure`\n    macros for concise error checking and propagation.\n-   Ensure resources are cleaned up appropriately, especially on early returns.\n    Generally prefer RAII patterns for cleanup.\n-   **Logging**: Use the `ChipLog*` macros (e.g., `ChipLogProgress`,\n    `ChipLogError`, `ChipLogDetail`) for logging. Ensure logs are appropriately\n    categorized by module (e.g., `AppServer`, `InteractionModel`).\n\n## Ignored Directories\n\nWhen searching for files or code patterns, ignore the following directories\nunless explicitly asked to look there:\n\n-   `third_party/` (contains external dependencies)\n-   `out/` (contains build artifacts)\n\n## Code Review Instructions\n\n-   Do not comment on content for XML files or .matter content for clusters.\n-   The SDK implements an in-progress Matter specification that may be in flux\n    and may not be available to all contributors. Assume the Matter\n    specification is unknown and out of scope _unless_ you have explicit access\n    to the latest version (e.g., via a specialized tool or skill).\n-   Avoid \"pat on the back\" style comments that just restate what the code is\n    doing. Focus on suggesting concrete code improvements.\n-   Be concise. Do not over-explain code.\n-   Look for common typos and suggest fixes.\n-   Do not comment on whitespace or formatting (auto-formatters handle this).\n-   Review changes for embedded development:\n    -   Minimize use of heap allocation.\n    -   Optimize for resource usage (RAM/Flash).\n    -   Be cautious with complex templates that could lead to code bloat.\n\n## API preferences\n\n-   Prefer using `chip::Span` from `src/lib/support/Span.h` to pointer + size\n    groups. Pass `Span` by value rather than const reference (treat it as a\n    `string_view`)\n-   Use `\"foo\"_span` (i.e. `operator _span`) for const char spans instead of\n    `fromCharString`.\n-   Prefer `std::optional` to `chip::Optional`\n-   Prefer `StringBuilder` from `src/lib/support/StringBuilder.h` to using\n    `snprintf` for string formatting.\n\n## Coding Style (Highlights)\n\nRefer to [docs/style/CODING_STYLE_GUIDE.md](docs/style/CODING_STYLE_GUIDE.md)\nfor full details.\n\n-   **C++**: C++17 standard.\n    -   Use fixed-width integer types from `<cstdint>` for POD integer types\n    -   Avoid top-level `using namespace` in headers.\n    -   Use anonymous namespaces for file-internal classes/objects.\n    -   Avoid heap allocation and auto-resizing containers in core SDK.\n-   **Python**: Python 3.11 standard.\n    -   Use type hints on public APIs.\n    -   Include docstrings for public APIs.\n-   _Always_ include `{}` bracketing for control flows, even if using one liners\n    (e.g. for `if`, `while`, `for` and such)\n\n## Testing\n\n-   Unit tests are required for all changes unless unit testing is impossible\n    (e.g., platform-specific code).\n-   Tests in `src/python_testing` and `src/app/tests/suites` which verify\n    expected failures should clearly indicate why the failure is expected.\n    Include a summary of the relevant specification requirements if possible.\n\n## Architectural Constraints\n\n### Code-Driven Clusters\n\nCode-driven clusters are implementations in `src/app/clusters` that use\n`DefaultServerCluster` as a base class. When developing them:\n\n-   `ReadAttribute`, `WriteAttribute`, and `InvokeCommand` are by API contract\n    only called for existent paths. Do not add path validity checks — they\n    increase code size and are redundant as long as `Attributes` or\n    `AcceptedCommands` are correct.\n-   Ember APIs and generated ZAP accessors must not be used outside the\n    `CodegenIntegration` layer. `CodegenIntegration.h/cpp` is the documented\n    bridge between generated configuration and code-driven cluster logic. Avoid\n    types like `EmberAfStatus` or functions like `emberAfContainsServer`,\n    `emberAfReadAttribute`, or `emberAfWriteAttribute` in core cluster code.\n-   When adding files: codegen-specific files belong in\n    `app_config_dependent_sources.cmake/gni`; all others belong in `BUILD.gn`.\n    Ensure every file (especially headers) is listed in one of these — there\n    should be no unreferenced files.\n\n### Example Applications (Documentation Discovery)\n\nWhen operating on or analyzing reference applications (such as\n`examples/all-devices-app` or custom simulator tools), always inspect that\napplication's dedicated `docs/` folder or `ARCHITECTURE.md` file to understand\nits dynamic runtime Interaction Model, specific CLI parameters, and recommended\nproduct baseline patterns before modifying or generating code.\n\n## Common Commands\n\nMost commands require an activated environment.\n\n### Environment Activation\n\nYou can run commands within the environment using `scripts/run_in_build_env.sh`:\n`scripts/run_in_build_env.sh \"command\"`\n\nAlternatively, you can activate the environment in your shell:\n`source scripts/activate.sh`\n\n### Build and Test\n\n-   **List available targets**:\n    `scripts/run_in_build_env.sh \"./scripts/build/build_examples.py targets\"`\n-   **Generate Ninja files**:\n    `scripts/run_in_build_env.sh \"./scripts/build/build_examples.py --target linux-x64-tests-clang --quiet gen\"`\n-   **Build and run all tests**:\n    `scripts/run_in_build_env.sh \"./scripts/build/build_examples.py --target linux-x64-tests-clang --quiet build\"`\n-   **Run a specific test**:\n    `scripts/run_in_build_env.sh \"ninja -C out/linux-x64-tests-clang --quiet path/to/test:test_name.run\"`\n\n    -   Explicit example:\n        `scripts/run_in_build_env.sh \"ninja -C out/linux-x64-tests-clang src/app/clusters/occupancy-sensor-server/tests:TestOccupancySensingCluster.run\"`\n    -   Compile and run can be separated (e.g. if running under some memory\n        debugger or needing to set other options):\n\n            ```bash\n            scripts/run_in_build_env.sh \"ninja -C out/linux-x64-tests-clang src/app/clusters/occupancy-sensor-server/tests:TestOccupancySensingCluster\"`\n            ./out/linux-x64-tests-clang/tests/TestOccupancySensingCluster\n            ```\n\n### Building Common Apps\n\n-   **chip-tool** (Interactive commissioning tool):\n    `scripts/run_in_build_env.sh \"./scripts/build/build_examples.py --target linux-x64-chip-tool-clang --quiet build\"`\n-   **all-clusters-app** (Feature-rich device simulator):\n    `scripts/run_in_build_env.sh \"./scripts/build/build_examples.py --target linux-x64-all-clusters-clang --quiet build\"`\n-   **all-devices-app** (Alternative feature-rich simulator):\n    `scripts/run_in_build_env.sh \"./scripts/build/build_examples.py --target linux-x64-all-devices-clang --quiet build\"`\n\n## Development Resources\n\n-   [docs/guides/writing_clusters.md](docs/guides/writing_clusters.md)\n-   [docs/guides/migrating_ember_cluster_to_code_driven.md](docs/guides/migrating_ember_cluster_to_code_driven.md)\n-   [docs/testing/unit_testing.md](docs/testing/unit_testing.md)\n-   [docs/testing/integration_tests.md](docs/testing/integration_tests.md)\n"},"files":{"AGENTS.md":"# AI Agent Guidelines for Matter SDK\n\nThis file provides guidelines and instructions for AI agents working on the\nMatter SDK codebase.\n\n## General Principles\n\n-   **When in Rome**: Match the prevailing style of the code being modified. See\n    [docs/style/CODING_STYLE_GUIDE.md](docs/style/CODING_STYLE_GUIDE.md).\n-   **Atomicity**: Make small, incremental changes. Do not mix refactoring with\n    feature implementation.\n-   **No Filler Names**: Avoid names like \"support\", \"common\", \"helpers\",\n    \"util\", \"core\". Use concrete names.\n-   **Error Handling**: Use `CHIP_ERROR` as the standard return type for\n    fallible operations. Prefer `VerifyOrReturnError` and `ReturnErrorOnFailure`\n    macros for concise error checking and propagation.\n-   Ensure resources are cleaned up appropriately, especially on early returns.\n    Generally prefer RAII patterns for cleanup.\n-   **Logging**: Use the `ChipLog*` macros (e.g., `ChipLogProgress`,\n    `ChipLogError`, `ChipLogDetail`) for logging. Ensure logs are appropriately\n    categorized by module (e.g., `AppServer`, `InteractionModel`).\n\n## Ignored Directories\n\nWhen searching for files or code patterns, ignore the following directories\nunless explicitly asked to look there:\n\n-   `third_party/` (contains external dependencies)\n-   `out/` (contains build artifacts)\n\n## Code Review Instructions\n\n-   Do not comment on content for XML files or .matter content for clusters.\n-   The SDK implements an in-progress Matter specification that may be in flux\n    and may not be available to all contributors. Assume the Matter\n    specification is unknown and out of scope _unless_ you have explicit access\n    to the latest version (e.g., via a specialized tool or skill).\n-   Avoid \"pat on the back\" style comments that just restate what the code is\n    doing. Focus on suggesting concrete code improvements.\n-   Be concise. Do not over-explain code.\n-   Look for common typos and suggest fixes.\n-   Do not comment on whitespace or formatting (auto-formatters handle this).\n-   Review changes for embedded development:\n    -   Minimize use of heap allocation.\n    -   Optimize for resource usage (RAM/Flash).\n    -   Be cautious with complex templates that could lead to code bloat.\n\n## API preferences\n\n-   Prefer using `chip::Span` from `src/lib/support/Span.h` to pointer + size\n    groups. Pass `Span` by value rather than const reference (treat it as a\n    `string_view`)\n-   Use `\"foo\"_span` (i.e. `operator _span`) for const char spans instead of\n    `fromCharString`.\n-   Prefer `std::optional` to `chip::Optional`\n-   Prefer `StringBuilder` from `src/lib/support/StringBuilder.h` to using\n    `snprintf` for string formatting.\n\n## Coding Style (Highlights)\n\nRefer to [docs/style/CODING_STYLE_GUIDE.md](docs/style/CODING_STYLE_GUIDE.md)\nfor full details.\n\n-   **C++**: C++17 standard.\n    -   Use fixed-width integer types from `<cstdint>` for POD integer types\n    -   Avoid top-level `using namespace` in headers.\n    -   Use anonymous namespaces for file-internal classes/objects.\n    -   Avoid heap allocation and auto-resizing containers in core SDK.\n-   **Python**: Python 3.11 standard.\n    -   Use type hints on public APIs.\n    -   Include docstrings for public APIs.\n-   _Always_ include `{}` bracketing for control flows, even if using one liners\n    (e.g. for `if`, `while`, `for` and such)\n\n## Testing\n\n-   Unit tests are required for all changes unless unit testing is impossible\n    (e.g., platform-specific code).\n-   Tests in `src/python_testing` and `src/app/tests/suites` which verify\n    expected failures should clearly indicate why the failure is expected.\n    Include a summary of the relevant specification requirements if possible.\n\n## Architectural Constraints\n\n### Code-Driven Clusters\n\nCode-driven clusters are implementations in `src/app/clusters` that use\n`DefaultServerCluster` as a base class. When developing them:\n\n-   `ReadAttribute`, `WriteAttribute`, and `InvokeCommand` are by API contract\n    only called for existent paths. Do not add path validity checks — they\n    increase code size and are redundant as long as `Attributes` or\n    `AcceptedCommands` are correct.\n-   Ember APIs and generated ZAP accessors must not be used outside the\n    `CodegenIntegration` layer. `CodegenIntegration.h/cpp` is the documented\n    bridge between generated configuration and code-driven cluster logic. Avoid\n    types like `EmberAfStatus` or functions like `emberAfContainsServer`,\n    `emberAfReadAttribute`, or `emberAfWriteAttribute` in core cluster code.\n-   When adding files: codegen-specific files belong in\n    `app_config_dependent_sources.cmake/gni`; all others belong in `BUILD.gn`.\n    Ensure every file (especially headers) is listed in one of these — there\n    should be no unreferenced files.\n\n### Example Applications (Documentation Discovery)\n\nWhen operating on or analyzing reference applications (such as\n`examples/all-devices-app` or custom simulator tools), always inspect that\napplication's dedicated `docs/` folder or `ARCHITECTURE.md` file to understand\nits dynamic runtime Interaction Model, specific CLI parameters, and recommended\nproduct baseline patterns before modifying or generating code.\n\n## Common Commands\n\nMost commands require an activated environment.\n\n### Environment Activation\n\nYou can run commands within the environment using `scripts/run_in_build_env.sh`:\n`scripts/run_in_build_env.sh \"command\"`\n\nAlternatively, you can activate the environment in your shell:\n`source scripts/activate.sh`\n\n### Build and Test\n\n-   **List available targets**:\n    `scripts/run_in_build_env.sh \"./scripts/build/build_examples.py targets\"`\n-   **Generate Ninja files**:\n    `scripts/run_in_build_env.sh \"./scripts/build/build_examples.py --target linux-x64-tests-clang --quiet gen\"`\n-   **Build and run all tests**:\n    `scripts/run_in_build_env.sh \"./scripts/build/build_examples.py --target linux-x64-tests-clang --quiet build\"`\n-   **Run a specific test**:\n    `scripts/run_in_build_env.sh \"ninja -C out/linux-x64-tests-clang --quiet path/to/test:test_name.run\"`\n\n    -   Explicit example:\n        `scripts/run_in_build_env.sh \"ninja -C out/linux-x64-tests-clang src/app/clusters/occupancy-sensor-server/tests:TestOccupancySensingCluster.run\"`\n    -   Compile and run can be separated (e.g. if running under some memory\n        debugger or needing to set other options):\n\n            ```bash\n            scripts/run_in_build_env.sh \"ninja -C out/linux-x64-tests-clang src/app/clusters/occupancy-sensor-server/tests:TestOccupancySensingCluster\"`\n            ./out/linux-x64-tests-clang/tests/TestOccupancySensingCluster\n            ```\n\n### Building Common Apps\n\n-   **chip-tool** (Interactive commissioning tool):\n    `scripts/run_in_build_env.sh \"./scripts/build/build_examples.py --target linux-x64-chip-tool-clang --quiet build\"`\n-   **all-clusters-app** (Feature-rich device simulator):\n    `scripts/run_in_build_env.sh \"./scripts/build/build_examples.py --target linux-x64-all-clusters-clang --quiet build\"`\n-   **all-devices-app** (Alternative feature-rich simulator):\n    `scripts/run_in_build_env.sh \"./scripts/build/build_examples.py --target linux-x64-all-devices-clang --quiet build\"`\n\n## Development Resources\n\n-   [docs/guides/writing_clusters.md](docs/guides/writing_clusters.md)\n-   [docs/guides/migrating_ember_cluster_to_code_driven.md](docs/guides/migrating_ember_cluster_to_code_driven.md)\n-   [docs/testing/unit_testing.md](docs/testing/unit_testing.md)\n-   [docs/testing/integration_tests.md](docs/testing/integration_tests.md)\n"},"items":[{"name":"AGENTS.md","path":"AGENTS.md","title":"AGENTS.md","content":"# AI Agent Guidelines for Matter SDK\n\nThis file provides guidelines and instructions for AI agents working on the\nMatter SDK codebase.\n\n## General Principles\n\n-   **When in Rome**: Match the prevailing style of the code being modified. See\n    [docs/style/CODING_STYLE_GUIDE.md](docs/style/CODING_STYLE_GUIDE.md).\n-   **Atomicity**: Make small, incremental changes. Do not mix refactoring with\n    feature implementation.\n-   **No Filler Names**: Avoid names like \"support\", \"common\", \"helpers\",\n    \"util\", \"core\". Use concrete names.\n-   **Error Handling**: Use `CHIP_ERROR` as the standard return type for\n    fallible operations. Prefer `VerifyOrReturnError` and `ReturnErrorOnFailure`\n    macros for concise error checking and propagation.\n-   Ensure resources are cleaned up appropriately, especially on early returns.\n    Generally prefer RAII patterns for cleanup.\n-   **Logging**: Use the `ChipLog*` macros (e.g., `ChipLogProgress`,\n    `ChipLogError`, `ChipLogDetail`) for logging. Ensure logs are appropriately\n    categorized by module (e.g., `AppServer`, `InteractionModel`).\n\n## Ignored Directories\n\nWhen searching for files or code patterns, ignore the following directories\nunless explicitly asked to look there:\n\n-   `third_party/` (contains external dependencies)\n-   `out/` (contains build artifacts)\n\n## Code Review Instructions\n\n-   Do not comment on content for XML files or .matter content for clusters.\n-   The SDK implements an in-progress Matter specification that may be in flux\n    and may not be available to all contributors. Assume the Matter\n    specification is unknown and out of scope _unless_ you have explicit access\n    to the latest version (e.g., via a specialized tool or skill).\n-   Avoid \"pat on the back\" style comments that just restate what the code is\n    doing. Focus on suggesting concrete code improvements.\n-   Be concise. Do not over-explain code.\n-   Look for common typos and suggest fixes.\n-   Do not comment on whitespace or formatting (auto-formatters handle this).\n-   Review changes for embedded development:\n    -   Minimize use of heap allocation.\n    -   Optimize for resource usage (RAM/Flash).\n    -   Be cautious with complex templates that could lead to code bloat.\n\n## API preferences\n\n-   Prefer using `chip::Span` from `src/lib/support/Span.h` to pointer + size\n    groups. Pass `Span` by value rather than const reference (treat it as a\n    `string_view`)\n-   Use `\"foo\"_span` (i.e. `operator _span`) for const char spans instead of\n    `fromCharString`.\n-   Prefer `std::optional` to `chip::Optional`\n-   Prefer `StringBuilder` from `src/lib/support/StringBuilder.h` to using\n    `snprintf` for string formatting.\n\n## Coding Style (Highlights)\n\nRefer to [docs/style/CODING_STYLE_GUIDE.md](docs/style/CODING_STYLE_GUIDE.md)\nfor full details.\n\n-   **C++**: C++17 standard.\n    -   Use fixed-width integer types from `<cstdint>` for POD integer types\n    -   Avoid top-level `using namespace` in headers.\n    -   Use anonymous namespaces for file-internal classes/objects.\n    -   Avoid heap allocation and auto-resizing containers in core SDK.\n-   **Python**: Python 3.11 standard.\n    -   Use type hints on public APIs.\n    -   Include docstrings for public APIs.\n-   _Always_ include `{}` bracketing for control flows, even if using one liners\n    (e.g. for `if`, `while`, `for` and such)\n\n## Testing\n\n-   Unit tests are required for all changes unless unit testing is impossible\n    (e.g., platform-specific code).\n-   Tests in `src/python_testing` and `src/app/tests/suites` which verify\n    expected failures should clearly indicate why the failure is expected.\n    Include a summary of the relevant specification requirements if possible.\n\n## Architectural Constraints\n\n### Code-Driven Clusters\n\nCode-driven clusters are implementations in `src/app/clusters` that use\n`DefaultServerCluster` as a base class. When developing them:\n\n-   `ReadAttribute`, `WriteAttribute`, and `InvokeCommand` are by API contract\n    only called for existent paths. Do not add path validity checks — they\n    increase code size and are redundant as long as `Attributes` or\n    `AcceptedCommands` are correct.\n-   Ember APIs and generated ZAP accessors must not be used outside the\n    `CodegenIntegration` layer. `CodegenIntegration.h/cpp` is the documented\n    bridge between generated configuration and code-driven cluster logic. Avoid\n    types like `EmberAfStatus` or functions like `emberAfContainsServer`,\n    `emberAfReadAttribute`, or `emberAfWriteAttribute` in core cluster code.\n-   When adding files: codegen-specific files belong in\n    `app_config_dependent_sources.cmake/gni`; all others belong in `BUILD.gn`.\n    Ensure every file (especially headers) is listed in one of these — there\n    should be no unreferenced files.\n\n### Example Applications (Documentation Discovery)\n\nWhen operating on or analyzing reference applications (such as\n`examples/all-devices-app` or custom simulator tools), always inspect that\napplication's dedicated `docs/` folder or `ARCHITECTURE.md` file to understand\nits dynamic runtime Interaction Model, specific CLI parameters, and recommended\nproduct baseline patterns before modifying or generating code.\n\n## Common Commands\n\nMost commands require an activated environment.\n\n### Environment Activation\n\nYou can run commands within the environment using `scripts/run_in_build_env.sh`:\n`scripts/run_in_build_env.sh \"command\"`\n\nAlternatively, you can activate the environment in your shell:\n`source scripts/activate.sh`\n\n### Build and Test\n\n-   **List available targets**:\n    `scripts/run_in_build_env.sh \"./scripts/build/build_examples.py targets\"`\n-   **Generate Ninja files**:\n    `scripts/run_in_build_env.sh \"./scripts/build/build_examples.py --target linux-x64-tests-clang --quiet gen\"`\n-   **Build and run all tests**:\n    `scripts/run_in_build_env.sh \"./scripts/build/build_examples.py --target linux-x64-tests-clang --quiet build\"`\n-   **Run a specific test**:\n    `scripts/run_in_build_env.sh \"ninja -C out/linux-x64-tests-clang --quiet path/to/test:test_name.run\"`\n\n    -   Explicit example:\n        `scripts/run_in_build_env.sh \"ninja -C out/linux-x64-tests-clang src/app/clusters/occupancy-sensor-server/tests:TestOccupancySensingCluster.run\"`\n    -   Compile and run can be separated (e.g. if running under some memory\n        debugger or needing to set other options):\n\n            ```bash\n            scripts/run_in_build_env.sh \"ninja -C out/linux-x64-tests-clang src/app/clusters/occupancy-sensor-server/tests:TestOccupancySensingCluster\"`\n            ./out/linux-x64-tests-clang/tests/TestOccupancySensingCluster\n            ```\n\n### Building Common Apps\n\n-   **chip-tool** (Interactive commissioning tool):\n    `scripts/run_in_build_env.sh \"./scripts/build/build_examples.py --target linux-x64-chip-tool-clang --quiet build\"`\n-   **all-clusters-app** (Feature-rich device simulator):\n    `scripts/run_in_build_env.sh \"./scripts/build/build_examples.py --target linux-x64-all-clusters-clang --quiet build\"`\n-   **all-devices-app** (Alternative feature-rich simulator):\n    `scripts/run_in_build_env.sh \"./scripts/build/build_examples.py --target linux-x64-all-devices-clang --quiet build\"`\n\n## Development Resources\n\n-   [docs/guides/writing_clusters.md](docs/guides/writing_clusters.md)\n-   [docs/guides/migrating_ember_cluster_to_code_driven.md](docs/guides/migrating_ember_cluster_to_code_driven.md)\n-   [docs/testing/unit_testing.md](docs/testing/unit_testing.md)\n-   [docs/testing/integration_tests.md](docs/testing/integration_tests.md)\n","category":"root","tokens":1891}]}