How Spec Kit Generates Release Packages for Different AI Agents in CI/CD Workflows

When a version tag is pushed to the Spec Kit repository, a GitHub Actions workflow executes create-release-packages.sh to build individualized zip archives for every supported AI assistant across both Bash and PowerShell environments.

The automation pipeline in the github/spec-kit repository transforms generic command templates into agent-specific configurations during the release process. By iterating over predefined agent lists and script variants, the CI/CD system ensures each AI assistant receives a compatible, ready-to-use package bundle.

Workflow Trigger and Version Resolution

The Release Workflow defined in .github/workflows/release.yml initiates exclusively when a maintainer pushes a git tag matching the v* pattern. According to the Spec Kit source code, this workflow extracts the semantic version from the tag name and passes it as the sole argument to the packaging script.

Core Packaging Orchestration

The shell script .github/workflows/scripts/create-release-packages.sh serves as the central orchestration engine. At initialization, it defines two critical arrays that determine the build matrix:

• ALL_AGENTS: Enumerates every supported AI assistant (e.g., claude, gemini, cursor-agent, kiro-cli) at lines 32-34
• ALL_SCRIPTS: Declares the supported script variants as ALL_SCRIPTS=(sh ps) at lines 34-35

Environment-Based Filtering

Before processing begins, the script checks for the optional environment variables AGENTS and SCRIPTS. When populated, these variables filter the build scope to specific agents or script types. If unset, the script defaults to the full lists, ensuring comprehensive coverage across the entire agent ecosystem.

Directory Structure and Assembly

For each permutation of agent and script type, the script invokes the build_variant function. This function creates a temporary staging directory at <GENRELEASES_DIR>/sdd-<agent>-package-<script>, then assembles the package contents:

1. Copies the core Spec Kit skeleton—including memory, templates, and the selected script variant—into a hidden .specify folder

2. Invokes generate_commands to produce agent-specific command files

3. For the Copilot agent specifically, calls generate_copilot_prompts to create companion .prompt.md files

4. Compresses the assembled directory into a zip file following the deterministic naming convention:

   
   spec-kit-template-<agent>-<script>-<VERSION>.zip
   

   For example, the kiro-cli Bash variant becomes spec-kit-template-kiro-cli-sh-v0.2.0.zip (as implemented at lines 27-30).

Template Transformation Engine

The generate_commands function handles the conversion of generic templates into agent-specific command definitions. It reads the source files from templates/commands/*.md and performs string substitution on three critical placeholders:

• {SCRIPT}: The base script command
• {AGENT_SCRIPT}: The agent-specific script invocation
• {ARGS}: The argument format string (e.g., $ARGUMENTS for Claude-style Markdown or {{args}} for Gemini/Qwen TOML syntax)

As implemented in the Spec Kit source code at lines 61-67, this function writes the processed output to agent-specific directories such as .kiro/prompts/ for the kiro-cli agent, ensuring each AI assistant receives commands in its native format.

Release Publication Automation

After the build_variant loop completes, the workflow executes .github/workflows/scripts/create-github-release.sh. This script references the same ALL_AGENTS array to locate the generated zip files within the .genreleases/ directory. It then attaches these archives as release assets to the GitHub Release associated with the version tag, completing the distribution pipeline.

Manual Package Generation

Developers can manually test the packaging logic without triggering a full release by setting environment variables to constrain the build scope. To generate only the Claude and kiro-cli packages for PowerShell:

AGENTS="claude,kiro-cli" SCRIPTS="ps" \
  .github/workflows/scripts/create-release-packages.sh v0.3.0

This command produces targeted output files such as:

• spec-kit-template-claude-ps-v0.3.0.zip
• spec-kit-template-kiro-cli-ps-v0.3.0.zip

Summary

• The Release Workflow triggers exclusively on v* tag pushes via .github/workflows/release.yml
• The ALL_AGENTS and ALL_SCRIPTS arrays in create-release-packages.sh define the complete build matrix of supported AI assistants and script variants
• The build_variant function constructs staging directories, assembles skeleton files, and invokes generate_commands for each agent-script permutation
• Template processing substitutes placeholders like {SCRIPT}, {ARGS}, and agent identifiers to produce format-compatible command files
• The create-github-release.sh script automates asset attachment using the same agent enumeration logic
• Environment variables AGENTS and SCRIPTS enable selective package generation for testing or partial releases

Frequently Asked Questions

How does Spec Kit determine which AI agents receive release packages?

The script maintains a bash array named ALL_AGENTS at lines 32-34 of .github/workflows/scripts/create-release-packages.sh that explicitly lists every supported agent identifier, such as claude, gemini, and cursor-agent. The packaging loop iterates over this array to ensure each agent receives a customized package with appropriate command file structures.

Can I generate release packages for only one specific AI agent?

Yes. Set the AGENTS environment variable to a comma-separated list of agent identifiers before invoking the script. For example, AGENTS="claude" ./create-release-packages.sh v1.0.0 produces archives exclusively for the Claude agent. You can further restrict output by also setting SCRIPTS="sh" to build only the Bash variant.

What file naming convention does Spec Kit use for release archives?

Archives follow the deterministic pattern spec-kit-template-<agent>-<script>-<VERSION>.zip, where <agent> is the lowercase agent identifier (e.g., kiro-cli), <script> is either sh or ps, and <VERSION> matches the git tag (e.g., v0.2.0). The script implements this naming at lines 27-30 of create-release-packages.sh.

How are agent-specific command formats handled during generation?

The generate_commands function reads generic templates from templates/commands/*.md and performs targeted string substitution on placeholders including {SCRIPT}, {ARGS}, and the agent name. This transformation allows the same source templates to generate Claude-style Markdown arguments, Gemini-style TOML arguments, or other agent-specific syntaxes without maintaining separate template repositories for each AI assistant.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}