OpenParable
Skip to content
← Back to skills

Generate From Typespec

Development
generate-from-typespec

Generate From Typespec is an Agent Skill for development published in the microsoft/typespec repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

Generate Python SDK code from a TypeSpec specification using the local emitter. Use this skill when the user wants to generate/regenerate a Python client from a TypeSpec spec, provides a GitHub URL or local path to a TypeSpec project, or says things like "generate from this spec", "emit Python from this tsp", "regenerate the SDK", or "compile this TypeSpec for Python".

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/microsoft/typespec/blob/HEAD/packages/http-client-python/.github/skills/generate-from-typespec/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/generate-from-typespec, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

Generate From TypeSpec Skill

Compiles a TypeSpec specification using the local @typespec/http-client-python emitter and generates Python SDK code. Supports both branded (@azure-tools/typespec-python) and unbranded (@typespec/http-client-python) generation.

Inputs

The caller must provide:

  1. Spec path — either:
    • A local file path to a .tsp entry point (e.g., client.tsp, main.tsp)
    • A raw GitHub URL pointing to a TypeSpec project directory or file (e.g., https://github.com/Azure/azure-rest-api-specs/tree/main/specification/.../Foundry/src/sdk-service-agentserver-contracts/client.tsp)
  2. Flavor — azure (branded) or unbranded. If not provided, ask the user.
  3. Emitter output directory — the full resolved path where generated code should be written (e.g., ~/Desktop/github/azure-sdk-for-python/sdk/agentserver/azure-ai-agentserver-responses). If not provided, ask the user.
  4. Additional options (optional) — any extra key=value emitter options the user wants applied on top of the tspconfig options. These override tspconfig values if there's a conflict (e.g., models-mode=typeddict).

Workflow

Step 1: Resolve the spec path

If the input is a GitHub URL:

  1. Parse the URL to extract owner, repo, ref (branch/commit), and path.
  2. Check if the repository is cloned locally (look under common locations like ~/Desktop/github/<repo-name>, ~/<repo-name>, etc.).
  3. If found locally, check out the correct ref/commit if needed:
    cd <local-repo>
    git fetch origin <ref>
    git checkout <ref> -- <path-to-spec-dir>/
    
  4. If not found locally, ask the user where the repo is cloned, or offer to clone it.

If the input is a local path:

Verify the file/directory exists. If the path points to a directory, look for client.tsp or main.tsp as the entry point.

Step 2: Locate and parse tspconfig.yaml

Look for tspconfig.yaml in the same directory as the spec entry point, then walk up parent directories until one is found.

# Starting from the spec file's directory, search for tspconfig.yaml
current_dir="<spec-dir>"
while [ "$current_dir" != "/" ]; do
  if [ -f "$current_dir/tspconfig.yaml" ]; then
    echo "Found: $current_dir/tspconfig.yaml"
    break
  fi
  current_dir=$(dirname "$current_dir")
done

Step 3: Extract Python emitter options from tspconfig.yaml

Parse the tspconfig.yaml and extract the options block for the Python emitter. The emitter may appear under either name:

FlavorEmitter key in tspconfig.yaml
Branded@azure-tools/typespec-python
Unbranded@typespec/http-client-python

Important cross-flavor rule: If the user requests a different flavor than what's in the tspconfig, carry over ALL options from the tspconfig's Python emitter block. For example:

  • tspconfig has options under @azure-tools/typespec-python but user wants unbranded → use all those options, but emit under @typespec/http-client-python
  • tspconfig has options under @typespec/http-client-python but user wants branded → use all those options, but emit under @azure-tools/typespec-python

If no Python emitter options exist in the tspconfig at all, ask the user for:

  • emitter-output-dir (required — where to write the generated code)
  • package-name (required)
  • namespace (optional — omit to let @clientNamespace decorators resolve naturally)

Step 4: Determine the flavor

Use this precedence:

  1. If the user explicitly stated azure or unbranded, use that.
  2. If the tspconfig has a flavor option set, mention it to the user and confirm.
  3. If the tspconfig only has one Python emitter key, infer:
    • @azure-tools/typespec-python → azure
    • @typespec/http-client-python → unbranded
  4. If still ambiguous, ask the user:

    "Should I generate as branded (azure flavor) or unbranded?"

Step 5: Find the TypeSpec compiler

Look for the tsp CLI in the spec repo's node_modules:

# Check spec repo root for compiler
< spec-repo-root > /node_modules/@typespec/compiler/cmd/tsp.js

If not found, fall back to the global tsp command, or check the typespec monorepo's compiler:

~/Desktop/github/typespec/packages/compiler/cmd/tsp.js

Step 6: Construct and run the compile command

Build the tsp compile command using:

  • Entry point: The resolved .tsp file from Step 1
  • --emit: Always the local emitter path: ~/Desktop/github/typespec/packages/http-client-python
  • --option flags: One for each option from the tspconfig, prefixed with the local emitter name @typespec/http-client-python (regardless of what the tspconfig called it). Any additional options provided by the user are appended last and override tspconfig values if there's a conflict.

Template:

< tsp-cli-path > compile < entry-point.tsp > --emit ~/Desktop/github/typespec/packages/http-client-python \
  --option "@typespec/http-client-python.<key1>=<value1>" \
  --option "@typespec/http-client-python.<key2>=<value2>" \
  ...

Option mapping rules:

tspconfig keyCLI --option keyNotes
emitter-output-diremitter-output-dirResolve {output-dir}, {service-dir} variables
package-modepackage-modeUsually dataplane or mgmt
package-namepackage-name
namespacenamespaceOmit if not in tspconfig — see note below
api-versionapi-version
flavorflavorSet to azure for branded, omit for unbranded
generate-testgenerate-test
generate-samplegenerate-sample
models-modemodels-modee.g., dpg, msrest, typeddict
Any other optionPass through as-is

Namespace note: Do NOT pass --namespace unless it is explicitly set in the tspconfig or by the user. When omitted, the emitter lets TCGC resolve @clientNamespace decorators correctly. Passing a namespace when @clientNamespace is used in the spec can cause incorrect directory nesting.

emitter-output-dir: Always use the value provided by the user (Input #3). Ignore the emitter-output-dir from the tspconfig — it typically contains unresolvable template variables like {output-dir} and {service-dir}.

Step 7: Run the compilation

cd <spec-directory>
<constructed-compile-command>

Set a timeout of at least 180 seconds — compilation can take a few minutes.

Check the output:

  • Warnings only → success
  • Errors → report to the user with the full error output

Step 8: Verify and clean up

After successful compilation:

  1. Show the generated directory structure:

    find < output-dir > -type d | sort
    
  2. Verify the output matches expectations (e.g., TypedDict if models-mode=typeddict).

  3. If the generation overwrote files in an existing package, warn the user and offer to revert non-generated files:

    cd <sdk-repo>
    git diff --name-status <package-dir>/ | grep -v "<expected-generated-path>"
    

Notes

The --namespace trap

When a TypeSpec uses @clientNamespace to map types into a different namespace, TCGC resolves the namespace. If you also pass --namespace, TCGC tries to replace the root of the @clientNamespace value with the flag, which can produce doubled prefixes like azure.azure.ai.projects.... Only pass --namespace when the tspconfig explicitly sets it.

Branded vs unbranded emitter names

The local emitter is always @typespec/http-client-python on the CLI --emit and --option flags. The flavor option controls branded behavior:

  • Branded: --option "@typespec/http-client-python.flavor=azure"
  • Unbranded: omit the flavor option entirely

Common additional options the user may request

User requestOption to add
TypedDict only--option "@typespec/http-client-python.models-mode=typeddict"
No tests--option "@typespec/http-client-python.generate-test=false"
No samples--option "@typespec/http-client-python.generate-sample=false"