feat: add OpenClaw agent integration#1861
Conversation
This file outlines the Spec-Driven Development workflow using the speckit toolset, detailing the sequence of commands and core rules for implementation.
There was a problem hiding this comment.
Pull request overview
Adds OpenClaw as a first-class AI agent option in Specify CLI, updating agent configuration, release packaging, context update scripts, and user-facing docs so projects can be initialized with .openclaw/ structures.
Changes:
- Added
openclawto runtime agent configuration and documentation (README/AGENTS). - Extended release package generators (bash + PowerShell) to build OpenClaw skill-directory layouts.
- Updated agent-context update script to recognize
openclawand map it toAGENTS.md.
Reviewed changes
Copilot reviewed 8 out of 8 changed files in this pull request and generated 3 comments.
Show a summary per file
| File | Description |
|---|---|
src/specify_cli/__init__.py |
Registers openclaw in AGENT_CONFIG (folder + skills subdir + CLI requirement). |
templates/skill-file-template.md |
Adds a new SKILL.md template file (currently not referenced by code). |
templates/commands/skill.md |
Introduces a new template under templates/commands/ intended as a “Speckit skill” description. |
scripts/bash/update-agent-context.sh |
Adds openclaw option and maps it to AGENTS.md. |
.github/workflows/scripts/create-release-packages.sh |
Adds openclaw build variant and generates .openclaw/skills/<skill>/SKILL.md directories. |
.github/workflows/scripts/create-release-packages.ps1 |
PowerShell mirror of OpenClaw release packaging support. |
README.md |
Documents OpenClaw support, --ai openclaw, and tool checks. |
AGENTS.md |
Documents OpenClaw directory conventions and configuration fields. |
Comments suppressed due to low confidence (1)
templates/commands/skill.md:4
- PR description mentions a new
templates/SKILL.mdcopied to.openclaw/skills/speckit/SKILL.md, but the added file here istemplates/commands/skill.md(which will be packaged/installed as a normal command template). If the intent is a workspace-level OpenClaw skill manifest, it likely shouldn’t live undertemplates/commands/.
---
name: "speckit"
description: "Full Spec-Driven Development (SDD) workflow powered by github/spec-kit. Use speckit-specify to start a feature, then speckit-plan, speckit-tasks, and speckit-implement in sequence."
metadata:
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| --- | ||
| name: "{SKILL_NAME}" | ||
| description: "{DESCRIPTION}" | ||
| compatibility: "Requires spec-kit project structure with .specify/ directory" | ||
| metadata: | ||
| author: "github-spec-kit" | ||
| source: "templates/commands/{COMMAND_NAME}.md" | ||
| --- | ||
|
|
||
| # Spec Kit {COMMAND_TITLE} Skill | ||
|
|
||
| {COMMAND_BODY} |
mnriem
left a comment
mnriem
left a comment
There was a problem hiding this comment.
Please address Copilot feedback. If not applicable, please explain why
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
There was a problem hiding this comment.
Pull request overview
Adds OpenClaw as a new supported agent in Specify CLI, including packaging support and documentation updates so users can initialize projects with OpenClaw-compatible skill layouts.
Changes:
- Added
openclawto runtime agent configuration (AGENT_CONFIG) and updated docs to list OpenClaw as supported. - Updated release packaging scripts (bash + PowerShell) to build
.openclaw/skills/<skill>/SKILL.mdartifacts and includeopenclawin agent build lists. - Extended the bash agent context updater to recognize
openclaw, and introduced new skill-related templates.
Reviewed changes
Copilot reviewed 8 out of 8 changed files in this pull request and generated 7 comments.
Show a summary per file
| File | Description |
|---|---|
src/specify_cli/__init__.py |
Adds openclaw agent metadata used by init/check and skills installation logic. |
.github/workflows/scripts/create-release-packages.sh |
Adds OpenClaw packaging path and skill generation function; updates agent list. |
.github/workflows/scripts/create-release-packages.ps1 |
Mirrors OpenClaw packaging/skill generation on Windows. |
scripts/bash/update-agent-context.sh |
Adds OpenClaw to supported agent list and update routing (bash version). |
README.md |
Documents OpenClaw in supported agents + --ai/check help text and examples. |
AGENTS.md |
Documents OpenClaw directory conventions and CLI requirements. |
templates/commands/skill.md |
Adds a “speckit” skill manifest-like template (currently placed under command templates). |
templates/skill-file-template.md |
Adds a new SKILL.md template file (no code references found). |
Comments suppressed due to low confidence (3)
src/specify_cli/init.py:281
- The post-init “Next Steps” messaging in this module is hard-coded to slash commands like
/speckit.specify, but OpenClaw skills are generated/invoked asspeckit-<command>(per this PR). Consider making the displayed invocation style conditional onselected_ai(e.g., OpenClaw should showspeckit-specify,speckit-plan, etc.) so users don’t get incorrect instructions after initializing with--ai openclaw.
"openclaw": {
"name": "OpenClaw",
"folder": ".openclaw/",
"commands_subdir": "skills", # OpenClaw reads skills from .openclaw/skills/<skill-name>/SKILL.md
"install_url": "https://openclaw.ai",
"requires_cli": True,
},
.github/workflows/scripts/create-release-packages.sh:248
- OpenClaw skills are named
speckit-<cmd>, but the underlying command templates contain many hard-coded references to/speckit.<cmd>(dot style) in the body text.create_openclaw_skills()currently does not rewrite these, so OpenClaw users will see incorrect invocation instructions inside the generated SKILL.md content. Consider adding a rewrite step for OpenClaw that converts/speckit.<cmd>/speckit.<cmd>references to the OpenClaw form (e.g.,speckit-<cmd>).
# Build body: replace placeholders, strip scripts sections, rewrite paths
local body
body=$(printf '%s\n' "$file_content" | sed "s|{SCRIPT}|${script_command}|g")
if [[ -n $agent_script_command ]]; then
body=$(printf '%s\n' "$body" | sed "s|{AGENT_SCRIPT}|${agent_script_command}|g")
fi
body=$(printf '%s\n' "$body" | awk '
/^---$/ { print; if (++dash_count == 1) in_frontmatter=1; else in_frontmatter=0; next }
in_frontmatter && /^scripts:$/ { skip_scripts=1; next }
in_frontmatter && /^agent_scripts:$/ { skip_scripts=1; next }
in_frontmatter && /^[a-zA-Z].*:/ && skip_scripts { skip_scripts=0 }
in_frontmatter && skip_scripts && /^[[:space:]]/ { next }
{ print }
')
body=$(printf '%s\n' "$body" | sed 's/{ARGS}/\$ARGUMENTS/g' | sed 's/__AGENT__/openclaw/g' | rewrite_paths)
.github/workflows/scripts/create-release-packages.ps1:359
New-OpenClawSkillsdoes not rewrite template body references like/speckit.plan/speckit.plan(dot style) to the OpenClaw invocation style (speckit-plan). Since OpenClaw skills are named with dashes, leaving dot-style references in the body will produce incorrect user instructions. Consider adding an OpenClaw-specific text rewrite step before writing SKILL.md.
# Replace {SCRIPT}, strip scripts sections, rewrite paths
$body = $fileContent -replace '\{SCRIPT\}', $scriptCommand
if (-not [string]::IsNullOrEmpty($agentScriptCommand)) {
$body = $body -replace '\{AGENT_SCRIPT\}', $agentScriptCommand
}
$lines = $body -split "`n"
$outputLines = @()
$inFrontmatter = $false
$skipScripts = $false
$dashCount = 0
foreach ($line in $lines) {
if ($line -match '^---$') {
$outputLines += $line
$dashCount++
$inFrontmatter = ($dashCount -eq 1)
continue
}
if ($inFrontmatter) {
if ($line -match '^(scripts|agent_scripts):$') { $skipScripts = $true; continue }
if ($line -match '^[a-zA-Z].*:' -and $skipScripts) { $skipScripts = $false }
if ($skipScripts -and $line -match '^\s+') { continue }
}
$outputLines += $line
}
$body = $outputLines -join "`n"
$body = $body -replace '\{ARGS\}', '$ARGUMENTS'
$body = $body -replace '__AGENT__', 'openclaw'
$body = Rewrite-Paths -Content $body
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| "openclaw": { | ||
| "name": "OpenClaw", | ||
| "folder": ".openclaw/", | ||
| "commands_subdir": "skills", # OpenClaw reads skills from .openclaw/skills/<skill-name>/SKILL.md | ||
| "install_url": "https://openclaw.ai", | ||
| "requires_cli": True, | ||
| }, |
There was a problem hiding this comment.
Adding openclaw to AGENT_CONFIG enables specify init --ai openclaw, but extension/preset command registration uses CommandRegistrar.AGENT_CONFIGS (see src/specify_cli/agents.py) which currently has no openclaw entry. This means OpenClaw won’t be supported by the registrar-based flows; add an OpenClaw config there (likely .openclaw/skills with /SKILL.md semantics, similar to kimi) to make the integration complete and consistent.
This issue also appears on line 275 of the same file.
| ALL_AGENTS=(claude gemini copilot cursor-agent qwen opencode windsurf codex kilocode auggie roo codebuddy amp shai tabnine kiro-cli agy bob vibe qodercli kimi openclaw generic) | ||
| ALL_SCRIPTS=(sh ps) |
There was a problem hiding this comment.
ALL_AGENTS now includes openclaw, but the GitHub release upload script (.github/workflows/scripts/create-github-release.sh) still enumerates zip artifacts and does not include spec-kit-template-openclaw-{sh,ps}-<version>.zip. Without updating that script (and its corresponding consistency tests), OpenClaw packages won’t be published even though they are built here.
| { | ||
| printf -- '---\n' | ||
| printf 'name: "%s"\n' "$skill_name" | ||
| printf 'description: "%s"\n' "$description" | ||
| printf 'metadata:\n' | ||
| printf ' author: "github-spec-kit"\n' | ||
| printf ' source: "templates/commands/%s.md"\n' "$name" | ||
| printf -- '---\n\n' | ||
| printf '%s\n' "$template_body" | ||
| } > "$skill_dir/SKILL.md" |
There was a problem hiding this comment.
create_openclaw_skills() writes YAML by interpolating description into a double-quoted scalar (description: "%s"). If a template description contains double quotes or other YAML-significant characters, this can emit invalid YAML. Consider escaping quotes/newlines in description (or emitting YAML via a YAML-aware tool) before writing SKILL.md frontmatter.
This issue also appears on line 234 of the same file.
| openclaw) | ||
| update_agent_file "$OPENCLAW_FILE" "OpenClaw" || return 1 | ||
| ;; | ||
| generic) | ||
| log_info "Generic agent: no predefined context file. Use the agent-specific update script for your agent." | ||
| ;; | ||
| *) | ||
| log_error "Unknown agent type '$agent_type'" | ||
| log_error "Expected: claude|gemini|copilot|cursor-agent|qwen|opencode|codex|windsurf|kilocode|auggie|roo|codebuddy|amp|shai|tabnine|kiro-cli|agy|bob|vibe|qodercli|kimi|generic" | ||
| log_error "Expected: claude|gemini|copilot|cursor-agent|qwen|opencode|codex|windsurf|kilocode|auggie|roo|codebuddy|amp|shai|tabnine|kiro-cli|agy|bob|vibe|qodercli|kimi|openclaw|generic" | ||
| exit 1 |
There was a problem hiding this comment.
The bash agent context updater now supports openclaw, but the PowerShell equivalent (scripts/powershell/update-agent-context.ps1) does not contain any OpenClaw handling yet. To keep Windows support consistent, add the corresponding OpenClaw option/case there as well (and update its ValidateSet/help text if applicable).
| } | ||
|
|
||
| # Build SKILL.md with OpenClaw metadata block | ||
| $skillContent = "---`nname: `"$skillName`"`ndescription: `"$description`"`nmetadata:`n author: `"github-spec-kit`"`n source: `"templates/commands/$name.md`"`n---`n`n$templateBody" |
There was a problem hiding this comment.
PowerShell OpenClaw skill generation builds YAML frontmatter by interpolating $description inside double quotes. If the captured description contains quotes or other YAML-significant characters, the generated SKILL.md frontmatter can become invalid. Prefer escaping/quoting robustly (or using a YAML serializer) when emitting the frontmatter fields.
This issue also appears on line 328 of the same file.
| $skillContent = "---`nname: `"$skillName`"`ndescription: `"$description`"`nmetadata:`n author: `"github-spec-kit`"`n source: `"templates/commands/$name.md`"`n---`n`n$templateBody" | |
| # Escape description for YAML single-quoted scalar ('' represents a single ') | |
| $escapedDescription = $description -replace "'", "''" | |
| $skillContent = @" | |
| --- | |
| name: "$skillName" | |
| description: '$escapedDescription' | |
| metadata: | |
| author: "github-spec-kit" | |
| source: "templates/commands/$name.md" | |
| --- | |
| $templateBody | |
| "@ |
| --- | ||
| name: speckit | ||
| description: Full Spec-Driven Development (SDD) workflow powered by github/spec-kit. Use speckit-specify to start a feature, then speckit-plan, speckit-tasks, and speckit-implement in sequence. | ||
| metadata: | ||
| author: github-spec-kit | ||
| source: https://github.com/github/spec-kit | ||
| version: 1.0.0 | ||
| --- |
There was a problem hiding this comment.
templates/commands/skill.md is placed alongside command templates and will be picked up by release generation (templates/commands/*.md) for all agents, producing an unintended speckit.skill command (and extra Kimi/OpenClaw skills). If this file is meant to be an OpenClaw-only root skill manifest, move it out of templates/commands/ (e.g., templates/SKILL.md) and have the OpenClaw packaging/init logic copy it specifically to .openclaw/skills/speckit/SKILL.md (and ensure it’s excluded from generic command generation).
| --- | ||
| name: "{SKILL_NAME}" | ||
| description: "{DESCRIPTION}" | ||
| compatibility: "Requires spec-kit project structure with .specify/ directory" | ||
| metadata: | ||
| author: "github-spec-kit" | ||
| source: "templates/commands/{COMMAND_NAME}.md" | ||
| --- |
There was a problem hiding this comment.
This newly added templates/skill-file-template.md does not appear to be referenced anywhere in the codebase (e.g., install_ai_skills() builds SKILL.md content inline). Consider either wiring this template into the skill generation flow or removing it to avoid drift/confusion about the source of truth for SKILL.md formatting.
mnriem
left a comment
mnriem
left a comment
There was a problem hiding this comment.
Please address Copilot feedback. If not applicable, please explain why. And resolve conflicts.
|
@copilot open a new pull request to apply changes based on the comments in this thread |
1 similar comment
|
@copilot open a new pull request to apply changes based on the comments in this thread |
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 8 out of 8 changed files in this pull request and generated 5 comments.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| 'openclaw' { | ||
| $skillsDir = Join-Path $baseDir ".openclaw/skills" | ||
| New-Item -ItemType Directory -Force -Path $skillsDir | Out-Null | ||
| New-OpenClawSkills -SkillsDir $skillsDir -ScriptVariant $Script | ||
| } |
There was a problem hiding this comment.
The generated OpenClaw skills will include {AGENT_SCRIPT} expansions like scripts/powershell/update-agent-context.ps1 -AgentType openclaw (from templates/commands/plan.md). However scripts/powershell/update-agent-context.ps1 currently does not accept openclaw in its ValidateSet (and has no OPENCLAW_FILE mapping), so the PowerShell variant of the OpenClaw skill set will fail when the plan workflow tries to update agent context. Update the PowerShell context script to add OpenClaw support (mirroring the bash changes) or avoid emitting an OpenClaw agent_script for the ps package until it’s supported.
| # - Supports: Claude, Gemini, Copilot, Cursor, Qwen, opencode, Codex, Windsurf, Kilo Code, Auggie CLI, Roo Code, CodeBuddy CLI, Qoder CLI, Amp, SHAI, Tabnine CLI, Kiro CLI, Mistral Vibe, Kimi Code, OpenClaw, Antigravity or Generic | ||
| # - Can update single agents or all existing agent files | ||
| # - Creates default Claude file if no agent files exist | ||
| # | ||
| # Usage: ./update-agent-context.sh [agent_type] | ||
| # Agent types: claude|gemini|copilot|cursor-agent|qwen|opencode|codex|windsurf|kilocode|auggie|roo|codebuddy|amp|shai|tabnine|kiro-cli|agy|bob|vibe|qodercli|kimi|generic | ||
| # Agent types: claude|gemini|copilot|cursor-agent|qwen|opencode|codex|windsurf|kilocode|auggie|roo|codebuddy|amp|shai|tabnine|kiro-cli|agy|bob|vibe|qodercli|kimi|openclaw|generic |
There was a problem hiding this comment.
The bash context updater now supports openclaw, but the PowerShell version (scripts/powershell/update-agent-context.ps1) does not currently mention or accept openclaw (its ValidateSet omits it). This will break cross-platform parity for projects using the PowerShell scripts variant, especially because some command templates call the PowerShell context updater via {AGENT_SCRIPT}. Please update the PowerShell script alongside this bash change to keep agent support consistent.
| specify init my-project --ai bob | ||
|
|
||
| # Initialize with OpenClaw support | ||
| specify init my-project --ai openclaw --ai-skills |
There was a problem hiding this comment.
README recommends --ai openclaw --ai-skills, but the OpenClaw release package generation creates .openclaw/skills/<skill>/SKILL.md directories directly. In that setup, --ai-skills (which converts extracted command templates into skills) is likely a no-op or can produce confusing warnings/cleanup behavior. Either change the docs to recommend plain --ai openclaw or update the init/skill-install flow so --ai-skills is truly the intended path for OpenClaw.
| specify init my-project --ai openclaw --ai-skills | |
| specify init my-project --ai openclaw |
| "openclaw": { | ||
| "name": "OpenClaw", | ||
| "folder": ".openclaw/", | ||
| "commands_subdir": "skills", # OpenClaw reads skills from .openclaw/skills/<skill-name>/SKILL.md |
There was a problem hiding this comment.
With commands_subdir: "skills", specify init --ai openclaw --ai-skills can end up deleting the just-installed skill directories. The init cleanup logic deletes <agent_folder>/<commands_subdir> after successful install_ai_skills(), and for OpenClaw that path is the same as the skills output directory (.openclaw/skills). Consider either (1) keeping commands_subdir pointing at a commands template dir (e.g. .openclaw/commands) and writing skills to .openclaw/skills, or (2) updating the cleanup to skip deletion when cmds_dir resolves to the same path as _get_skills_dir() / when commands_subdir == "skills".
| "commands_subdir": "skills", # OpenClaw reads skills from .openclaw/skills/<skill-name>/SKILL.md | |
| # Use a dedicated commands template directory; OpenClaw still reads live skills from .openclaw/skills/<skill-name>/SKILL.md | |
| "commands_subdir": "commands", |
| --- | ||
| name: "{SKILL_NAME}" | ||
| description: "{DESCRIPTION}" | ||
| compatibility: "Requires spec-kit project structure with .specify/ directory" | ||
| metadata: | ||
| author: "github-spec-kit" | ||
| source: "templates/commands/{COMMAND_NAME}.md" | ||
| --- | ||
|
|
||
| # Spec Kit {COMMAND_TITLE} Skill | ||
|
|
||
| {COMMAND_BODY} |
There was a problem hiding this comment.
This file isn’t referenced anywhere in the repo right now (no code paths read templates/skill-file-template.md), and install_ai_skills() generates SKILL.md content inline. Either wire this template into the skill generation path (so it’s the single source of truth) or remove it to avoid an unused/duplicated template that can drift from the real output format.
| --- | |
| name: "{SKILL_NAME}" | |
| description: "{DESCRIPTION}" | |
| compatibility: "Requires spec-kit project structure with .specify/ directory" | |
| metadata: | |
| author: "github-spec-kit" | |
| source: "templates/commands/{COMMAND_NAME}.md" | |
| --- | |
| # Spec Kit {COMMAND_TITLE} Skill | |
| {COMMAND_BODY} | |
| <!-- | |
| NOTE: This file is intentionally not used as a runtime template. | |
| The SKILL.md content is generated inline by `install_ai_skills()`, which is | |
| the single source of truth for the SKILL file format. | |
| This placeholder file exists only to document that there is no standalone | |
| SKILL.md template. If you need to change the generated output, update | |
| `install_ai_skills()` instead. | |
| --> |
mnriem
left a comment
mnriem
left a comment
There was a problem hiding this comment.
Some more Copilot feedback. If not applicable, please explain why
Description
Adds full support for [OpenClaw](https://openclaw.ai) as a new AI agent in Specify CLI.
OpenClaw is a persistent AI agent daemon that connects to messaging platforms (Telegram, WhatsApp, Slack, etc.) and uses a skill-based architecture — skills are discovered as directories containing a
SKILL.mdfile under<workspace>/skills/, identical to the pattern used by Kimi Code.Files changed:
src/specify_cli/__init__.py— Added"openclaw"toAGENT_CONFIGwithfolder: ".openclaw/",commands_subdir: "skills",requires_cli: True,install_url: "https://openclaw.ai". Help text updates automatically via_build_ai_assistant_help()..github/workflows/scripts/create-release-packages.sh— AddedopenclawtoALL_AGENTSand newcreate_openclaw_skills()function that generates.openclaw/skills/speckit-<command>/SKILL.mdfiles with OpenClaw-compatible frontmatter..github/workflows/scripts/create-release-packages.ps1— Mirror of bash changes:New-OpenClawSkillsfunction,'openclaw'case inBuild-Variant,'openclaw'added to$AllAgents.scripts/bash/update-agent-context.sh— AddedOPENCLAW_FILE="$AGENTS_FILE"(OpenClaw readsAGENTS.mdfrom workspace root, same asamp,kiro-cli,bob), addedopenclaw)case inupdate_specific_agent()andupdate_if_newcall inupdate_all_existing_agents().AGENTS.md— Added OpenClaw to supported agents table, CLI-based agents list, Markdown format section, and directory conventions.README.md— Added OpenClaw to supported agents table,--aioption description,specify checktools list, and examples section.templates/SKILL.md— New workspace-level skill manifest copied to.openclaw/skills/speckit/SKILL.mdonspecify init --ai openclaw --ai-skills.templates/skill-file-template.md— New per-command SKILL.md template used byinstall_ai_skills(), following the existing*-template.mdnaming convention.Key design decisions:
--ai-skillsis the primary path for OpenClaw since it uses skill directories, not flat slash command filesspeckit-specify) vs Kimi Code's dot separator (speckit.specify)OPENCLAW_FILEpoints toAGENTS.md— the OpenClaw equivalent ofCLAUDE.mdfor Claude Codegenericremains last in all agent arraysTesting
uv run specify --helpuv sync && uv run pytestAI Disclosure
Implementation approach and file structure were developed with AI assistance (Claude). All code was manually reviewed, tested end-to-end, and verified against existing agent integration patterns before submission.