Skip to content

ADR: Reject ! syntax in SKILL.md due to compatibility concerns #68

@nucliweb

Description

@nucliweb

Context

The possibility of using the !command`` syntax in the WebPerf Skills SKILL.md files was evaluated. This feature injects shell command output directly into the prompt when a skill is invoked.

The proposal, referenced in https://x.com/lydiahallie/status/2034337963820327017, would allow embedding JavaScript snippet content inline at skill invocation time — eliminating the need for Claude to read script files separately during execution.

Image

Decision

Reject the !command`` syntax in the WebPerf Skills.

Reason

The !command`` feature is exclusive to Claude Code (CLI). The skills are designed to be compatible with any environment that supports the skills format. Introducing a Claude Code dependency would break that compatibility.

Consequences

JavaScript scripts remain as standalone files referenced by name in the SKILL.md files. Claude reads them on demand during skill execution.

Metadata

Metadata

Assignees

No one assigned

    Labels

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions