From 19f9330073ed8cbacab748d3e0d56ecd96e1aaa5 Mon Sep 17 00:00:00 2001 From: benjdlambert Date: Tue, 19 May 2026 14:14:30 +0200 Subject: [PATCH] docs: document source-location annotation for skill/rule content Signed-off-by: benjdlambert --- .../catalog-model/src/kinds/AiResourceEntityV1alpha1.ts | 7 +++++++ plugins/catalog-backend-module-ai-model/README.md | 5 +++++ 2 files changed, 12 insertions(+) diff --git a/packages/catalog-model/src/kinds/AiResourceEntityV1alpha1.ts b/packages/catalog-model/src/kinds/AiResourceEntityV1alpha1.ts index 8ee9374a45..f73c7a1682 100644 --- a/packages/catalog-model/src/kinds/AiResourceEntityV1alpha1.ts +++ b/packages/catalog-model/src/kinds/AiResourceEntityV1alpha1.ts @@ -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 { diff --git a/plugins/catalog-backend-module-ai-model/README.md b/plugins/catalog-backend-module-ai-model/README.md index 907c074c83..7b85733ffe 100644 --- a/plugins/catalog-backend-module-ai-model/README.md +++ b/plugins/catalog-backend-module-ai-model/README.md @@ -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.