feat: add boundary-validator skill for automated code review (#48)

Co-authored-by: Claude Sonnet 4.5 <noreply@anthropic.com>

Author: roottool

AGENTS.md

@@ -242,3 +242,76 @@ If a change makes the parser:
 it likely violates the boundary.
 
 When in doubt, reject the change.
+
+---
+
+## Agent Skills
+
+This project provides the content of AGENTS.md in Agent Skills format through the `skills/` directory.
+
+### Purpose
+
+Agent Skills are structured knowledge packages optimized for Claude Code and similar AI-powered development tools. They enable:
+
+- **Automatic triggering**: Skills activate during PR creation, code review, etc.
+- **Progressive disclosure**: Load only necessary information on demand
+- **Standardized format**: Follows [agentskills.dev](https://agentskills.dev) specification
+
+### Available Skills
+
+#### boundary-validator (`skills/boundary-validator/`)
+
+Validates code changes against the Design rules and Security rules defined in this document.
+
+- **Purpose**: Automated detection of boundary principle violations
+- **Triggers**: PR creation, code review, post-implementation checks
+- **Coverage**:
+  - Keys are opaque strings (no bracket/dot notation parsing)
+  - No silent behavior (detect duplicate keys)
+  - No inference, no convenience (no type coercion, validation)
+  - Explicit issue reporting (no exceptions for input errors)
+  - Security rules (forbidden keys, prototype safety)
+
+**Supported tools**: Claude Code
+
+For details, see [`skills/boundary-validator/SKILL.md`](skills/boundary-validator/SKILL.md).
+
+### Using Skills in Other Tools
+
+Agent Skills are currently supported primarily by Claude Code. For other development tools:
+
+| Tool              | Support   | Usage                                        |
+| ----------------- | --------- | -------------------------------------------- |
+| **Claude Code**   | ✅ Full   | Automatic detection of `skills/` directory   |
+| **Windsurf**      | ⚠️ Manual | Reference this AGENTS.md directly in prompts |
+| **Cursor**        | ⚠️ Manual | Use `.cursorrules` or reference AGENTS.md    |
+| **claude.ai Web** | ⚠️ Manual | Upload SKILL.md as project knowledge         |
+
+**For non-supported tools**: Use this AGENTS.md document directly, or configure your tool to reference the project's design principles explicitly in CLAUDE.md.
+
+### Relationship to AGENTS.md
+
+- **AGENTS.md is the source of truth**: All design principle changes are made here first
+- **Skills are optimized versions**: The `skills/` directory provides the same rules in a format optimized for agent consumption
+- **Synchronization**: When AGENTS.md is updated, corresponding files in `skills/boundary-validator/references/` should be updated
+
+This is a **strategic duplication**:
+
+- **AGENTS.md**: Human-readable, comprehensive, works with all tools
+- **skills/**: Agent-optimized, progressive disclosure, auto-triggering (Claude Code)
+
+Both serve different audiences and purposes, making the duplication necessary for maximum compatibility.
+
+### Maintenance
+
+When updating design rules:
+
+1. **Edit AGENTS.md first** (this file is the master)
+2. **Update corresponding references** in `skills/boundary-validator/references/`
+   - `design-rules.md` - Lines 36-75 of this file
+   - `security-rules.md` - Lines 76-95 of this file
+   - `api-contract.md` - Lines 119-199 of this file
+3. **Increment skill version** in `skills/boundary-validator/SKILL.md` frontmatter
+4. **Commit both** AGENTS.md and skills/ changes together
+
+For more information about the skills system, see [`skills/README.md`](skills/README.md).

CLAUDE.md

@@ -22,6 +22,42 @@ When implementing features or reviewing code:
 2. Then, apply AGENTS.md technical constraints
 3. If a change makes the parser smarter/more convenient, it likely violates the boundary → reject it
 
+## Project Skills
+
+This project includes **Agent Skills** in the `skills/` directory, providing automated code review capabilities for Claude Code.
+
+### boundary-validator
+
+The `boundary-validator` skill automatically validates code changes against AGENTS.md design rules:
+
+- **Location**: `skills/boundary-validator/`
+- **Purpose**: Detect boundary principle violations during PR creation and code review
+- **Triggers**: Automatically activates when creating PRs or requesting code reviews
+- **Coverage**:
+  - Keys are opaque strings (no bracket/dot notation parsing)
+  - No silent behavior (detect duplicate keys)
+  - No inference, no convenience (no type coercion, validation)
+  - Explicit issue reporting (no exceptions for input errors)
+  - Security rules (forbidden keys, prototype safety)
+
+**Usage in Claude Code**:
+
+```
+Review this code against boundary-validator rules
+```
+
+The skill will automatically check your implementation for violations and provide specific feedback with line references.
+
+### For Non-Claude Code Tools
+
+If you're using other development tools (Windsurf, Cursor, etc.):
+
+- **Reference AGENTS.md directly** in your prompts or tool configuration
+- Agent Skills are primarily designed for Claude Code
+- See `skills/README.md` for more details on cross-tool compatibility
+
+For complete information about the skills system, see [`skills/README.md`](skills/README.md) and [`AGENTS.md`](AGENTS.md#agent-skills).
+
 ## API Documentation
 
 For complete API documentation, TypeScript interfaces, and usage examples, see **README.md**.

skills/README.md

@@ -0,0 +1,66 @@
+# safe-formdata Agent Skills
+
+This directory contains **Agent Skills** specific to the safe-formdata project.
+
+## What are Agent Skills?
+
+Agent Skills are structured knowledge packages that agents like Claude Code can efficiently reference. Based on the implementation rules in AGENTS.md, they provide:
+
+- **Automatic triggering**: Activates automatically during PR creation and code review
+- **Progressive disclosure**: Loads only necessary information incrementally
+- **Standardized format**: Complies with the [agentskills.dev](https://agentskills.dev) official specification
+
+## Available Skills
+
+### boundary-validator
+
+Performs code review based on boundary principles.
+
+- **Purpose**: Automatically detect violations of safe-formdata's design principles
+- **Triggers**: PR creation, code review, post-implementation
+- **Validation items**:
+  - Key opacity (no array notation parsing, etc.)
+  - No silent behavior (no merging, overwriting, etc.)
+  - No inference or convenience features
+  - Explicit error reporting
+
+For details, see [`boundary-validator/SKILL.md`](./boundary-validator/SKILL.md).
+
+## Supported Tools
+
+### ✅ Automatic Support
+
+- **Claude Code** - Automatically detects `skills/` in the project
+
+### ⚠️ Manual Reference Required
+
+- **Windsurf** - Instruct to reference AGENTS.md directly
+- **Cursor** - Specify rules in AGENTS.md or `.cursorrules`
+- **claude.ai Web** - Manually upload as project knowledge
+
+## Relationship to AGENTS.md
+
+- **AGENTS.md**: Master document for both humans and agents
+- **skills/**: Optimized version for Agent Skills-compatible tools
+
+If you're using tools that don't support Agent Skills, please reference [AGENTS.md](../AGENTS.md) directly.
+
+## Maintenance Policy
+
+1. **AGENTS.md is the source of truth**: Make design principle changes in AGENTS.md first
+2. **Skills follow**: Reflect AGENTS.md changes in `skills/`
+3. **Strategic duplication**: Document duplication is acceptable due to different purposes
+
+## Official Specification
+
+The Skills in this directory comply with the [agentskills.dev](https://agentskills.dev) official specification.
+
+Validation tool:
+
+```bash
+skills-ref validate ./boundary-validator
+```
+
+## License
+
+The same license as the safe-formdata project applies. See `LICENSE.txt` in each skill.

skills/boundary-validator/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 roottool
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.