@skill-graph/cli 0.5.6

package/schemas/manifest.schema.json

@@ -0,0 +1,811 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://skillgraph.dev/schemas/manifest.schema.json",
+  "title": "Skill Graph Manifest",
+  "type": "object",
+  "required": [
+    "schema_version",
+    "generated_at",
+    "summary",
+    "skills"
+  ],
+  "additionalProperties": false,
+  "properties": {
+    "schema_version": {
+      "oneOf": [
+        {
+          "type": "integer",
+          "const": 4
+        },
+        {
+          "type": "string",
+          "const": "4"
+        }
+      ],
+      "description": "Major contract shape version. Integer for v4+; string '4' tolerated for back-compat with hand-rolled YAML. Bumps when shape changes break consumers."
+    },
+    "generated_at": {
+      "type": "string",
+      "format": "date-time"
+    },
+    "workspace": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Optional multi-root workspace metadata. Emitted when `.skill-graph/config.json` declares workspace projects. Consumers filter generated `skills[].project` ownership and authored `skills[].workspace_tags` relevance against this block.",
+      "properties": {
+        "projects": {
+          "type": "object",
+          "additionalProperties": {
+            "type": "object",
+            "additionalProperties": false,
+            "properties": {
+              "semantic_tags": {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                }
+              }
+            }
+          }
+        },
+        "skill_roots": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        }
+      }
+    },
+    "summary": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "total_skills"
+      ],
+      "properties": {
+        "total_skills": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "by_type": {
+          "type": "object",
+          "additionalProperties": {
+            "type": "integer",
+            "minimum": 0
+          }
+        },
+        "by_category": {
+          "type": "object",
+          "additionalProperties": {
+            "type": "integer",
+            "minimum": 0
+          }
+        },
+        "by_scope": {
+          "type": "object",
+          "additionalProperties": {
+            "type": "integer",
+            "minimum": 0
+          }
+        },
+        "by_stability": {
+          "type": "object",
+          "additionalProperties": {
+            "type": "integer",
+            "minimum": 0
+          }
+        },
+        "by_project": {
+          "type": "object",
+          "additionalProperties": {
+            "type": "integer",
+            "minimum": 0
+          }
+        }
+      }
+    },
+    "skills": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": [
+          "id",
+          "path",
+          "name",
+          "description",
+          "version",
+          "type",
+          "category",
+          "scope",
+          "owner"
+        ],
+        "properties": {
+          "id": {
+            "type": "string"
+          },
+          "path": {
+            "type": "string"
+          },
+          "project": {
+            "type": "string",
+            "description": "Literal handle of the project this skill was loaded from. Absent for skills loaded from a shared root without a project owner."
+          },
+          "name": {
+            "type": "string"
+          },
+          "urn": {
+            "type": "string",
+            "pattern": "^urn:skill:[a-z0-9][a-z0-9-]*:[a-z0-9][a-z0-9-/:]*$",
+            "description": "Optional globally-unique persistent identifier from the authored frontmatter (RFC 8141). Pass-through — generator does not synthesise this."
+          },
+          "description": {
+            "type": "string"
+          },
+          "version": {
+            "type": "string"
+          },
+          "type": {
+            "type": "string",
+            "enum": [
+              "capability",
+              "workflow",
+              "router",
+              "overlay"
+            ]
+          },
+          "archetype": {
+            "type": "string",
+            "enum": [
+              "capability",
+              "workflow",
+              "router",
+              "overlay"
+            ],
+            "description": "v3.1 preferred alias for `type`. Pass-through from authored frontmatter."
+          },
+          "category": {
+            "type": "string"
+          },
+          "domain": {
+            "type": "string"
+          },
+          "scope": {
+            "type": "string",
+            "enum": [
+              "codebase",
+              "reference",
+              "portable"
+            ]
+          },
+          "owner": {
+            "type": "string"
+          },
+          "stability": {
+            "type": "string",
+            "enum": [
+              "experimental",
+              "stable",
+              "frozen",
+              "deprecated"
+            ]
+          },
+          "superseded_by": {
+            "type": "string",
+            "description": "Name of the skill that replaces this one. Populated when authored `stability: deprecated`. Consumers use this to follow deprecation chains automatically."
+          },
+          "extends": {
+            "type": "string"
+          },
+          "workspace_tags": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          },
+          "activation": {
+            "type": "object",
+            "additionalProperties": false,
+            "properties": {
+              "triggers": {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                }
+              },
+              "keywords": {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                }
+              },
+              "paths": {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                }
+              },
+              "examples": {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                }
+              },
+              "anti_examples": {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                }
+              }
+            }
+          },
+          "relations": {
+            "type": "object",
+            "additionalProperties": false,
+            "properties": {
+              "adjacent": {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                }
+              },
+              "related": {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                }
+              },
+              "broader": {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                }
+              },
+              "narrower": {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                }
+              },
+              "boundary": {
+                "type": "array",
+                "items": {
+                  "oneOf": [
+                    {
+                      "type": "string"
+                    },
+                    {
+                      "type": "object",
+                      "additionalProperties": false,
+                      "required": [
+                        "skill"
+                      ],
+                      "properties": {
+                        "skill": {
+                          "type": "string"
+                        },
+                        "reason": {
+                          "type": "string"
+                        }
+                      }
+                    }
+                  ]
+                }
+              },
+              "disjoint_with": {
+                "type": "array",
+                "items": {
+                  "oneOf": [
+                    {
+                      "type": "string"
+                    },
+                    {
+                      "type": "object",
+                      "additionalProperties": false,
+                      "required": [
+                        "skill"
+                      ],
+                      "properties": {
+                        "skill": {
+                          "type": "string"
+                        },
+                        "reason": {
+                          "type": "string"
+                        }
+                      }
+                    }
+                  ]
+                }
+              },
+              "verify_with": {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                }
+              },
+              "depends_on": {
+                "type": "array",
+                "items": {
+                  "oneOf": [
+                    {
+                      "type": "string"
+                    },
+                    {
+                      "type": "object",
+                      "additionalProperties": false,
+                      "required": [
+                        "skill"
+                      ],
+                      "properties": {
+                        "skill": {
+                          "type": "string"
+                        },
+                        "min_version": {
+                          "type": "string",
+                          "description": "Semver range for the minimum required version. Accepts bare semver, caret, tilde, comparator, or AND-joined ranges.",
+                          "pattern": "^(\\^|~|>=|<=|>|<|=)?[0-9]+\\.[0-9]+\\.[0-9]+(-[a-zA-Z0-9.-]+)?( +(\\^|~|>=|<=|>|<|=)?[0-9]+\\.[0-9]+\\.[0-9]+(-[a-zA-Z0-9.-]+)?)*$"
+                        }
+                      }
+                    }
+                  ]
+                }
+              }
+            }
+          },
+          "grounding": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": [
+              "domain_object",
+              "grounding_mode",
+              "truth_sources",
+              "failure_modes",
+              "evidence_priority"
+            ],
+            "properties": {
+              "domain_object": {
+                "type": "string"
+              },
+              "subject": {
+                "type": "string",
+                "description": "v3.1 preferred alias for `domain_object`. Pass-through."
+              },
+              "grounding_mode": {
+                "type": "string",
+                "enum": [
+                  "repo_specific",
+                  "universal",
+                  "hybrid"
+                ]
+              },
+              "claim_scope": {
+                "type": "string",
+                "enum": [
+                  "repo_specific",
+                  "universal",
+                  "hybrid"
+                ],
+                "description": "v3.1 preferred alias for `grounding_mode`. Pass-through."
+              },
+              "truth_sources": {
+                "type": "array",
+                "items": {
+                  "oneOf": [
+                    {
+                      "type": "string"
+                    },
+                    {
+                      "type": "object",
+                      "additionalProperties": false,
+                      "required": [
+                        "path"
+                      ],
+                      "properties": {
+                        "path": {
+                          "type": "string",
+                          "minLength": 1
+                        },
+                        "line_range": {
+                          "type": "object",
+                          "additionalProperties": false,
+                          "required": [
+                            "start"
+                          ],
+                          "properties": {
+                            "start": {
+                              "type": "integer",
+                              "minimum": 1
+                            },
+                            "end": {
+                              "type": "integer",
+                              "minimum": 1
+                            }
+                          }
+                        },
+                        "anchor": {
+                          "type": "string"
+                        },
+                        "note": {
+                          "type": "string"
+                        }
+                      }
+                    }
+                  ]
+                }
+              },
+              "failure_modes": {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                }
+              },
+              "evidence_priority": {
+                "type": "string",
+                "enum": [
+                  "repo_code_first",
+                  "general_knowledge_first",
+                  "equal"
+                ]
+              }
+            }
+          },
+          "routing_bundles": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          },
+          "license": {
+            "type": "string"
+          },
+          "compatibility": {
+            "type": "object",
+            "additionalProperties": false,
+            "properties": {
+              "runtimes": {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                }
+              },
+              "agent_runtimes": {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                },
+                "description": "v3.1 preferred alias for `runtimes`. Pass-through."
+              },
+              "node": {
+                "type": "string"
+              },
+              "node_version": {
+                "type": "string",
+                "description": "v3.1 preferred alias for `node`. Pass-through."
+              },
+              "notes": {
+                "type": "string",
+                "description": "Free-text additional compatibility notes. Pass-through from SKILL.md. No protocol length cap."
+              }
+            }
+          },
+          "allowed-tools": {
+            "type": "string"
+          },
+          "allowed_tools": {
+            "type": "string",
+            "description": "v3.1 preferred snake_case alias for `allowed-tools`. Pass-through."
+          },
+          "portability": {
+            "type": "object",
+            "additionalProperties": false,
+            "properties": {
+              "readiness": {
+                "type": "string",
+                "enum": [
+                  "declared",
+                  "scripted",
+                  "verified"
+                ]
+              },
+              "targets": {
+                "type": "array",
+                "items": {
+                  "type": "string",
+                  "enum": [
+                    "skill-md"
+                  ]
+                }
+              },
+              "export_targets": {
+                "type": "array",
+                "description": "v3.1 preferred alias for `targets`. Pass-through.",
+                "items": {
+                  "type": "string",
+                  "enum": [
+                    "skill-md"
+                  ]
+                }
+              }
+            }
+          },
+          "health": {
+            "type": "object",
+            "additionalProperties": false,
+            "properties": {
+              "eval_artifacts": {
+                "type": "string"
+              },
+              "eval_state": {
+                "type": "string"
+              },
+              "routing_eval": {
+                "type": "string"
+              },
+              "eval_last_run": {
+                "type": "object",
+                "additionalProperties": false,
+                "required": [
+                  "at",
+                  "status"
+                ],
+                "properties": {
+                  "at": {
+                    "type": "string",
+                    "format": "date-time"
+                  },
+                  "status": {
+                    "type": "string",
+                    "enum": [
+                      "pass",
+                      "fail",
+                      "mixed"
+                    ]
+                  },
+                  "runner": {
+                    "type": "string"
+                  },
+                  "model": {
+                    "type": "string"
+                  },
+                  "receipt": {
+                    "type": "string"
+                  },
+                  "receipt_hash": {
+                    "type": "string",
+                    "pattern": "^[a-f0-9]{64}$"
+                  }
+                }
+              },
+              "eval": {
+                "type": "object",
+                "additionalProperties": false,
+                "description": "v3.1 preferred nested form for the eval-health triple. Pass-through from authored frontmatter.",
+                "properties": {
+                  "artifacts": {
+                    "type": "string"
+                  },
+                  "content_state": {
+                    "type": "string"
+                  },
+                  "routing_coverage": {
+                    "type": "string"
+                  },
+                  "comprehension_state": {
+                    "type": "string",
+                    "enum": [
+                      "absent",
+                      "present"
+                    ],
+                    "description": "v3.1 preferred nested alias for top-level `comprehension_state`. Pass-through."
+                  }
+                }
+              },
+              "freshness": {
+                "type": "string",
+                "format": "date"
+              },
+              "reviewed_at": {
+                "type": "string",
+                "format": "date",
+                "description": "v3.1 preferred alias for `freshness`. Pass-through."
+              },
+              "drift_check": {
+                "type": "object",
+                "additionalProperties": false,
+                "required": [
+                  "last_verified"
+                ],
+                "properties": {
+                  "last_verified": {
+                    "type": "string",
+                    "format": "date"
+                  },
+                  "verified_at": {
+                    "type": "string",
+                    "format": "date",
+                    "description": "v3.1 preferred alias for `last_verified`. Pass-through."
+                  },
+                  "truth_source_hashes": {
+                    "type": "object",
+                    "additionalProperties": {
+                      "type": "string",
+                      "pattern": "^[a-f0-9]{64}$"
+                    }
+                  }
+                }
+              },
+              "lifecycle": {
+                "type": "object",
+                "additionalProperties": false,
+                "properties": {
+                  "stale_after_days": {
+                    "type": "integer",
+                    "minimum": 1
+                  },
+                  "review_cadence": {
+                    "type": "string",
+                    "enum": [
+                      "per-commit",
+                      "weekly",
+                      "quarterly",
+                      "on-truth-source-change"
+                    ]
+                  }
+                }
+              },
+              "runtime_telemetry": {
+                "type": "object",
+                "additionalProperties": false,
+                "required": [
+                  "feedback_source"
+                ],
+                "properties": {
+                  "feedback_source": {
+                    "type": "string"
+                  },
+                  "last_updated": {
+                    "type": "string",
+                    "format": "date"
+                  },
+                  "metrics": {
+                    "type": "object",
+                    "additionalProperties": false,
+                    "properties": {
+                      "sample_size": {
+                        "type": "integer",
+                        "minimum": 0
+                      },
+                      "success_rate": {
+                        "type": "number",
+                        "minimum": 0,
+                        "maximum": 1
+                      }
+                    }
+                  }
+                }
+              },
+              "has_grounding": {
+                "type": "boolean"
+              },
+              "has_relations": {
+                "type": "boolean"
+              },
+              "drift_detected": {
+                "type": "boolean",
+                "description": "True when any normalized `grounding.truth_sources` key has a current SHA-256 hash that differs from the stored `drift_check.truth_source_hashes` value. Computed by the manifest generator when hashes are available."
+              },
+              "comprehension_state": {
+                "type": "string",
+                "enum": [
+                  "absent",
+                  "present"
+                ],
+                "description": "Does this skill carry a comprehension eval (typically `evals/comprehension.json`) and a `concept` block authored for the 7-dimension comprehension grader? `absent` (no comprehension grading), `present` (comprehension evals exist; the `concept` block is required by the allOf rule). Optional in v3 — omitted means `absent`. Independent of `routing_eval` (router-level) and `eval_state` (content-level). The nested `eval.comprehension_state` is the v3.1 preferred alias."
+              },
+              "last_audited": {
+                "type": "string",
+                "format": "date",
+                "description": "ISO date (YYYY-MM-DD) the `audit` command last ran against this skill. Written by `scripts/skill/skill-audit.js`. Pass-through from authored frontmatter (v6 Health Block)."
+              },
+              "last_changed": {
+                "type": "string",
+                "format": "date",
+                "description": "ISO date (YYYY-MM-DD) the SKILL.md body or frontmatter was last edited. Written automatically by `improve` operations. Pass-through from authored frontmatter (v6 Health Block)."
+              },
+              "audit_verdict": {
+                "type": "string",
+                "enum": [
+                  "PASS",
+                  "PASS_WITH_FIXES",
+                  "PARTIAL",
+                  "FAIL",
+                  "UNKNOWN"
+                ],
+                "description": "Aggregate result of the most recent `audit` run. Combines `lint_verdict`, `drift_status`, and (when run with `--graded`) the seven dimension scores. Pass-through from authored frontmatter (v6 Health Block)."
+              },
+              "eval_score": {
+                "type": "number",
+                "minimum": 0,
+                "maximum": 5,
+                "description": "Latest aggregate eval grade on a 0.0–5.0 scale, written by `scripts/skill/evaluate-skill.js`. Pass-through from authored frontmatter (v6 Health Block)."
+              },
+              "eval_failed_ids": {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                },
+                "description": "Eval IDs that failed in the most recent run. Empty array when clean. Pass-through from authored frontmatter (v6 Health Block)."
+              },
+              "lint_verdict": {
+                "type": "string",
+                "enum": [
+                  "PASS",
+                  "FAIL",
+                  "UNKNOWN"
+                ],
+                "description": "Result of the most recent deterministic-lint pass against this skill. `PASS` means zero lint errors; `UNKNOWN` is the initial state. Pass-through from authored frontmatter (v6 Health Block)."
+              },
+              "drift_status": {
+                "type": "string",
+                "enum": [
+                  "OK",
+                  "DRIFT",
+                  "BROKEN",
+                  "STALE",
+                  "NO_BASELINE",
+                  "EXTERNAL_UNHASHED",
+                  "UNKNOWN"
+                ],
+                "description": "Current truth-source drift status. `OK` (live hashes match recorded), `DRIFT` (mismatch), `BROKEN` (truth source missing), `STALE`, `NO_BASELINE`, `EXTERNAL_UNHASHED`, `UNKNOWN`. Pass-through from authored frontmatter (v6 Health Block)."
+              }
+            }
+          },
+          "concept": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": [
+              "definition",
+              "mental_model",
+              "purpose",
+              "boundary",
+              "taxonomy",
+              "analogy",
+              "misconception"
+            ],
+            "properties": {
+              "definition": {
+                "type": "string",
+                "description": "What the concept IS. Primary category + what it does + who uses it. A domain outsider should understand. Author as deeply as the concept requires — there is no protocol length cap. Graded by the comprehension grader's `definition` dimension (weight 1.0)."
+              },
+              "mental_model": {
+                "type": "string",
+                "description": "Primitives and their relationships. Name primitives and the relationships between them. Markdown permitted inside the string. Author with the depth the concept needs — there is no protocol length cap. Graded by the comprehension grader's `mental_model` dimension (weight 1.5)."
+              },
+              "purpose": {
+                "type": "string",
+                "description": "What problem the concept solves and the alternative it replaced. Concrete pain point + prior alternative. No protocol length cap — explain as fully as the concept needs. Graded by the comprehension grader's `purpose` dimension (weight 1.0)."
+              },
+              "boundary": {
+                "type": "string",
+                "description": "Things commonly confused with the concept but that are NOT it. Express each difference as a mechanism (different primitives, different purpose, different scope) - not just different names. No protocol length cap. Graded by the comprehension grader's `boundary` dimension (weight 1.5)."
+              },
+              "taxonomy": {
+                "type": "string",
+                "description": "Nearby concepts with their relationship type (subset / alternative / prerequisite / composition / specialization). Markdown list permitted inside the string. No protocol length cap. Graded by the comprehension grader's `taxonomy` dimension (weight 1.0)."
+              },
+              "analogy": {
+                "type": "string",
+                "description": "Analogy that preserves the core mechanism. Translate for a non-expert without breaking the structural relationship between primitives. No protocol length cap. Graded by the comprehension grader's `analogy` dimension (weight 0.5)."
+              },
+              "misconception": {
+                "type": "string",
+                "description": "The wrong mental model people bring and why it misleads. Authored hint to inoculate the agent against the common error trap. No protocol length cap. Not directly graded; complements `boundary`."
+              }
+            },
+            "description": "Seven-field universal-subject concept teaching block. Read by the comprehension grader (`scripts/skill/evaluate-skill.js --comprehension`) and rendered into the agent context when the skill is loaded. Required when `comprehension_state: present`. No protocol length cap — author each field as deeply as the concept requires. Distinct from `## Philosophy` in the body, which is about *why this skill file exists in this repo*; the `concept` block is about *what the subject is, universally*."
+          }
+        }
+      }
+    }
+  }
+}