Azure Developer CLI (azd)

The azure.ai.skills extension allows you to manage Microsoft Foundry skills (reusable behavioral guidelines for agents) from your terminal. Skills are versioned and immutable.

When you create a skill, it uploads the first default version. When you update a skill, it uploads a new immutable version and promotes it to the default_version. You can revert to or access older versions using --set-default-version <version> or by downloading a specific version with azd ai skill download --version <ver>.

# Example: Creating a skill from a directory
azd ai skill create my-skill --file ./skill-src/

# Example: Updating a skill with inline instructions
azd ai skill update my-skill --instructions "New instructions here"

A CommandJob is the fundamental job type in the Azure AI ML SDK. It executes a single command on a specified compute target with defined inputs, outputs, and environment configuration.

A CommandJob is composed of four functional layers:

1. Resource: Handles metadata and serialization.
2. Job: Manages job-level configuration.
3. ParameterizedCommand: A mixin for command execution details.
4. JobIOMixin: A mixin for input/output handling.

When a parent command (like root) defines persistent flags, store them in a global variable within that package. Child commands can then reference this global variable directly to access the flag values.

// In root.go
var rootFlags struct {
    Debug    bool
    NoPrompt bool
}

func NewRootCommand() *cobra.Command {
    cmd := &cobra.Command{...}
    cmd.PersistentFlags().BoolVar(&rootFlags.NoPrompt, "no-prompt", false, "...")
    return cmd
}

// In child commands
func runInit(ctx context.Context, flags *initFlags) error {
    if rootFlags.NoPrompt {
        // Use no-prompt mode
    }
    return nil
}

Local provision validation is a client-side check that executes during azd provision after Bicep compilation but before the template is sent to Azure.

The Workflow:

1. Compile Bicep module: Generates the ARM template and parameters.
2. Local provision validation:
   • Parses the ARM template.
   • Generates a Bicep snapshot (a fully resolved deployment graph).
   • Analyzes resources to derive properties.
   • Runs registered check functions.
3. Server-side ARM preflight: Calls the Azure ValidatePreflight API.
4. Deploy: Executes the deployment in Azure.

When viewing pull request jobs, you may see suffixes like b1 or ib1. These are automatically added by the matrix creation logic to handle batching:

• bX (e.g., b1, b2): Indicates a batch of direct packages. Packages are grouped by their matrix configuration (from their ci.yml) and then split into batches based on a configurable batchSize (defaulting to 10).
• ibX (e.g., ib1): Indicates a batch of indirect packages. These are also batched, but instead of using the full test matrix, the system deterministically selects a single item from the resolved test matrix to assign the batch to.

When implementing Go logic in azd:

• Errors: Always wrap errors using fmt.Errorf with the %w verb to provide actionable context and maintain trace IDs.
• Context: Always propagate context.Context through function calls to ensure proper cancellation and telemetry support.

func (s *Service) Run(ctx context.Context) error {
    if err := s.doWork(ctx); err != nil {
        return fmt.Errorf("failed to provision resources: %w", err)
    }
    return nil
}