@forwardimpact/schema 0.8.2 → 0.9.0

package/examples/tracks/platform.yaml

@@ -28,8 +28,11 @@ assessmentWeights:
 # Agent-specific content
 agent:
   identity: |
-    You are a Platform {roleTitle} agent. Your primary focus is 
+    You are a Platform {roleTitle} agent. Your primary focus is
     building self-service capabilities that enable other engineers.
+    You treat checklists the way surgeons and pilots do—not as a
+    crutch, but as a discipline that catches the errors expertise
+    alone cannot prevent.
   priority: |
     Developer experience is paramount. You design golden paths, maintain 
     backward compatibility, and document everything. Code quality and 

package/examples/tracks/sre.yaml

@@ -27,8 +27,11 @@ assessmentWeights:
 # Agent-specific content
 agent:
   identity: |
-    You are an SRE {roleTitle} agent. Your primary focus is 
-    system reliability, observability, and incident response.
+    You are an SRE {roleTitle} agent. Your primary focus is
+    system reliability, observability, and incident response. You
+    treat checklists the way surgeons and pilots do—not as a crutch,
+    but as a discipline that catches the errors expertise alone
+    cannot prevent.
   priority: |
     Reliability is non-negotiable. You instrument everything, design for 
     graceful degradation, and maintain error budgets. Every change 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forwardimpact/schema",
-  "version": "0.8.2",
+  "version": "0.9.0",
   "description": "Schema definitions and data loading for skills, behaviours, and role frameworks",
   "license": "Apache-2.0",
   "repository": {

package/schema/json/capability.schema.json

@@ -89,14 +89,22 @@
           "$ref": "#/$defs/skillAgentSection",
           "description": "Agent-specific content for the skill"
         },
-        "implementationReference": {
-          "type": "string",
-          "description": "Implementation patterns and code examples in markdown format (shared by human and agent)"
-        },
         "toolReferences": {
           "type": "array",
           "description": "Required tools for this skill",
           "items": { "$ref": "#/$defs/toolReference" }
+        },
+        "instructions": {
+          "type": "string",
+          "description": "Step-by-step workflow guidance for the main SKILL.md body"
+        },
+        "installScript": {
+          "type": "string",
+          "description": "Shell commands for environment setup, exported to scripts/install.sh"
+        },
+        "implementationReference": {
+          "type": "string",
+          "description": "Code examples and detailed reference material, exported to references/REFERENCE.md"
         }
       },
       "additionalProperties": false

package/schema/rdf/capability.ttl

@@ -77,9 +77,21 @@ fit:levelDescriptions a rdf:Property ;
     rdfs:comment "Description of expectations at each level"@en ;
     rdfs:range fit:LevelDescriptions .
 
+fit:instructions a rdf:Property ;
+    rdfs:label "instructions"@en ;
+    rdfs:comment "Step-by-step workflow guidance for the main SKILL.md body"@en ;
+    rdfs:domain fit:Skill ;
+    rdfs:range xsd:string .
+
+fit:installScript a rdf:Property ;
+    rdfs:label "installScript"@en ;
+    rdfs:comment "Shell commands for environment setup, exported to scripts/install.sh"@en ;
+    rdfs:domain fit:Skill ;
+    rdfs:range xsd:string .
+
 fit:implementationReference a rdf:Property ;
     rdfs:label "implementationReference"@en ;
-    rdfs:comment "Implementation patterns and code examples in markdown format"@en ;
+    rdfs:comment "Code examples and detailed reference material, exported to references/REFERENCE.md"@en ;
     rdfs:domain fit:Skill ;
     rdfs:range xsd:string .
 
@@ -277,18 +289,32 @@ fit:SkillShape a sh:NodeShape ;
         sh:name "agent" ;
         sh:description "Agent-specific content for the skill" ;
     ] ;
-    sh:property [
-        sh:path fit:implementationReference ;
-        sh:datatype xsd:string ;
-        sh:maxCount 1 ;
-        sh:name "implementationReference" ;
-        sh:description "Implementation patterns and code examples in markdown format" ;
-    ] ;
     sh:property [
         sh:path fit:toolReferences ;
         sh:node fit:ToolReferenceShape ;
         sh:name "toolReferences" ;
         sh:description "Required tools for this skill" ;
+    ] ;
+    sh:property [
+        sh:path fit:instructions ;
+        sh:datatype xsd:string ;
+        sh:maxCount 1 ;
+        sh:name "instructions" ;
+        sh:description "Step-by-step workflow guidance for the main SKILL.md body" ;
+    ] ;
+    sh:property [
+        sh:path fit:installScript ;
+        sh:datatype xsd:string ;
+        sh:maxCount 1 ;
+        sh:name "installScript" ;
+        sh:description "Shell commands for environment setup, exported to scripts/install.sh" ;
+    ] ;
+    sh:property [
+        sh:path fit:implementationReference ;
+        sh:datatype xsd:string ;
+        sh:maxCount 1 ;
+        sh:name "implementationReference" ;
+        sh:description "Code examples and detailed reference material, exported to references/REFERENCE.md" ;
     ] .
 
 # -----------------------------------------------------------------------------

package/src/loader.js

@@ -90,6 +90,8 @@ async function loadSkillsFromCapabilities(capabilitiesDir) {
           isHumanOnly,
           human,
           agent,
+          instructions,
+          installScript,
           implementationReference,
           toolReferences,
         } = skill;
@@ -103,6 +105,9 @@ async function loadSkillsFromCapabilities(capabilitiesDir) {
           ...(isHumanOnly && { isHumanOnly }),
           // Preserve agent section for agent generation
           ...(agent && { agent }),
+          // Include agent skill content fields
+          ...(instructions && { instructions }),
+          ...(installScript && { installScript }),
           // Include implementation reference and tool references (shared by human and agent)
           ...(implementationReference && { implementationReference }),
           ...(toolReferences && { toolReferences }),

package/src/validation.js

@@ -307,6 +307,50 @@ function validateSkill(skill, index, requiredStageIds = []) {
     );
   }
 
+  // Validate instructions if present (optional string)
+  if (
+    skill.instructions !== undefined &&
+    typeof skill.instructions !== "string"
+  ) {
+    errors.push(
+      createError(
+        "INVALID_VALUE",
+        "Skill instructions must be a string",
+        `${path}.instructions`,
+        skill.instructions,
+      ),
+    );
+  }
+
+  // Validate installScript if present (optional string)
+  if (
+    skill.installScript !== undefined &&
+    typeof skill.installScript !== "string"
+  ) {
+    errors.push(
+      createError(
+        "INVALID_VALUE",
+        "Skill installScript must be a string",
+        `${path}.installScript`,
+        skill.installScript,
+      ),
+    );
+  }
+
+  // Error if implementationReference still contains <onboarding_steps> tags (migration aid)
+  if (
+    typeof skill.implementationReference === "string" &&
+    skill.implementationReference.includes("<onboarding_steps>")
+  ) {
+    errors.push(
+      createError(
+        "INVALID_FIELD",
+        "Skill implementationReference contains <onboarding_steps> tags. Extract install commands to skill.installScript instead.",
+        `${path}.implementationReference`,
+      ),
+    );
+  }
+
   // Validate toolReferences array if present
   if (skill.toolReferences !== undefined) {
     if (!Array.isArray(skill.toolReferences)) {