Skip to content
API Cloud

API Standards Review: Linting as a Developer Skill

This documentation explains how API providers can use linting as an AI-assisted developer skill in the early stages of their development process. The approach validates OpenAPI specifications against Trimble API Standards while you design and implement APIs, so issues surface as errors and warnings during development rather than only after hand-off or publication.

1. Overview

Trimble has piloted a shift-left strategy: run the same style of ruleset validation you would use for compliance checking directly in the development environment (for example, Cursor with Agent Skills), guided by explicit instructions tied to Trimble’s OpenAPI rules.

Traditionally, teams might discover gaps only when they validate or score a spec only when uploading their spec in the Cloud Console. With linting as a skill, the assistant is instructed to find your OpenAPI files, run or reason about Trimble rules (including Spectral-based rulesets where applicable), and report structured findings so you can fix MUST/REQUIRED items and SHOULD/RECOMMENDED items before the API is considered complete.

For teams on GitHub without Cursor, the same guidance can be delivered as explicit instructions (for example, in Copilot custom instructions), so the behavior is reproducible across editors.

2. What the skill helps you do

When the API standards review skill is active (or its instructions are pasted into your assistant’s context), you can:

  • Validate and review OpenAPI (YAML/JSON) specifications against Trimble API Standard expectations.
  • Receive a clear breakdown of errors (must-fix / required) and warnings (recommended), with locations tied to paths, operations, or components in the spec.
  • Iterate on fixes in the same session: address violations, re-run review, and converge on Trimble-standard APIs before Console steps or consumer integration.

The goal is for integrators and API providers to build APIs that already match Trimble conventions during the development phase, reducing rework and review cycles.

3. Official skill source (Platform AI Kit)

The maintained skill definition lives in the Trimble OSS Platform AI Kit repository:

API standards review skill (SKILL.md) on GitHub

You should treat that file as the source of truth for workflows, rule references, and updates. Copy from this location whenever you refresh skills in your project or adapt text for Copilot instructions.

To download a single file without cloning the whole repository, open the link above and use Raw (or your browser / curl) to save SKILL.md locally, then place it as described in the sections below.

4. Using the skill in Cursor

Cursor Agent Skills are typically folders that contain a SKILL.md file. To install the API standards review skill for a project:

  1. In your repository root, ensure a skills directory exists, for example: .cursor/skills/.

  2. Create a folder for this skill, for example: api-standards-review (the name can match the repo path for consistency).

  3. Copy the file from Platform AI Kit into that folder and name it SKILL.md, so the full path is:

    • .cursor/skills/api-standards-review/SKILL.md

  4. Reload or reopen the workspace if your editor does not pick up new skills immediately.

  5. In chat or agent mode, ask for a review (see Section 6) so the model loads the skill and follows its workflow.

5. Using the same guidance in GitHub Copilot (non-Cursor users)

GitHub Copilot does not use Cursor’s SKILL.md format natively, but you can give Copilot the same instructions as plain text. Recommended options:

Repository-level instructions (shared with the team)

  1. In your API or docs repository, add or edit .github/copilot-instructions.md at the root (supported for GitHub Copilot coding agent and repository-scoped guidance in supported clients).
  2. Paste the contents of SKILL.md from the Platform AI Kit link above, or a shortened version your team maintains that still references Trimble rules and the desired report format.
  3. Commit the file so everyone cloning the repo gets the same behavior.

Personal or organization instructions (GitHub.com)

  1. Sign in to GitHub → Settings → Copilot (exact navigation can vary by plan and UI updates).
  2. Find Copilot custom or instructions fields (personal and, where enabled, organization-level).
  3. Paste an adapted excerpt from SKILL.md that fits the character limit, and point to your in-repo .github/copilot-instructions.md for the full text if needed.

Visual Studio Code with Copilot Chat

If your team uses workspace instructions in VS Code, add the skill text to the workspace instructions file or setting your admin documents, so Copilot Chat in that folder follows the same review steps.

Keep instructions versioned in Git whenever possible so “review my spec” behaves consistently across machines and over time.

6. Example prompts to review and fix your spec

Use clear paths and goals. Examples you can copy and adjust:

Initial review

  • “Using our Trimble API standards instructions, review openapi/openapi.yaml .List all errors and warnings with file locations and rule names.”
  • “Lint my OpenAPI spec at ./specs/my-api.yaml for Trimble compliance. Summarize must-fix vs recommended issues.”

Deep dive on one area

  • “Focus on versioning, base path, and security schemes in openapi.yaml. What violates Trimble API Standard?”

Fix cycle

  • “For each error in the last report, propose a concrete OpenAPI edit (YAML snippet) for openapi.yaml.”
  • “Apply the fixes for error items only, then re-run the same review and show the diff summary.”

CI alignment

  • “Compare your findings to what npm run lint would report if we add the Trimble linter script—list anything only Spectral covers.”

Short, explicit prompts work best: name the file and whether you want report only or proposed patches.

7. Benefits

  • Earlier feedback: Catch standard violations while the spec is still easy to change.
  • Clear severity: Separate errors from warnings so teams can prioritize MUST fixes first.
  • Consistent expectations: Same Trimble-oriented guidance for Cursor and Copilot users when instructions are shared from one source (SKILL.md).
  • Less downstream churn: Fewer surprises during API Cloud publication.
  • Knowledge in the repo: Checked-in instructions document how your team expects OpenAPI to be validated.

8. Conclusion

Linting as a developer skill brings Trimble API Standard validation into the authoring phase of the API lifecycle. Install the skill from Platform AI Kit – SKILL.md into .cursor/skills/.../SKILL.md for Cursor, or mirror that content into .github/copilot-instructions.md and Copilot settings for GitHub-centric workflows. Use the prompt patterns in Section 6 to review, fix, and re-validate until your OpenAPI spec aligns with Trimble standards before you depend on late-stage tooling alone.

For the normative standard and rule references, continue to rely on Trimble API Standard documentation and your team’s chosen ruleset version (for example r2026.1 / r2023.1).