Skip to content

feat: add apimatic sdk skill#2

Open
Ayeshas09 wants to merge 4 commits intomainfrom
feat/add-apimatic-sdk-skill
Open

feat: add apimatic sdk skill#2
Ayeshas09 wants to merge 4 commits intomainfrom
feat/add-apimatic-sdk-skill

Conversation

@Ayeshas09
Copy link
Copy Markdown

Adds a new skill for generating, customizing, and managing SDKs using the APIMatic CLI.

What's included:

  • SKILL.md having full workflow covering auth, generation, CodeGen settings via APIMATIC-META.json, and change tracking for customizations
  • Reference files for all CodeGen setting categories (timeout, branding, endpoints, serialization, etc.)
  • First-time setup guide and save-changes workflow
  • Example flows
  • Eval suite

@Ayeshas09 Ayeshas09 self-assigned this Apr 23, 2026
@Ayeshas09 Ayeshas09 requested a review from sohaibtariq April 23, 2026 11:00
Copy link
Copy Markdown
Collaborator

@sohaibtariq sohaibtariq left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

PR Review: apimatic-sdk skill

The skill is well-architected overall — strong eval suite (41 cases), clean progressive disclosure, and the 14-item red flags section is the best part of the SKILL.md. Two blocking issues need resolution before merge.

Blocking:

  • B1. Missing scripts/auth-login.mjs — runtime failure on first use (see inline comment)
  • B2. --track-changes contradicts between SKILL.md and the example file (see inline comments)

Suggestion:

  • I3. Add a publishing example file to examples/ (see inline comment)

Details inline below.

Additionally, in terms of the structure of SKILLs.md, it might make sense to have 3 sections:

  • Generate an SDK
  • Customize an SDK
  • Publish an SDK

The last 2 are covered, but the first isn't explicitly mentioned, although it is implied in both of the sections.
Do you think we need to have a separate SDK generation section ?

Comment thread skills/apimatic-sdk/SKILL.md

Ask: "Do you already have a generated SDK you've customized, or are you starting fresh?"
- **Already has a customized SDK →** Skip generation entirely. Ask: "Would you like me to apply the customizations, or will you handle them yourself?" then follow the appropriate path below.
- **Starting fresh →** Add the `--track-changes` flag to the generate command. After generation completes in Step 7, ask: "Would you like me to apply the customizations, or will you handle them yourself?" then follow the appropriate path below.
Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

B2. --track-changes contradicts between SKILL.md and the example file

SKILL.md says here to "Add the --track-changes flag to the generate command" and the Additional flags section (line 342) says it "Must be used during the initial generation to set up the source tree."

But examples/generate-customize-save.md says "Change tracking is enabled automatically" and its generate command omits --track-changes:

apimatic sdk generate --language=typescript

Evals 6, 10, and 11 all assert --track-changes must be present, aligning with SKILL.md.

The agent receives contradictory instructions. One of these artifacts is teaching wrong behavior.

Suggested fix — determine which is correct:

  • If --track-changes is required: update the example to include the flag and remove the "enabled automatically" line
  • If tracking is now automatic in the CLI: update SKILL.md and evals 6, 10, 11 to reflect this

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

--track-changes flag is required to enable tracking, I have updated the example.

Comment thread skills/apimatic-sdk/examples/generate-customize-save.md Outdated
Comment thread skills/apimatic-sdk/SKILL.md Outdated
@Ayeshas09
Copy link
Copy Markdown
Author

PR Review: apimatic-sdk skill

The skill is well-architected overall — strong eval suite (41 cases), clean progressive disclosure, and the 14-item red flags section is the best part of the SKILL.md. Two blocking issues need resolution before merge.

Blocking:

  • B1. Missing scripts/auth-login.mjs — runtime failure on first use (see inline comment)
  • B2. --track-changes contradicts between SKILL.md and the example file (see inline comments)

Suggestion:

  • I3. Add a publishing example file to examples/ (see inline comment)

Details inline below.

Additionally, in terms of the structure of SKILLs.md, it might make sense to have 3 sections:

  • Generate an SDK
  • Customize an SDK
  • Publish an SDK

The last 2 are covered, but the first isn't explicitly mentioned, although it is implied in both of the sections. Do you think we need to have a separate SDK generation section ?

Reagrding the last point, the generation steps were already there, I've grouped them under a Generate an SDK heading and added a note that these same steps apply when initializing change tracking during a customization workflow. So now all the three sections are explicitly covered.

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

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants