[Roadmap] First-class Claude Code and Codex skills installation and execution #22

Outcome and priority

Make skills authored for Claude Code and Codex equally installable, discoverable, and usable in Motifcode, through one documented skills management and invocation interface. Users should be able to bring an existing skill directory or a pinned Git source, inspect its compatibility, and run supported workflows without rewriting the skill as a Motif-only package.

This is the maintainer's highest-priority long-term ecosystem direction. It is a roadmap/design issue, not a single large implementation PR or a commitment to a specific release date. Use the Ecosystem interoperability milestone and split agreed phases into small child issues before implementation. The local/file-based path must work without MCP or a remote service.

Current gaps, verified on main

Audited at 01b49ad5a4d3e60395aa61f094275042a88aae0c:

• Skill discovery loads built-ins, Motif plugins, ~/.motif/skills, and the current directory's .motif/skills. There is no cross-host discovery/import workflow. motif skills only lists entries.
• The parser splits frontmatter line by line rather than parsing YAML, requires name/description, rejects allowed-tools/tools, and does not retain host-specific invocation policy or nested metadata.
• Skill records retain only coarse source scope; rendering injects the body without its origin path. Bundled references/scripts therefore lack an explicit skill-root resolution contract.
• The registry overwrites same-name registrations. Plugin loading expects a root plugin.json; that is not enough to claim compatibility with full Claude/Codex plugin packages.
• Existing slash invocation, progressive body loading, and fixed session tool schemas are useful foundations to preserve.

Compatibility target

The shared Agent Skills format uses YAML frontmatter plus Markdown and can bundle scripts, references, and assets resolved from the skill root. Its optional allowed-tools field is experimental. Supporting the common format is the baseline, then host adapters account for extensions.

Official host differences matter: Claude Code documents .claude/skills, invocation controls such as disable-model-invocation/user-invocable, argument and directory substitutions, and host-specific execution features. Codex documentation documents .agents/skills discovery and optional agents/openai.yaml invocation/dependency metadata. A legacy .codex/skills directory can be an explicit import source; it must not be described as the only current Codex location.

Proposed endpoint/interface

Define one reusable local skills lifecycle and invocation API first, shared by CLI, TUI, and future integrations. “Endpoint” here means a stable entry point; this issue does not require an HTTP daemon or a hosted marketplace.

Illustrative commands, subject to design review:

motif skills add <local-directory-or-git-url> --path <skill-subdir> --ref <commit> --scope user|project
motif skills list --json
motif skills inspect <qualified-id> --json
motif skills run <qualified-id> -- <task arguments>
motif skills enable|disable <qualified-id>
motif skills update <qualified-id> --ref <commit>
motif skills remove <qualified-id>

Only applicable options are required: a local directory does not need a Git ref. Remote installs resolve and record immutable revisions. Underlying operations should cover list, inspect, install, invoke, enable/disable, update, and remove, returning structured diagnostics. Reuse /skills, explicit slash invocation, and the existing model-facing skill loader where possible. An SDK or future MCP exposure should call this same implementation.

Phased delivery

Phase 1 — contract, compatibility fixtures, and parser

• Agree on normalized metadata, a source-qualified skill identity, policy representation, and supported / adapted / blocked diagnostics. Document compatibility by feature and tested host format version/date.
• Add a real YAML parser with schema validation for the common format, preservation of extension data, and clear errors for malformed or unsupported executable semantics. Preserve existing Motif budget/tags behavior.
• Create small, redistributable fixtures for portable, Claude-style, Codex-style, and intentionally unsupported skills. Keep the initial fixture suite API-key-free.

Phase 2 — install, discover, inspect, update, remove

• Support local folders and pinned Git repository subdirectories with the same UX for both ecosystems; preserve the complete selected skill directory, including license files and assets.
• Add opt-in import/discovery for .claude/skills, .agents/skills, and explicitly supplied legacy/custom roots. Resolve nested project scope deliberately; never mutate another host's installed skills as a side effect.
• Record origin URL/local path, commit/content digest, adapter, installed scope, original name, and compatibility status. Make update changes reviewable and replacement atomic; remove only installation-owned files and keep user edits detectable.
• Define deterministic scope precedence without silently breaking existing .motif overrides. Preserve colliding entries under qualified IDs and show exactly which entry an unqualified alias resolves to.

Phase 3 — execution and resource parity

• Ensure relative references/assets/scripts resolve from the installed skill root even when the working directory changes. Define script working directory and output location explicitly; preserve paths containing spaces and Unicode.
• Apply explicit versus implicit invocation policy consistently in the index, TUI, slash entry point, and model-facing loader. A blocked implicit invocation must not succeed through an alternate entry point.
• Implement and test selected Claude argument/path substitutions and Codex metadata adaptation. Capability-bearing fields must produce precise diagnostics until their semantics are implemented.
• Run scripts through Motif's existing execution and permission controls. Discovery/install/inspect must not run bundled scripts or shell preprocessing. Imported metadata must not grant permissions beyond user/project policy. Handle archive traversal, escaping symlinks, missing dependencies, cancellation, and execution failure explicitly.
• Keep installed dependencies and updates visible. Missing MCP tools should identify the required server/tool and link to the MCP setup flow once that exists; portable skills must remain usable independently.

Phase 4 — ecosystem packaging and mature integration

• Design Claude/Codex plugin packaging adapters separately, starting with selecting skills from bundles and explaining unsupported accompanying components.
• Expose the stable API to additional clients only when a concrete consumer exists. Coordinate MCP-dependent skills with the MCP roadmap without coupling basic installation to a network service.
• Publish the tested compatibility matrix, migration guidance, examples for both ecosystems, and concise contributor documentation.

Acceptance and review boundaries

• A portable skill from either ecosystem can be installed, inspected, explicitly invoked, disabled, updated, and removed using the same interface, with bundled resources preserved and correct path resolution.
• An unsupported host feature has an actionable compatibility diagnosis; unknown safety/execution policy is never silently treated as supported.
• Tests cover YAML multiline/quoted/nested values, invocation policy, same-name collisions, source provenance, failed/atomic updates, missing resources, path traversal/symlinks, and permission denial.
• End-to-end tests use temporary homes/workspaces, local Git fixtures, a fake transport, and harmless scripts. No paid API key or real Claude/Codex account is required for CI; any later live smoke test is separately optional.
• Existing Motif skills remain functional. Skills do not unexpectedly mutate tool schemas during a live session; any required capability changes respect the session/cache design.

Please propose the smallest independently reviewable phase or child issue before implementation. This umbrella is not a good first issue. Fixture/documentation tasks may become GFIs after their interfaces and acceptance criteria are settled.

Related work and coordination

Companion roadmap: #23 (managed MCP clients). Missing MCP dependencies should be diagnosed, but local/file-based skills remain independently installable and usable. Reuse the execution-policy and cancellation contracts from #15, #16, and #17.