Support Claude Code skills format alongside legacy custom commands

[cabrauck]

Summary

Agent OS currently installs its Claude workflows as legacy custom commands under .claude/commands/agent-os/*.md.

Anthropic now recommends project skills under .claude/skills/<skill-name>/SKILL.md. Existing custom commands remain supported, but skills are the recommended successor and follow the portable Agent Skills standard.

Would you consider supporting the skills format, either as the new default or alongside the existing command output?

Current behavior

On current main, scripts/project-install.sh copies commands/agent-os/*.md to .claude/commands/agent-os/*.md. This produces namespaced commands such as /agent-os:shape-spec.

Observed problem

I tested a repository initialized with these files using Claude Desktop on Windows with an Ubuntu WSL2 coding environment:

• Claude Desktop: 1.24012.9
• Bundled Claude Code runtime: 2.1.219
• Project repository opened directly inside Ubuntu WSL2
• Agent OS command files present, tracked, and non-empty in the selected repository

The Desktop slash-command picker displayed only built-in commands and did not list the project-owned Agent OS commands. This may be a Desktop discovery/compatibility issue rather than an Agent OS defect, since Anthropic documents .claude/commands/ as still supported, but using the current skills format would avoid depending on the legacy discovery path.

Why skills would help

According to the current Claude Code documentation:

• .claude/commands/ is the legacy format.
• .claude/skills/<name>/SKILL.md is the recommended format.
• Skills support supporting files, automatic invocation, live discovery, and the open Agent Skills standard.
• Existing custom commands can remain supported during a migration.

Documentation: https://code.claude.com/docs/en/slash-commands

Suggested approach

1. Add canonical Agent OS skill definitions under a skills source directory.
2. Let the installer emit .claude/skills/<skill-name>/SKILL.md.
3. Preserve existing slash-command names where practical, or document the naming change explicitly.
4. Optionally continue emitting legacy .claude/commands/ files for older Claude Code versions during a transition period.
5. Add installation tests covering both Claude Code CLI and Claude Desktop with a WSL2 project.

Acceptance criteria

• A freshly initialized project exposes the Agent OS workflows through the current Claude skills mechanism.
• The workflows are discoverable in supported Claude Code surfaces, including Desktop with a WSL2 project.
• Existing users have a documented, non-destructive migration path.
• Command/skill naming and compatibility behavior are documented.
• Installer tests validate the generated skill structure.

I can help test a proposed implementation in Claude Code CLI and Claude Desktop/WSL2.