Skip to content

chore- Add OpenAPI api-eval, api-review, and api-fix skills#303

Merged
AEAbreu-hub merged 5 commits into
mainfrom
chore/developAPIReviewCommand
May 19, 2026
Merged

chore- Add OpenAPI api-eval, api-review, and api-fix skills#303
AEAbreu-hub merged 5 commits into
mainfrom
chore/developAPIReviewCommand

Conversation

@AEAbreu-hub
Copy link
Copy Markdown
Collaborator

@AEAbreu-hub AEAbreu-hub commented May 19, 2026

Summary

Replaces the monolithic eval-API-ref.mdc rule with modular OpenAPI rules, three Cursor skills (/api-eval, /api-review, /api-fix), Redocly lint scripts, and an api-spec-reviewer agent. Spoke repos with a symlinked .cursor folder can use the same skills to audit and fix specs under static/ without a fixed petstore.json filename.

Changes

.cursor/rules/api-ref-router.mdc

  • Thin router for OpenAPI JSON: routes to api-eval, api-review, or api-fix.

.cursor/rules/api-ref-structure.mdc

  • Section order, license boilerplate, JSON/$ref validity.

.cursor/rules/api-ref-copy.mdc

  • Summaries, description punctuation, public-facing text (no internal IDs).

.cursor/rules/api-ref-schema.mdc

  • anyOf/null, OpenAPI 3.1 type arrays, $ref/title rules.

.cursor/rules/api-ref-examples.mdc

  • Redocly example and placeholder conventions.

.cursor/rules/api-ref-tags-errors.mdc

  • Tags, standard error responses, auth parameters.

.cursor/rules/api-ref-ffs-styleguide.mdc

  • Condensed Firefly Services API Style Guide checkpoints for api-eval.

.cursor/rules/api-ref-skills.mdc

  • Documents /api-eval, /api-review, /api-fix and lint commands.

.cursor/rules/eval-API-ref.mdc

  • Deprecated stub pointing to modular rules and skills (replaces ~837-line monolith).

.cursor/skills/_shared/resolve-api-spec.md

  • Resolves spec path from user input, editor, or static/**/*.json discovery.

.cursor/skills/api-eval/SKILL.md

  • Read-only audit: Redocly lint, structure, OpenAPI version, FFS style guide, copy rules.

.cursor/skills/api-eval/ffs-styleguide-checklist.md

  • Offline FFS style guide checklist with wiki links.

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

  • Ref-numbered description catalog tables with proposed content.

.cursor/skills/api-fix/SKILL.md

  • Fixes Redocly lint errors and api-ref-structure inconsistencies.

.cursor/skills/api-fix/reference.md

  • Redocly and structure fix reference.

.cursor/agents/api-spec-reviewer.md

  • Agent: lint + api-fix after OpenAPI edits; suggests api-eval for style/copy.

redocly.yaml

  • Redocly CLI config for static/**/*.json.

package.json

  • Adds lint:openapi and lint:openapi:all scripts.

.cursor/rules/cursor-rules.mdc

  • Documents API skills alongside gc/gcam.

README.md

  • OpenAPI spec skills section for contributors.

Context

Jira

No ticket

Made with Cursor

AEAbreu-hub and others added 4 commits May 19, 2026 11:29
@AEAbreu-hub @cursoragent
Add OpenAPI eval, review, and fix skills
6527099 
- 📖 Add modular api-ref rules, eval-api, review-api, and fix-api
  skills plus api-spec-reviewer agent.
- 📖 Add redocly.yaml, lint:openapi scripts, and resolve-api-spec
  helper for static/ spec discovery.
- ✏️ Replace eval-API-ref.mdc monolith with a deprecated stub.
- ✏️ Document skills in README and cursor-rules.mdc.

Co-authored-by: Cursor <cursoragent@cursor.com>
@AEAbreu-hub @cursoragent
Rename API skills to api-eval, api-fix, api-review
91a0259 
- ✏️ Rename skill directories and slash commands for clearer
  listing (/api-eval, /api-fix, /api-review).
- ✏️ Update rules, agent, README, and resolve-api-spec references.

Co-authored-by: Cursor <cursoragent@cursor.com>
@AEAbreu-hub @cursoragent
Extend api-fix to apply api-ref-structure fixes
755478f 
- ✏️ Update api-fix skill and reference for lint plus structure
  pass (section order, license, refs).
- ✏️ Align api-eval, router, README, and agent with new scope.

Co-authored-by: Cursor <cursoragent@cursor.com>
@AEAbreu-hub
Remove specific path filtering for linting in GitHub Actions workflow
9ff8bf8
@github-actions
Copy link
Copy Markdown
Contributor

github-actions Bot commented May 19, 2026

🔍 Linter Report

Click to expand full report 
═══════════════════════════════════════════════════════════════
                     LINTER REPORT
═══════════════════════════════════════════════════════════════

Generated: 2026-05-19T23:14:00.202Z
Mode: Full Linting (all rules + dead links check)
Target Directory: /home/runner/work/ff-services-docs/ff-services-docs

───────────────────────────────────────────────────────────────

Files to process: 8

───────────────────────────────────────────────────────────────
📄 FILE: src/pages/guides/get-started.md
───────────────────────────────────────────────────────────────
  ⚠️  WARNING
    Location: Line 115:117
    Message: Unexpected dead URL `https://developer.adobe.com/developer-console/docs/guides/authentication/ServerToServerAuthentication/implementation/`, expected live URL
    Rule: no-dead-urls

───────────────────────────────────────────────────────────────
📄 FILE: src/pages/guides/index.md
───────────────────────────────────────────────────────────────
  ⚠️  WARNING
    Location: Line 143:1
    Message: Unexpected redirecting URL `https://experienceleague.adobe.com/docs/experience-platform/intelligent-services/content-commerce-ai/overview.html`, expected final URL `https://experienceleague.adobe.com/en/docs/experience-platform/intelligent-services/content-commerce-ai/overview`
    Rule: no-dead-urls

───────────────────────────────────────────────────────────────
📄 FILE: src/pages/guides/support/index.md
───────────────────────────────────────────────────────────────
  ⚠️  WARNING
    Location: Line 1:1
    Message: Missing or empty description in frontmatter
    Rule: check-frontmatter

  ⚠️  WARNING
    Location: Line 29:100
    Message: Unexpected redirecting URL `https://community.adobe.com/t5/adobe-firefly/ct-p/ct-adobe-firefly?page=1&sort=latest_replies&filter=all&lang=all&tabid=bugs`, expected final URL `https://community.adobe.com/p/firefly`
    Rule: no-dead-urls

───────────────────────────────────────────────────────────────
📄 FILE: src/pages/guides/tutorials/automate-workflow.md
───────────────────────────────────────────────────────────────
  ⚠️  WARNING
    Location: Line 35:190
    Message: Unexpected dead URL `https://developer.adobe.com/developer-console/docs/guides/services/services-add-api-oauth-s2s/#api-overview`, expected live URL
    Rule: no-dead-urls

  ⚠️  WARNING
    Location: Line 273:16
    Message: Unexpected dead URL `https://developer.adobe.com/firefly-services/docs/firefly-api/api/#operation/generateObjectCompositeV3Async`, expected live URL
    Rule: no-dead-urls

───────────────────────────────────────────────────────────────
📄 FILE: src/pages/guides/tutorials/create-product-images-with-ff.md
───────────────────────────────────────────────────────────────
  ⚠️  WARNING
    Location: Line 212:14
    Message: Unexpected dead URL `https://developer.adobe.com/firefly-services/docs/firefly-api/api/#operation/storageImageV2`, expected live URL
    Rule: no-dead-urls

  ⚠️  WARNING
    Location: Line 384:233
    Message: Unexpected dead URL `https://developer.adobe.com/firefly-services/docs/firefly-api/api/#operation/generateImagesV3Async`, expected live URL
    Rule: no-dead-urls

  ⚠️  WARNING
    Location: Line 440:23
    Message: Unexpected dead URL `https://developer.adobe.com/firefly-services/docs/firefly-api/api/#operation/expandImagesV3Async`, expected live URL
    Rule: no-dead-urls

───────────────────────────────────────────────────────────────
📄 FILE: src/pages/guides/tutorials/using-the-sdk.md
───────────────────────────────────────────────────────────────
  ⚠️  WARNING
    Location: Line 56:1
    Message: Title is too long (64 characters). Consider keeping it under 60 characters.
    Rule: check-frontmatter

  ⚠️  WARNING
    Location: Line 291:113
    Message: Unexpected dead URL `https://github.com/Firefly-Services/firefly-services-sdk-jshttps://github.com/Firefly-Services/firefly-services-sdk-js`, expected live URL
    Rule: no-dead-urls

  ⚠️  WARNING
    Location: Line 99:58
    Message: Unexpected dead URL `https://git.corp.adobe.com/cc-apis/firefly-services-sdk-js/`, expected live URL
    Rule: no-dead-urls


═══════════════════════════════════════════════════════════════
                        SUMMARY
═══════════════════════════════════════════════════════════════

  📁 Files processed:    8
  📄 Files with issues:  6
  ❌ Total errors:       0
  ⚠️  Total warnings:     12
  📋 Total issues:       12

Result: ⚠️  PASSED WITH WARNINGS - No fatal errors

═══════════════════════════════════════════════════════════════

This comment was automatically generated by the linter bot.

@github-actions
Copy link
Copy Markdown
Contributor

github-actions Bot commented May 19, 2026

🔍 Linter Report

Click to expand full report 
═══════════════════════════════════════════════════════════════
                     LINTER REPORT
═══════════════════════════════════════════════════════════════

Generated: 2026-05-19T23:16:34.991Z
Mode: Full Linting (all rules + dead links check)
Target Directory: /home/runner/work/ff-services-docs/ff-services-docs

───────────────────────────────────────────────────────────────

Files to process: 8

───────────────────────────────────────────────────────────────
📄 FILE: src/pages/guides/get-started.md
───────────────────────────────────────────────────────────────
  ⚠️  WARNING
    Location: Line 115:117
    Message: Unexpected dead URL `https://developer.adobe.com/developer-console/docs/guides/authentication/ServerToServerAuthentication/implementation/`, expected live URL
    Rule: no-dead-urls

───────────────────────────────────────────────────────────────
📄 FILE: src/pages/guides/index.md
───────────────────────────────────────────────────────────────
  ⚠️  WARNING
    Location: Line 143:1
    Message: Unexpected redirecting URL `https://experienceleague.adobe.com/docs/experience-platform/intelligent-services/content-commerce-ai/overview.html`, expected final URL `https://experienceleague.adobe.com/en/docs/experience-platform/intelligent-services/content-commerce-ai/overview`
    Rule: no-dead-urls

───────────────────────────────────────────────────────────────
📄 FILE: src/pages/guides/support/index.md
───────────────────────────────────────────────────────────────
  ⚠️  WARNING
    Location: Line 1:1
    Message: Missing or empty description in frontmatter
    Rule: check-frontmatter

  ⚠️  WARNING
    Location: Line 29:100
    Message: Unexpected redirecting URL `https://community.adobe.com/t5/adobe-firefly/ct-p/ct-adobe-firefly?page=1&sort=latest_replies&filter=all&lang=all&tabid=bugs`, expected final URL `https://community.adobe.com/p/firefly`
    Rule: no-dead-urls

───────────────────────────────────────────────────────────────
📄 FILE: src/pages/guides/tutorials/automate-workflow.md
───────────────────────────────────────────────────────────────
  ⚠️  WARNING
    Location: Line 273:16
    Message: Unexpected dead URL `https://developer.adobe.com/firefly-services/docs/firefly-api/api/#operation/generateObjectCompositeV3Async`, expected live URL
    Rule: no-dead-urls

  ⚠️  WARNING
    Location: Line 35:190
    Message: Unexpected dead URL `https://developer.adobe.com/developer-console/docs/guides/services/services-add-api-oauth-s2s/#api-overview`, expected live URL
    Rule: no-dead-urls

───────────────────────────────────────────────────────────────
📄 FILE: src/pages/guides/tutorials/create-product-images-with-ff.md
───────────────────────────────────────────────────────────────
  ⚠️  WARNING
    Location: Line 212:14
    Message: Unexpected dead URL `https://developer.adobe.com/firefly-services/docs/firefly-api/api/#operation/storageImageV2`, expected live URL
    Rule: no-dead-urls

  ⚠️  WARNING
    Location: Line 384:233
    Message: Unexpected dead URL `https://developer.adobe.com/firefly-services/docs/firefly-api/api/#operation/generateImagesV3Async`, expected live URL
    Rule: no-dead-urls

  ⚠️  WARNING
    Location: Line 440:23
    Message: Unexpected dead URL `https://developer.adobe.com/firefly-services/docs/firefly-api/api/#operation/expandImagesV3Async`, expected live URL
    Rule: no-dead-urls

───────────────────────────────────────────────────────────────
📄 FILE: src/pages/guides/tutorials/using-the-sdk.md
───────────────────────────────────────────────────────────────
  ⚠️  WARNING
    Location: Line 56:1
    Message: Title is too long (64 characters). Consider keeping it under 60 characters.
    Rule: check-frontmatter

  ⚠️  WARNING
    Location: Line 99:58
    Message: Unexpected dead URL `https://git.corp.adobe.com/cc-apis/firefly-services-sdk-js/`, expected live URL
    Rule: no-dead-urls

  ⚠️  WARNING
    Location: Line 291:113
    Message: Unexpected dead URL `https://github.com/Firefly-Services/firefly-services-sdk-jshttps://github.com/Firefly-Services/firefly-services-sdk-js`, expected live URL
    Rule: no-dead-urls


═══════════════════════════════════════════════════════════════
                        SUMMARY
═══════════════════════════════════════════════════════════════

  📁 Files processed:    8
  📄 Files with issues:  6
  ❌ Total errors:       0
  ⚠️  Total warnings:     12
  📋 Total issues:       12

Result: ⚠️  PASSED WITH WARNINGS - No fatal errors

═══════════════════════════════════════════════════════════════

This comment was automatically generated by the linter bot.

@AEAbreu-hub AEAbreu-hub merged commit 13bddcd into main May 19, 2026
2 checks passed
@AEAbreu-hub AEAbreu-hub deleted the chore/developAPIReviewCommand branch May 19, 2026 23:17
@AEAbreu-hub
Copy link
Copy Markdown
Collaborator Author

AEAbreu-hub commented May 20, 2026

api-rules-reconfiguration-plan.md
AI plan that was implemented

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@AEAbreu-hub