JSON knowledge file generation with mandatory schema validation against schemas/knowledge-file.schema.json
JSON knowledge file generation with mandatory schema validation against schemas/knowledge-file.schema.json
Generates structured JSON knowledge files for target projects with mandatory schema validation against schemas/knowledge-file.schema.json.
All knowledge files MUST validate against schemas/knowledge-file.schema.json. Required fields:
| Field | Type | Constraints |
|-||-|
| $schema | const | Must be "http://json-schema.org/draft-07/schema#" |
| id | string | Pattern: ^[a-z0-9-]+$, min 3 chars, matches filename without .json |
| title | string | Min 10 chars |
| description | string | Min 20 chars |
| version | string | Semantic version |
| category | enum | ONLY: core, rag, agent-patterns, integration, observability, specialized, workflow, optimization, security, testing, ai-ml, trading, sap, dotnet, java, web |
| axiomAlignment | object | Required keys: A1_verifiability, A2_user_primacy, A3_transparency, A4_non_harm, A5_consistency (each min 10 chars) |
| patterns | object | Min 1 property. Each entry MUST have: description (min 20), use_when (min 10), code_example (min 20), best_practices (array, min 2 items each min 10 chars) |
| | array | Min 2 concrete items (min 15 chars) - |
| | array | Min 2 concrete items (min 15 chars) - |
| | array | Min 1 item, each |
| | array | Min 1 item, each |
best_practicesanti_patternsrelated_skills^[a-z0-9-]+$related_knowledge^[a-z0-9-]+\\.json$Category mapping: data-science → ai-ml, general → specialized, devops → integration, meta → core
CRITICAL: patterns must be an OBJECT (not array), with entries containing description, use_when, code_example, and best_practices.
{
"$schema": "http://json-schema.org/draft-07/schema#",
"id": "my-patterns",
"title": "My Domain Patterns for Reference",
"description": "Patterns for handling domain-specific integrations and workflows.",
"version": "1.0.0",
"category": "integration",
"axiomAlignment": {
"A1_verifiability": "Patterns include verifiable assertions.",
"A2_user_primacy": "User intent guides pattern selection.",
"A3_transparency": "Pattern logic is documented.",
"A4_non_harm": "Patterns avoid harmful side effects.",
"A5_consistency": "Patterns align with project conventions."
},
"patterns": {
"pattern-key": {
"description": "When to use this pattern with sufficient detail.",
"use_when": "Integration with external API required.",
"code_example": "// Example code snippet here...",
"best_practices": [
"First best practice with enough detail.",
"Second best practice requirement."
]
}
},
"related_skills": ["designing-apis", "integration"],
"related_knowledge": ["api-patterns.json"],
"best_practices": ["First best practice", "Second best practice"],
"anti_patterns": ["First anti-pattern", "Second anti-pattern"]
}
| Violation | Fix |
|---|---|
patterns is array | Use object with named keys |
Missing axiomAlignment | Add all 5 required axiom keys |
| Invalid category | Map to allowed enum or use mapping table |
id doesn't match filename | Ensure id equals filename without .json |
| Short descriptions | Min 10 chars title, 20 chars description |
best_practices has < 2 items | Add at least 2 practices |
related_knowledge empty | Add at least 1 .json filename |
Missing best_practices/anti_patterns | Add both mandatory lists with at least 2 items each |
patterns is object with complete entries and best_practices/anti_patterns are provided.verify_structures.py before committing.After creating or updating knowledge files, run:
91. python scripts/build_knowledge_crossref.py
92. python scripts/validation/verify_structures.py
Then run repo-sync skill to validate artifact consistency.
{directories.XXX} path variables — NEVER hardcode directory paths. See {directories.config}/settings.json for the full mapping.best-practices.json).schemas/knowledge-file.schema.json.{directories.knowledge}/stack-capabilities.json{directories.knowledge}/best-practices.json{directories.knowledge}/knowledge-cross-reference.jsonschemas/knowledge-file.schema.jsonThis skill should be used when strict adherence to the defined process is required.