edit-idl

Orchestrates IDL pull, edit, commit, and code generation for PSM-scoped services.

Updated Apr 30, 2026
One-click install
npx skills add https://github.com/yuezhen-huang/my-bytedance-skillhub --skill edit-idl-yuezhen-huang
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: edit-idl
Source: https://github.com/yuezhen-huang/my-bytedance-skillhub/tree/main/edit-idl
Command: npx skills add https://github.com/yuezhen-huang/my-bytedance-skillhub --skill edit-idl-yuezhen-huang

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Editing Thrift or Protobuf IDL for a microservice involves pulling the right PSM-scoped files, committing changes to the correct feature branch via NextCode, and triggering code generation across different modes. This Skill defines the exact workflow and branch rules so these steps happen in the right order without committing to master or breaking downstream codegen. ## Core Features & Use Cases - PSM-scoped IDL pull: Fetches only the IDL files related to a target service PSM, with automatic read-only fallback to master when the requested branch is unavailable. - Branch-safe commit: Commits only .thrift/.proto files via the NextCode CreateCommit API to a feature branch, creating the branch if needed and producing a BAM version. - Flexible code generation: Triggers codegen in auto, overpass, gdp_local, or gdp_remote modes, with status querying and built-in retry for transient Overpass network errors. - Use Case: You need to add new fields to a service's Thrift interface. The Skill guides the agent to pull the IDL into a temp directory, edit it locally, commit to your feature branch, and run remote codegen, then verify the generated MR links. ## Quick Start Ask the agent to pull the IDL for your service PSM on your feature branch, apply your interface changes, commit them, and trigger code generation following the edit-idl workflow.

Frequently Asked Questions about edit-idl

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I edit Thrift IDL for a microservice and regenerate code?

Follow the four-step workflow: pull PSM-scoped IDL files with idl-pull, edit them locally in a temporary directory, commit with idl-commit to your feature branch via NextCode, then trigger generation with idl-codegen. Never commit IDL changes directly to master.

What happens if my feature branch does not exist in the IDL repo?

The idl-pull step falls back to reading from master, but idl-commit still targets your feature branch and creates it automatically before committing. Read fallback never changes the commit target branch.

Which codegen mode should I use: overpass, gdp_local, or gdp_remote?

Use auto to let the tool detect the mode. Choose gdp_remote to trigger a remote GDP task, gdp_local for local gdp update when the repo has .gdp/rpcmodels.local.yaml configured, or overpass to force Overpass generation.

Why does idl-codegen fail with a missing rpcmodels.local.yaml error?

The gdp_local mode requires GDP local development mode, which needs .gdp/rpcmodels.local.yaml in the service repo. Run gdp update --local-rpcmodels or gdp update --idl <path> --save-local once to configure it, then retry.

Can I modify base.thrift during an IDL change?

No. base.thrift must not be modified in this workflow because changing it can break downstream code generation for dependent services. Limit edits to your service's own IDL files.