context-engineering/examples/profile-api-doc-quality.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
79
# yaml-language-server: $schema=../../../capabilities/naftiko-schema.json
---
naftiko: "0.5"

info:
  label: "Profile API Documentation Quality"
  description: "Assesses API documentation quality for AI consumption — description completeness, example presence, parameter disambiguation, error documentation, and task-oriented framing."
  tags:
    - context-engineering
    - profile
    - documentation
    - quality
  created: "2026-03-19"
  modified: "2026-03-19"

capability:
  exposes:
    - type: "mcp"
      namespace: "context-engineering"
      tools:
        - name: "profile-api-doc-quality"
          description: "Assess API documentation quality for AI consumption — score description completeness, example presence, parameter disambiguation, and task-oriented framing. Produces per-operation scores and prioritized improvement list."
          inputParameters:
            - name: spec_url
              in: body
              type: string
              description: "URL or file path to the OpenAPI specification"
            - name: include_external_docs
              in: body
              type: boolean
              description: "Whether to also assess linked external documentation pages (default: false)"
          steps:
            - name: fetch-spec
              type: call
              call: "github.get-file-contents"
              with:
                owner: "{{owner}}"
                repo: "{{repo}}"
                file_path: "{{spec_url}}"

            - name: score-operations
              type: transform
              description: "Score each operation on: summary presence, description quality, parameter descriptions, enum documentation, error response documentation, example presence."
              outputParameters:
                - name: "operation_scores"
                  type: "array"

            - name: score-disambiguation
              type: transform
              description: "Assess whether similar operations are distinguishable by AI — can an agent tell apart 'get user by ID' from 'get user by email' from descriptions alone?"
              outputParameters:
                - name: "disambiguation_score"
                  type: "number"
                - name: "ambiguous_operations"
                  type: "array"

            - name: prioritize-improvements
              type: transform
              description: "Rank documentation gaps by impact on AI consumption — high-traffic operations with poor docs get highest priority."
              outputParameters:
                - name: "doc_quality_score"
                  type: "number"
                - name: "priority_improvements"
                  type: "array"

    - type: "http"
      path: "/profile/doc-quality"
      method: "POST"
      description: "REST endpoint to trigger API documentation quality assessment"

    - type: "agent-skill"
      namespace: "context-engineering"
      skill:
        name: "profile-api-doc-quality"
        description: "Assess API documentation quality for AI consumption"

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