Making Your APIs More Visible With GitHub and GitBook

naftiko: "0.5"
info:
  label: "GitHub OpenAPI Scanner"
  description: "Scans GitHub organization repositories for OpenAPI and AsyncAPI specification files, building an inventory of every API definition across the org."
capability:
  exposes:
    - type: "mcp"
      namespace: "spec-scanner"
      tools:
        - name: "scan-org-for-specs"
          description: "Scans all repositories in a GitHub organization for OpenAPI and AsyncAPI specification files."
          inputParameters:
            - name: org
              in: query
              type: string
          steps:
            - name: search-openapi
              type: call
              call: "github.search-code"
              with:
                q: "org: filename:openapi"
                per_page: 100
            - name: search-asyncapi
              type: call
              call: "github.search-code"
              with:
                q: "org: filename:asyncapi"
                per_page: 100
        - name: "get-spec-contents"
          description: "Retrieves the raw contents of a discovered spec file from a GitHub repository."
          inputParameters:
            - name: owner
              in: query
              type: string
            - name: repo
              in: query
              type: string
            - name: file_path
              in: query
              type: string
          steps:
            - name: fetch-file
              type: call
              call: "github.get-file-contents"
              with:
                owner: ""
                repo: ""
                file_path: ""
  consumes:
    - import: "consumes-github.yml"
      as: "github"

naftiko: "0.5"
info:
  label: "GitHub-to-GitBook Spec Publisher"
  description: "Discovers OpenAPI specifications in GitHub repositories and publishes them as structured documentation in GitBook spaces."
capability:
  exposes:
    - type: "mcp"
      namespace: "spec-publisher"
      tools:
        - name: "publish-spec-to-gitbook"
          description: "Fetches an OpenAPI spec from a GitHub repo and creates or updates a GitBook space with the spec content."
          inputParameters:
            - name: owner
              in: query
              type: string
            - name: repo
              in: query
              type: string
            - name: spec_path
              in: query
              type: string
            - name: gitbook_orgId
              in: query
              type: string
            - name: space_title
              in: query
              type: string
          steps:
            - name: fetch-spec
              type: call
              call: "github.get-file-contents"
              with:
                owner: ""
                repo: ""
                file_path: ""
            - name: create-space
              type: call
              call: "gitbook.create-space"
              with:
                orgId: ""
                title: ""
                visibility: "public"
        - name: "upload-openapi-to-space"
          description: "Uploads an OpenAPI specification to GitBook's native spec viewer within an existing space."
          inputParameters:
            - name: spaceId
              in: query
              type: string
            - name: spec_url
              in: query
              type: string
          steps:
            - name: upload-spec
              type: call
              call: "gitbook.upload-openapi"
              with:
                spaceId: ""
                url: ""
                source: "url"
  consumes:
    - import: "consumes-github.yml"
      as: "github"
    - import: "consumes-gitbook.yml"
      as: "gitbook"

naftiko: "0.5"
info:
  label: "GitBook-to-GitHub Spec Centralizer"
  description: "Extracts API documentation and specifications from GitBook spaces and commits them to a centralized GitHub repository."
capability:
  exposes:
    - type: "mcp"
      namespace: "spec-centralizer"
      tools:
        - name: "extract-specs-from-gitbook"
          description: "Lists all GitBook spaces and identifies those containing API documentation."
          inputParameters:
            - name: gitbook_orgId
              in: query
              type: string
          steps:
            - name: list-spaces
              type: call
              call: "gitbook.list-spaces"
              with:
                orgId: ""
        - name: "commit-spec-to-github"
          description: "Commits extracted spec content to a centralized GitHub repository."
          inputParameters:
            - name: owner
              in: query
              type: string
            - name: repo
              in: query
              type: string
            - name: file_path
              in: query
              type: string
            - name: content
              in: query
              type: string
            - name: commit_message
              in: query
              type: string
          steps:
            - name: push-file
              type: call
              call: "github.push-file"
              with:
                owner: ""
                repo: ""
                file_path: ""
                content: "<!-- Post hero with background image -->
<section class="section _204-164" style="position:relative; overflow:hidden;">
  
  <div style="position:absolute; top:0; left:0; width:100%; height:100%; z-index:0;">
    <img src="/assets/img/blog/five-problems-context-engineers-face-right-now.png" alt="" style="width:100%; height:100%; object-fit:cover; opacity:0.75;"/>
  </div>
  
  <div style="position:absolute; top:0; left:0; width:100%; height:100%; background:linear-gradient(to bottom, rgba(10,12,30,0.6), rgba(10,12,30,0.95)); z-index:1;"></div>
  <div class="container" style="position:relative; z-index:2;">
    <div class="gap-24 max-width-960" style="text-align:left;">
      <div class="paragraph-14 semi-bold" style="color:#4ade80;">Blog</div>
      <h1 class="heading-64" style="text-align:left;">Five Problems Context Engineers Face Right Now</h1>
      <div class="paragraph-18" style="display:flex; align-items:center; gap:16px;">
        <span>Kin Lane</span>
        <span>&middot;</span><span>April 14, 2026</span>
      </div>
    </div>
  </div>
</section>

<!-- Table of contents + Post content -->
<section class="section _64-56">
  <div class="container">
    <div class="content-56">
      <div class="grid-2-48" style="grid-template-columns:240px 1fr; gap:48px; align-items:start;">

        <!-- Table of contents sidebar -->
        <div id="post-toc" style="position:sticky; top:100px;">
          <div class="paragraph-14 semi-bold white" style="margin-bottom:16px;">Table of contents</div>
          <div id="toc-links" class="gap-12 align-top-left" style="display:flex; flex-direction:column; gap:8px;">
          </div>
        </div>

        <!-- Post body -->
        <div class="max-width-760" style="text-align:left;">
          <div class="paragraph-19 post-body" style="text-align:left;">
            <p>Context engineering is becoming a real job. Not a buzzword, not a rebranding of prompt engineering, but a distinct discipline with its own set of responsibilities: optimizing context windows for agents, translating upstream APIs and MCP servers into efficient tool interfaces, evaluating which techniques work for which models, and building evaluation frameworks for agent-API interaction quality.</p>

<p>We’ve been tracking this role through our persona work at Naftiko, and the problems context engineers face today are specific, structural, and largely unsolved. Here are five of them.</p>

<h2 id="1-there-is-no-agent-evaluation-framework">1. There Is No Agent Evaluation Framework</h2>

<p>Context engineers need to evaluate whether AI agents called APIs correctly — with the right parameters, in the right order — not just whether the final output looks correct. Today, most evaluation stops at the surface: did the agent produce a reasonable-looking response? That is not the same as verifying that the agent made the correct API call with the correct payload to the correct endpoint in the correct sequence.</p>

<p>This matters because agents that produce plausible outputs while making incorrect API calls are worse than agents that fail visibly. They create a false sense of reliability. Building evaluation frameworks that inspect the actual state of upstream services after an agent acts — not just the text it returns — is one of the most important unsolved problems in the space.</p>

<h2 id="2-too-many-mcp-tools-not-enough-consolidation">2. Too Many MCP Tools, Not Enough Consolidation</h2>

<p>Context engineers need to consolidate many upstream APIs and MCP servers into a smaller set of efficient tools that agents can use effectively. The current landscape is proliferating MCP servers and tool definitions faster than anyone can reason about them. An agent with access to forty tools performs worse than one with access to four well-designed tools, because the context window fills up with tool descriptions and the model spends tokens deciding which tool to use rather than doing the work.</p>

<p>The discipline of translating a sprawling API surface into a minimal, precise tool interface is where context engineering becomes genuinely hard. It requires understanding both the upstream API semantics and the downstream model behavior — and the translation is different for different models.</p>

<h2 id="3-mcp-workflows-need-embedded-question-formation">3. MCP Workflows Need Embedded Question Formation</h2>

<p>MCP-enabled documentation should accelerate implementation work inside IDEs and copilots, but “ask anything” interfaces fail when users don’t know the right prompts. Context engineers are discovering that the documentation layer needs to do more than expose information — it needs to embed question formation into the workflow itself.</p>

<p>This means structuring MCP-served content so that it suggests the next question, not just the current answer. It means building documentation that understands where a developer is in a workflow and surfaces the context they need before they know to ask for it. The “ask anything” paradigm assumes the user already knows what they don’t know, and that assumption breaks down fast in complex integration scenarios.</p>

<h2 id="4-repositories-need-minimum-agent-operational-documentation">4. Repositories Need Minimum Agent Operational Documentation</h2>

<p>Repositories can look documented but still fail basic agent tasks because the docs were written for humans, not for agent execution. A README that says “run the setup script” is fine for a developer. An agent needs to know which script, what arguments, what environment variables, what the expected output looks like, and what to do when the output doesn’t match.</p>

<p>Context engineers are starting to define what “minimum agent operational documentation” looks like — the baseline set of structured, machine-readable documentation that a repository needs before an agent can reliably operate within it. This is not about replacing human documentation. It is about establishing a parallel layer that agents can consume without ambiguity.</p>

<h2 id="5-markdown-needs-standardized-structures-for-agent-consumption">5. Markdown Needs Standardized Structures for Agent Consumption</h2>

<p>Markdown docs must follow predictable, machine-reliable structures so agents can consistently locate authoritative answers. Today, most markdown documentation is written for human readability — which means inconsistent heading hierarchies, ambiguous section boundaries, and context that depends on the reader having read previous sections.</p>

<p>Context engineers need markdown that agents can parse deterministically. That means consistent heading structures, explicit section boundaries, self-contained sections that don’t depend on prior context, and metadata that tells an agent what kind of information each section contains. The gap between “human-readable markdown” and “agent-consumable markdown” is wider than most teams realize, and closing it is foundational work for anyone building agent-powered developer tools.</p>

<h2 id="where-this-is-heading">Where This Is Heading</h2>

<p>These five problems share a common thread: the infrastructure and conventions that worked for human-only workflows do not transfer cleanly to agent-augmented workflows. Context engineering as a discipline exists precisely because that translation layer is missing and someone needs to build it.</p>

<p>At Naftiko, we are building the capability layer that sits between enterprise APIs and AI agents — governed, spec-driven, and designed for exactly the kind of structured context delivery that these problems demand. If you are working on any of these problems, we would like to hear from you.</p>

          </div>
        </div>

      </div>
    </div>
  </div>
</section>

<!-- More articles -->
<section class="section _64-56">
  <div class="container">
    <div class="content-56">
      <div class="gap-14 align-text-center max-width-760" style="margin:0 auto;">
        <h2>More articles</h2>
      </div>
      <div class="grid-2-48">
        
        
          <a href="/blog/making-your-apis-more-visible-with-github-and-gitbook/" class="card-15a-20r w-inline-block">
            <div class="inner-card-40-32">
              <div class="ho---bloom-3"></div>
              <div class="ho---bloom-4"></div>
              <div style="display:flex; flex-direction:column; gap:20px;">
                
                  <div style="flex-shrink:0; max-height:180px; overflow:hidden; border-radius:12px;">
                    <img src="/assets/img/blog/making-your-apis-more-visible-with-github-and-gitbook.png" loading="lazy" alt="Making Your APIs More Visible With GitHub and GitBook" style="width:100%; height:180px; object-fit:cover; display:block;"/>
                  </div>
                
                <div class="gap-12 align-top-left">
                  <div class="paragraph-14 semi-bold" style="color:#4ade80;">April 14, 2026 &middot; Kin Lane</div>
                  <div class="paragraph-24 white medium">Making Your APIs More Visible With GitHub and GitBook</div>
                  <div class="paragraph-18">API specs scatter across GitHub repos while documentation drifts in GitBook spaces. We built sixteen Naftiko capabilities to close the discovery-to...</div>
                </div>
              </div>
            </div>
          </a>
        
          <a href="/blog/naftiko-signals-q1-2026-what-292-companies-tell-us-about-ai-enterprise-investment/" class="card-15a-20r w-inline-block">
            <div class="inner-card-40-32">
              <div class="ho---bloom-3"></div>
              <div class="ho---bloom-4"></div>
              <div style="display:flex; flex-direction:column; gap:20px;">
                
                  <div style="flex-shrink:0; max-height:180px; overflow:hidden; border-radius:12px;">
                    <img src="/assets/img/blog/naftiko-signals-q1-2026-what-292-companies-tell-us-about-ai-enterprise-investment.png" loading="lazy" alt="Naftiko Signals Q1 2026: What 292 Companies Tell Us About AI Enterprise Investment" style="width:100%; height:180px; object-fit:cover; display:block;"/>
                  </div>
                
                <div class="gap-12 align-top-left">
                  <div class="paragraph-14 semi-bold" style="color:#4ade80;">April 8, 2026 &middot; Kin Lane</div>
                  <div class="paragraph-24 white medium">Naftiko Signals Q1 2026: What 292 Companies Tell Us About AI Enterprise Investment</div>
                  <div class="paragraph-18">Naftiko Signals looks at 49 industries and 292 companies for signals across 44 signal groups to understand the impact AI has had across enterprises...</div>
                </div>
              </div>
            </div>
          </a>
        
      </div>
    </div>
  </div>
</section>

<!-- TOC generator script -->
<script>
document.addEventListener('DOMContentLoaded', function() {
  var body = document.querySelector('.post-body');
  var tocLinks = document.getElementById('toc-links');
  if (!body || !tocLinks) return;
  var headings = body.querySelectorAll('h2, h3');
  if (!headings.length) {
    var toc = document.getElementById('post-toc');
    if (toc) toc.style.display = 'none';
    return;
  }
  headings.forEach(function(h, i) {
    var id = 'section-' + i;
    h.setAttribute('id', id);
    var link = document.createElement('a');
    link.href = '#' + id;
    link.textContent = h.textContent;
    link.className = 'paragraph-14';
    link.style.color = h.tagName === 'H3' ? 'rgba(255,255,255,0.5)' : 'rgba(255,255,255,0.7)';
    link.style.paddingLeft = h.tagName === 'H3' ? '12px' : '0';
    link.style.textDecoration = 'none';
    link.style.transition = 'color 0.2s';
    link.addEventListener('mouseenter', function() { this.style.color = '#4ade80'; });
    link.addEventListener('mouseleave', function() { this.style.color = h.tagName === 'H3' ? 'rgba(255,255,255,0.5)' : 'rgba(255,255,255,0.7)'; });
    tocLinks.appendChild(link);
  });
});
</script>

<style>
  .post-body h2 { margin-top: 40px; margin-bottom: 16px; text-align: left !important; font-size: 1.4em !important; }
  .post-body h3 { margin-top: 32px; margin-bottom: 12px; text-align: left !important; font-size: 1.15em !important; }
  .post-body p { margin-bottom: 16px; line-height: 1.7; }
  .post-body ul, .post-body ol { margin-bottom: 16px; padding-left: 24px; }
  .post-body li { margin-bottom: 8px; line-height: 1.6; }
  .post-body blockquote { border-left: 3px solid #4ade80; padding-left: 20px; margin: 24px 0; opacity: 0.85; }
  .post-body code { background: rgba(255,255,255,0.08); padding: 2px 6px; border-radius: 4px; font-size: 0.9em; }
  .post-body pre { background: rgba(255,255,255,0.06); padding: 20px; border-radius: 12px; overflow-x: auto; margin: 24px 0; }
  .post-body pre code { background: none; padding: 0; }
  .post-body a { color: #4ade80; text-decoration: underline; }
  .post-body img { max-width: 100%; border-radius: 12px; margin: 24px 0; }
  @media (max-width: 991px) {
    .grid-2-48[style*="grid-template-columns:240px"] { grid-template-columns: 1fr !important; }
    #post-toc { position: static !important; margin-bottom: 32px; }
  }
</style>
"
                commit_message: ""
                branch: "main"
  consumes:
    - import: "consumes-gitbook.yml"
      as: "gitbook"
    - import: "consumes-github.yml"
      as: "github"

naftiko: "0.5"
info:
  label: "API Doc Freshness Monitor"
  description: "Monitors last-modified dates of API specs on GitHub and docs on GitBook, flagging stale entries."
capability:
  exposes:
    - type: "mcp"
      namespace: "freshness-monitor"
      tools:
        - name: "check-freshness"
          description: "Compares spec and doc modification dates and reports staleness."
          inputParameters:
            - name: owner
              in: query
              type: string
            - name: repo
              in: query
              type: string
            - name: spaceId
              in: query
              type: string
            - name: stale_days
              in: query
              type: integer
          steps:
            - name: get-commits
              type: call
              call: "github.list-commits"
              with:
                owner: ""
                repo: ""
                per_page: 1
            - name: get-space
              type: call
              call: "gitbook.get-space"
              with:
                spaceId: ""
        - name: "list-stale-spaces"
          description: "Lists all spaces and flags those not updated within the staleness threshold."
          inputParameters:
            - name: gitbook_orgId
              in: query
              type: string
            - name: stale_days
              in: query
              type: integer
          steps:
            - name: list-spaces
              type: call
              call: "gitbook.list-spaces"
              with:
                orgId: ""
  consumes:
    - import: "consumes-github.yml"
      as: "github"
    - import: "consumes-gitbook.yml"
      as: "gitbook"