Skip to content

Commit 1a474d8

Browse files
tymondesignstymondesigns
committed
wip
1 parent bddbb8e commit 1a474d8

File tree

3 files changed

+174
-22
lines changed

3 files changed

+174
-22
lines changed

‎composer.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -17,7 +17,7 @@
1717
],
1818
"require": {
1919
"php": "^8.4",
20-
"cortexphp/json-repair": "^0.3",
20+
"cortexphp/json-repair": "^0.4",
2121
"cortexphp/json-schema": "^1.0",
2222
"cortexphp/model-info": "^0.3",
2323
"illuminate/collections": "^12.0",

‎src/Tools/Prebuilt/UseSkillTool.php‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -16,7 +16,7 @@ class UseSkillTool extends AbstractTool
1616
/**
1717
* Context key for storing active skills.
1818
*/
19-
public const ACTIVE_SKILLS_KEY = 'active_skills';
19+
public const string ACTIVE_SKILLS_KEY = 'active_skills';
2020

2121
public function __construct(
2222
protected SkillRegistry $registry,

‎tests/fixtures/skills/cortex-docs/SKILL.md‎

Lines changed: 172 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -1,35 +1,187 @@
11
---
2-
name: cortex-docs
3-
description: Use this skill for requests related to Cortex in order to fetch relevant documentation to provide accurate, up-to-date guidance.
2+
name: Cortex
3+
description: Documentation and capabilities reference for Cortex
44
---
55

6-
# cortex-docs
6+
## Capabilities
77

8-
## Overview
8+
Cortex JSON Schema enables agents to build, validate, and manage JSON schemas programmatically in PHP. Agents can create complex validation rules using a fluent API, generate schemas from existing PHP code, validate data against schemas with detailed error messages, and export schemas to standard JSON Schema format. The library supports multiple JSON Schema versions with automatic feature validation and provides comprehensive tools for API validation, configuration management, and data integrity.
99

10-
This skill explains how to access Cortex documentation to help answer questions and guide implementation.
10+
## Skills
1111

12-
## Instructions
12+
### Schema Building with Fluent API
13+
- Build schemas using intuitive fluent interface: `Schema::object('name')->properties(...)`
14+
- Create string schemas with validation: `Schema::string('email')->format(SchemaFormat::Email)->required()`
15+
- Build integer/number schemas with constraints: `Schema::integer('age')->minimum(18)->maximum(150)`
16+
- Create boolean schemas: `Schema::boolean('active')->default(true)`
17+
- Build array schemas with item validation: `Schema::array('tags')->items(Schema::string())->minItems(1)->maxItems(5)->uniqueItems(true)`
18+
- Create union types for multiple allowed types: `Schema::union([SchemaType::String, SchemaType::Integer], 'id')`
19+
- Define null schemas: `Schema::null('field')`
1320

14-
### 1. Fetch the Documentation Index
21+
### Data Type Validation
22+
- String validation with patterns, lengths, and formats
23+
- Number/integer validation with min/max, multipleOf constraints
24+
- Array validation with item schemas, tuple validation, contains validation
25+
- Object validation with properties, pattern properties, additional properties control
26+
- Boolean validation with default values
27+
- Union types allowing multiple data types
1528

16-
Use the fetch_url tool to read the following URL:
17-
https://docs.cortexphp.com/llms.txt
29+
### String Format Validation
30+
- Email format: `SchemaFormat::Email`
31+
- URI/URL formats: `SchemaFormat::Uri`, `SchemaFormat::UriReference`, `SchemaFormat::UriTemplate`
32+
- Hostname formats: `SchemaFormat::Hostname`, `SchemaFormat::IdnHostname`
33+
- IP address formats: `SchemaFormat::Ipv4`, `SchemaFormat::Ipv6`
34+
- Date/time formats: `SchemaFormat::Date`, `SchemaFormat::Time`, `SchemaFormat::DateTime`
35+
- UUID format: `SchemaFormat::Uuid` (Draft 2019-09+)
36+
- Duration format: `SchemaFormat::Duration` (ISO 8601, Draft 2019-09+)
37+
- JSON Pointer formats: `SchemaFormat::JsonPointer`, `SchemaFormat::RelativeJsonPointer`
38+
- Internationalized formats: `SchemaFormat::IdnEmail`, `SchemaFormat::Iri`, `SchemaFormat::IriReference`
1839

19-
This provides a structured list of all available documentation with descriptions.
40+
### Conditional Validation
41+
- If/then/else logic: `->if(condition)->then(schema)->else(schema)`
42+
- AllOf composition: All schemas must match
43+
- AnyOf composition: At least one schema must match
44+
- OneOf composition: Exactly one schema must match
45+
- Not condition: Schema must not match
46+
- Dependent schemas: Property-dependent validation rules
47+
- Nested conditional validation for complex business logic
2048

21-
### 2. Select Relevant Documentation
49+
### Code Generation
50+
- Generate schemas from PHP classes: `Schema::fromClass(UserClass::class)`
51+
- Generate from closures/functions: `Schema::fromClosure($function)`
52+
- Generate from backed enums: `Schema::fromEnum(StatusEnum::class)`
53+
- Import from JSON Schema: `Schema::fromJson($jsonString)`
54+
- Extract property types, descriptions, and deprecation status from docblocks
55+
- Automatic enum constraint generation from backed enums
2256

23-
Based on the question, identify 2-4 most relevant documentation URLs from the index. Prioritize:
24-
- Specific how-to guides for implementation questions
25-
- Core concept pages for understanding questions
26-
- Tutorials for end-to-end examples
27-
- Reference docs for API details
57+
### Schema Composition & Reuse
58+
- Define reusable components: `->addDefinition('address', Schema::object(...))`
59+
- Reference definitions: `->ref('#/$defs/address')`
60+
- Create modular schema structures
61+
- Support for complex nested schemas
62+
- Automatic $defs generation in JSON output
2863

29-
### 3. Fetch Selected Documentation
64+
### Pattern-Based Properties
65+
- Validate properties by name pattern: `->patternProperties(['^env_' => Schema::string()])`
66+
- Multiple pattern properties in single schema
67+
- Combine with regular properties and additional properties
68+
- Use regex patterns for flexible property validation
3069

31-
Use the fetch_url tool to read the selected documentation URLs.
70+
### Advanced Property Control
71+
- Required properties: `->required()`
72+
- Default values: `->default(value)`
73+
- Read-only properties: `->readOnly()`
74+
- Write-only properties: `->writeOnly()`
75+
- Deprecated properties: `->deprecated()`
76+
- Additional properties control: `->additionalProperties(false)`
77+
- Unevaluated properties validation (Draft 2019-09+)
3278

33-
### 4. Provide Accurate Guidance
79+
### Data Validation
80+
- Quick boolean validation: `$schema->isValid($data)` returns true/false
81+
- Detailed validation with exceptions: `$schema->validate($data)` throws SchemaException
82+
- Detailed error messages on validation failure
83+
- Version-aware feature validation with helpful error messages
3484

35-
After reading the documentation, complete the users request.
85+
### Schema Import & Export
86+
- Import from JSON Schema strings: `Schema::fromJson($jsonString)`
87+
- Export to JSON: `$schema->toJson(JSON_PRETTY_PRINT)`
88+
- Export to array: `$schema->toArray()`
89+
- Automatic version detection from JSON Schema
90+
- Support for Draft-07, Draft 2019-09, and Draft 2020-12
91+
92+
### Version Management
93+
- Multi-version support: Draft-07, Draft 2019-09, Draft 2020-12
94+
- Set default version: `Schema::setDefaultVersion(SchemaVersion::Draft_2019_09)`
95+
- Specify version per schema: `Schema::object('name', SchemaVersion::Draft_2019_09)`
96+
- Automatic feature validation for version compatibility
97+
- Version-specific features with error handling
98+
99+
## Workflows
100+
101+
### Building a Complete User Registration Schema
102+
1. Create object schema: `$schema = Schema::object('user')`
103+
2. Add string properties with validation: `->properties(Schema::string('email')->format(SchemaFormat::Email)->required())`
104+
3. Add numeric properties with constraints: `Schema::integer('age')->minimum(18)->maximum(150)`
105+
4. Add conditional logic for business users: `->if(type='business')->then(require company_name)`
106+
5. Validate user data: `$schema->isValid($userData)`
107+
6. Export to JSON: `$schema->toJson(JSON_PRETTY_PRINT)`
108+
109+
### Creating Reusable Schema Components
110+
1. Define base types: `->addDefinition('address', Schema::object()->properties(...))`
111+
2. Define domain objects: `->addDefinition('customer', Schema::object()->properties(...))`
112+
3. Reference definitions throughout: `Schema::object('billing_address')->ref('#/$defs/address')`
113+
4. Build complex schemas from components
114+
5. Export complete schema with all definitions
115+
116+
### Validating API Requests
117+
1. Generate schema from closure: `Schema::fromClosure($apiFunction)`
118+
2. Extract parameter types and descriptions automatically
119+
3. Add validation rules programmatically: `->minLength(2)->pattern('^[a-z]+$')`
120+
4. Validate incoming request data: `$schema->isValid($requestData)`
121+
5. Return detailed errors on validation failure
122+
123+
### Generating Schemas from Existing Code
124+
1. Create PHP class with docblocks: `class User { /** @var string */ public string $name; }`
125+
2. Generate schema: `$schema = Schema::fromClass(User::class)`
126+
3. Add validation rules: `$schema->properties(Schema::string('name')->minLength(2))`
127+
4. Use for API documentation and validation
128+
5. Export to JSON for client-side validation
129+
130+
### Handling Complex Conditional Validation
131+
1. Define base properties: `->properties(Schema::string('payment_method'), Schema::string('card_number'))`
132+
2. Add oneOf for mutually exclusive options: `->oneOf(creditCardSchema, bankTransferSchema, cryptoSchema)`
133+
3. Each option validates specific required fields
134+
4. Validate payment data against schema
135+
5. Ensure only one payment method is valid
136+
137+
## Integration
138+
139+
Cortex JSON Schema integrates with:
140+
- **PHP 8.3+**: Built with modern PHP features and strict typing
141+
- **JSON Schema Standard**: Generates valid JSON Schema Draft-07, Draft 2019-09, and Draft 2020-12
142+
- **MCP (Model Context Protocol)**: Available as MCP server at `https://docs.cortexphp.com/mcp` for AI assistants (Cursor, Claude Desktop, VS Code Cline)
143+
- **API Frameworks**: Validate request/response data in any PHP API framework
144+
- **Configuration Management**: Validate application configuration files
145+
- **Form Validation**: Generate validation rules for frontend forms
146+
- **Database Validation**: Validate data before persistence
147+
- **External Tools**: Export schemas for use with other JSON Schema validators
148+
149+
## Context
150+
151+
### JSON Schema Versions
152+
- **Draft-07**: Basic features, widely supported
153+
- **Draft 2019-09**: Adds $defs, unevaluatedProperties, deprecated, UUID, Duration formats
154+
- **Draft 2020-12**: Latest version, default in Cortex, includes all modern features
155+
156+
### Key Concepts
157+
- **Fluent API**: Method chaining for readable schema building
158+
- **Type Safety**: PHP 8.3+ strict typing prevents runtime errors
159+
- **Composition**: Build complex schemas from simple, reusable components
160+
- **Validation**: Two modes - quick boolean checks or detailed error reporting
161+
- **Code Generation**: Extract schemas from existing PHP code via reflection
162+
163+
### Common Use Cases
164+
- API request/response validation
165+
- Configuration file validation
166+
- Form validation (backend and frontend)
167+
- Data migration and transformation
168+
- API documentation generation
169+
- Payment processing validation
170+
- User profile management
171+
- Dynamic form generation
172+
- State machine validation
173+
- Enum-based validation for status codes and options
174+
175+
### Best Practices
176+
- Use docblocks with @var and @param annotations for code generation
177+
- Leverage backed enums for clear validation constraints
178+
- Define reusable components with addDefinition() for maintainability
179+
- Use conditional validation (if/then/else) for complex business logic
180+
- Combine pattern properties with additionalProperties for flexible schemas
181+
- Specify schema versions explicitly for version-specific features
182+
- Use format validation for common data types (email, URI, date, etc.)
183+
- Apply validation rules programmatically after code generation
184+
185+
---
186+
187+
> For additional documentation and navigation, see: https://docs.cortexphp.com/llms.txt

0 commit comments

Comments
 (0)