context-engineering/examples/enrich-openapi-context-annotations.yml at main · naftiko/context-engineering · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
# yaml-language-server: $schema=../../../capabilities/naftiko-schema.json
---
naftiko: "0.5"

info:
  label: "Enrich OpenAPI Context Annotations"
  description: "Adds x-context annotations to OpenAPI operations — when to call, what it returns, prerequisites, side effects, and related operations — the metadata AI needs that humans infer from documentation."
  tags:
    - context-engineering
    - enrich
    - openapi
    - annotations
    - context
  created: "2026-03-19"
  modified: "2026-03-19"

capability:
  exposes:
    - type: "mcp"
      namespace: "context-engineering"
      tools:
        - name: "enrich-openapi-context-annotations"
          description: "Add x-context annotations to OpenAPI operations — when to call, prerequisites, side effects, related operations, expected latency, idempotency. Produces an overlay with context metadata agents need."
          inputParameters:
            - name: spec_url
              in: body
              type: string
              description: "URL or file path to the OpenAPI specification"
            - name: annotation_depth
              in: body
              type: string
              description: "Annotation depth: 'minimal' (when-to-call only), 'standard' (+ prerequisites, side effects), 'full' (+ related ops, latency, idempotency). Default: standard"
          steps:
            - name: fetch-spec
              type: call
              call: "github.get-file-contents"
              with:
                owner: "{{owner}}"
                repo: "{{repo}}"
                file_path: "{{spec_url}}"

            - name: analyze-operations
              type: transform
              description: "Analyze each operation for implicit context — HTTP method semantics, path patterns, parameter types, response codes — to infer annotations."
              outputParameters:
                - name: "analyzed_operations"
                  type: "array"

            - name: generate-annotations
              type: transform
              description: "Generate x-context annotations: x-context-when (when to call), x-context-prerequisites (what must happen first), x-context-side-effects (what changes), x-context-related (related operations), x-context-idempotent (safe to retry)."
              outputParameters:
                - name: "annotations"
                  type: "array"

            - name: produce-overlay
              type: transform
              description: "Produce OpenAPI Overlay document with x-context annotations for all operations."
              outputParameters:
                - name: "overlay"
                  type: "object"
                - name: "operations_annotated"
                  type: "number"

    - type: "http"
      path: "/enrich/context-annotations"
      method: "POST"
      description: "REST endpoint to trigger context annotation enrichment"

    - type: "agent-skill"
      namespace: "context-engineering"
      skill:
        name: "enrich-openapi-context-annotations"
        description: "Add x-context annotations to OpenAPI operations for agent consumption"

  consumes:
    - import: "shared/consumes-github.yml"
      as: "github"