docs: document source-location annotation for skill/rule content

Signed-off-by: benjdlambert <ben@blam.sh>
2026-05-19 14:14:30 +02:00
parent a185d7e0f8
commit 19f9330073
2 changed files with 12 additions and 0 deletions
@@ -26,6 +26,13 @@ import ruleJsonSchema from '../schema/kinds/AiResource.v1alpha1.rule.schema.json
 /**
 * Default AiResource entity for types that don't have a structured spec.
 *
+ * @remarks
+ *
+ * The actual content of skills and rules is not stored in the entity spec.
+ * Instead, the source file is referenced via the standard
+ * `backstage.io/source-location` annotation, consistent with how other
+ * Backstage entities reference their source files.
+ *
 * @alpha
 */
 export interface AiResourceEntityV1alpha1Default extends Entity {
@@ -36,5 +36,10 @@ spec:
 The `type` field determines which spec fields are available. Currently supported types:

 - **`skill`** — reusable contextual knowledge for AI coding tools. Supports additional fields: `disciplines`, `categories`, `agents`, `dependsOn`.
+- **`rule`** — governance rules and constraints for AI coding tools. Supports additional fields: `disciplines`, `category` (required), `rationale` (required).

 Any other `type` value is accepted with the base spec fields: `type`, `lifecycle`, `owner`, and optionally `system`.
+
+## Accessing skill and rule content
+
+The actual content of skills and rules is not stored in the entity spec. Instead, the source file is referenced via the standard `backstage.io/source-location` annotation, consistent with how other Backstage entities reference their source files. Entity providers that generate `AiResource` entities from `SKILL.md` or rule files should set this annotation to point to the source file.