Support Agent Skills as ORD capability type

CHANGELOG.md

@@ -10,6 +10,15 @@ For a roadmap including expected timeline, please refer to [ROADMAP.md](./ROADMA
 
 ## [unreleased]
 
+### Added
+
+- Added capability type `ord:agent-skill:v1` for describing discrete, reusable agent skills that can be invoked by orchestrator agents or other systems.
+- Added capability definition type `ord:agent-skill-zip:v1` for ZIP archive definitions of agent skills (mediaType `application/zip`).
+
+### Changed
+
+- Clarified that `ord` is a reserved vendor namespace owned by the ORD specification itself, used to register well-known, cross-vendor [Specification IDs](docs/spec-v1/index.md#specification-id).
+
 ## [1.14.2]
 
 ### Added

docs/spec-v1/concepts/ai-agents-and-protocols.md

@@ -231,8 +231,64 @@ Given the rapidly evolving AI ecosystem, ORD takes a conservative approach to ad
     This allows for experimentation without committing to a stable schema.
 -   **Tags:** Free-form tags for folksonomy-style categorization (e.g., `["finance", "billing", "ai-agent"]`).
 
-### Examples
+### Agent Skills as Capabilities
 
-Example implementations are available in the ORD specification repository:
-- `examples/documents/document-agents.json` — Complete ORD document with agent definitions
-- `examples/definitions/DisputeResolutionAgentcard.json` — A2A Agent Card example
+[Agent skills](https://agentskills.io/home) are discrete, reusable capabilities that agents can perform—packaged as folders of instructions, scripts, and resources.
+In ORD, these are modeled using the **[Capability](../interfaces/Document#capability)** resource type with `type: "ord:agent-skill:v1"`.
+
+This enables:
+- **Discovery:** Agents can discover and load skills on-demand through the catalog
+- **Reusability:** Skills can be shared across multiple agents and systems
+- **Dependency Management:** Agents can declare dependencies on external skills
+
+**Example agent skill:**
+
+```json
+{
+  "capabilities": [
+    {
+      "ordId": "sap.foo:capability:disputeSummarization:v1",
+      "title": "Dispute Summarization Skill",
+      "shortDescription": "Summarizes dispute cases and their resolution history",
+      "version": "1.0.0",
+      "type": "ord:agent-skill:v1",
+      "definitions": [
+        {
+          "type": "ord:agent-skill-zip:v1",
+          "mediaType": "application/zip",
+          "url": "/capabilities/disputeSummarization/skill.zip",
+          "accessStrategies": [{ "type": "open" }]
+        }
+      ]
+    }
+  ]
+}
+```
+
+**Consuming agent skills:**
+
+Agents can depend on external skills through Integration Dependency aspects:
+
+```json
+{
+  "integrationDependencies": [
+    {
+      "ordId": "sap.foo:integrationDependency:DisputeCaseManagement:v1",
+      "aspects": [
+        {
+          "title": "Document Processing Skill Access",
+          "description": "Uses an external agent skill for processing documents",
+          "mandatory": false,
+          "capabilities": [
+            { "ordId": "sap.bar:capability:documentProcessing:v1" }
+          ]
+        }
+      ]
+    }
+  ]
+}
+```
+
+## Example
+
+A complete example with agent and capability definitions is available at [document-agents.json](../examples/document-agents).

docs/spec-v1/index.md

@@ -694,6 +694,8 @@ A vendor namespace MUST be constructed according to the following rules:
 
 **Examples**: For SAP, we chose and registered `sap`.
 
+> ℹ The `ord` vendor namespace is reserved by the ORD specification itself and is used to register well-known, cross-vendor [Specification IDs](#specification-id) (such as capability types and definition formats) that are part of the core standard. Only the ORD specification project may register identifiers under it.
+
 > 🚧 There is currently no global namespace registry where we can ensure that there are no conflicts across different vendors.
 
 #### System Namespace

examples/documents/document-agents.json

@@ -106,6 +106,28 @@
       ]
     }
   ],
+  "capabilities": [
+    {
+      "ordId": "sap.foo:capability:disputeSummarization:v1",
+      "title": "Dispute Summarization Skill",
+      "shortDescription": "Summarizes dispute cases and their resolution history",
+      "description": "An agent skill that generates concise summaries of financial dispute cases, including key facts, involved parties, and resolution status.",
+      "version": "1.0.0",
+      "lastUpdate": "2022-12-19T15:47:04+00:00",
+      "visibility": "public",
+      "releaseStatus": "active",
+      "partOfPackage": "sap.foo:package:ord-reference-app:v1",
+      "type": "ord:agent-skill:v1",
+      "definitions": [
+        {
+          "type": "ord:agent-skill-zip:v1",
+          "mediaType": "application/zip",
+          "url": "/capabilities/disputeSummarization/skill.zip",
+          "accessStrategies": [{ "type": "open" }]
+        }
+      ]
+    }
+  ],
   "integrationDependencies": [
     {
       "ordId": "sap.foo:integrationDependency:DisputeCaseManagement:v1",
@@ -127,6 +149,16 @@
               "ordId": "sap.bar:apiResource:DisputeResolutionAPI:v1"
             }
           ]
+        },
+        {
+          "title": "Document Processing Skill Access",
+          "description": "Optionally uses an external agent skill for processing and extracting information from supporting documents (e.g. contracts, invoices).",
+          "mandatory": false,
+          "capabilities": [
+            {
+              "ordId": "sap.bar:capability:documentProcessing:v1"
+            }
+          ]
         }
       ]
     }

spec/v1/Document.schema.yaml

@@ -3034,6 +3034,14 @@ definitions:
             pattern: ^([a-z0-9]+(?:[.][a-z0-9]+)*):([a-zA-Z0-9._\-]+):(v0|v[1-9][0-9]*)$
             description: |-
               Any valid [Specification ID](../index.md#specification-id).
+          - const: "ord:agent-skill:v1"
+            x-introduced-in-version: "1.14.3"
+            description: |-
+              An [agent skill](https://agentskills.io/home) is a discrete, reusable capability that an agent can perform.
+              Agent skills can be invoked by orchestrator agents or other systems and represent
+              a well-defined task or function that the agent is capable of executing.
+
+              For the capability definitions: `type` SHOULD be set to `ord:agent-skill-zip:v1`.
           - const: "sap.mdo:mdi-capability:v1"
             description: |-
               Capability for SAP Master Data Integration (MDI).
@@ -3044,7 +3052,7 @@ definitions:
               If chosen, `customType` MUST be provided.
             # Deprecate this in future?
         examples:
-          - custom
+          - "ord:agent-skill:v1"
 
       customType:
         <<: *customType
@@ -3207,6 +3215,14 @@ definitions:
             pattern: ^([a-z0-9]+(?:[.][a-z0-9]+)*):([a-zA-Z0-9._\-]+):(v0|v[1-9][0-9]*)$
             description: |-
               Any valid [Specification ID](../index.md#specification-id).
+          - const: "ord:agent-skill-zip:v1"
+            x-introduced-in-version: "1.14.3"
+            description: |-
+              A ZIP archive containing the definition of an agent skill, including all relevant
+              assets such as configuration and schema files.
+
+              The `mediaType` MUST be set to `application/zip`.
+              The capability `type` SHOULD be set to `ord:agent-skill:v1`.
           - const: "sap.mdo:mdi-capability-definition:v1"
             description: |-
               Specification for describing master data integration capabilities for Master Data Orchestration (MDO).

src/generated/spec/v1/types/Document.ts

@@ -1971,7 +1971,7 @@ export interface Capability {
   /**
    * Type of the Capability
    */
-  type: (string | "sap.mdo:mdi-capability:v1" | "custom") & string;
+  type: (string | "ord:agent-skill:v1" | "sap.mdo:mdi-capability:v1" | "custom") & string;
   /**
    * If the fixed `type` enum values need to be extended, an arbitrary `customType` can be provided.
    *
@@ -2217,7 +2217,7 @@ export interface CapabilityDefinition {
   /**
    * Type of the capability resource definition
    */
-  type: (string | "sap.mdo:mdi-capability-definition:v1" | "custom") & string;
+  type: (string | "ord:agent-skill-zip:v1" | "sap.mdo:mdi-capability-definition:v1" | "custom") & string;
   /**
    * If the fixed `type` enum values need to be extended, an arbitrary `customType` can be provided.
    *