[BUG] Using the `[arg-name]` syntax in slash command front-matter is technically a WARNING-level mistake

Preflight Checklist

• [x] I have searched existing issues and this hasn't been reported yet
• [x] This is a single bug report (please file separate reports for different bugs)
• [x] I am using the latest version of Claude Code

What's Wrong?

The method CC uses for providing argument hints to slash commands is to add a line like this to the Markdown front-matter and enclose each hint inside a pair of [ and ]:

---
argument-hint: [file-reference] [prose] [concept]
...
---
...

This is technically wrong, and triggers warning in linters (e.g. markdownlint), as [] is the first component of writing links in Markdown, where the link text is written in:

[Anthropic](https://anthropic.com)

When linters see [arg-hint-name] in the front-matter, they warn that this is not the way [ and ] are supposed to be used in Markdown files:

No link definition found: 'file-reference'(link.no-such-reference)

Deprecate the current syntax and use an alternative that doesn't trigger linting warnings.

What Should Happen?

State of the matter:

Claude Code specification and the TUI implementation for Claude Code, claude, should not use syntax that clashes with correct usage of Markdown.

Linters should not see argument hints and warn the user and mark the file as problematic.

Expected state:

Instead of using the [arg-hint-name] syntax, adopt a syntax that does not clash with how Markdown should be written. For example, adopt $argHintName or $arg-hint-name$:

argument-hint: $file-reference$ $prose$ $concept$

Optionally deprecate the old syntax.

Error Messages/Logs

No link definition found: 'file-reference'(link.no-such-reference)

Steps to Reproduce

1. Read the docs at https://docs.claude.com/en/docs/claude-code/slash-commands
2. Write a slash command with argument hints

```md
---
argument-hint: [pr-number] [priority] [assignee]
description: Review pull request
---

Review PR #$1 with priority $2 and assign to $3.
Focus on security, performance, and code style.
```

1. Lint the markdown file using markdownlint or open it in Visual Studio Code
2. Observe the linting warning:

<img width="729" height="150" alt="Image" src="https://github.com/user-attachments/assets/f343c541-b54d-42a9-a7e5-8b38c112a9df" />

Claude Model

None

Is this a regression?

I don't know

Last Working Version

_No response_

Claude Code Version

v2.0.0

Platform

Anthropic API

Operating System

Other Linux

Terminal/Shell

Other

Additional Information

_No response_