Skill reference syntax: convention for delineating skill dependencies in SKILL.md

[krisrowe]

Problem

Skills reference other skills in their body text (e.g., "invoke the privacy-scan skill") but there's no standard syntax to distinguish a skill reference from prose. This means build tools can't reliably:

• Detect which skills a given skill depends on
• Validate that all referenced skills are available
• Warn about undeclared or over-declared dependencies

Question

Is there an established convention in agentskills.io, Claude Code docs, or the broader ecosystem for delineating skill references in markdown? For example:

• Backtick-wrapped name + "skill" suffix: `privacy-scan` skill
• A specific markdown pattern the build can grep for
• A frontmatter field like depends: or references:

Research needed

1. Check agentskills.io for any reference syntax standard
2. Check Claude Code docs for skill cross-referencing conventions
3. Check Vercel Labs skills-npm for how they handle inter-skill dependencies
4. Propose a convention that works for both human readability and machine parsing

Context

The claude-coding-plugin has a build step with static analysis (pytest) that validates skill references in agent definitions and CLAUDE.md. Extending this to validate skill-to-skill references would catch missing dependencies at build time.

[krisrowe]

Precedent for @Skill: syntax

The proposed @skill:name inline reference pattern has strong precedent across multiple domains:

Domain	Syntax	Purpose
GitHub markdown	@username	Mention a user, parsed by platform, rendered as link
JSDoc / Javadoc	@see, @param, @link	Structured references to other entities in doc comments, parsed by tooling
Java	@Override, @Deprecated	Metadata annotations parsed by compiler
Python	@decorator	Metadata attachment parsed by runtime
Docker	image@sha256:abc	Digest-pinned reference to a specific artifact
Kubernetes	@latest, resource references	Structured references to named resources

The closest analogue is JSDoc @see — an inline reference in a documentation-like format that points to another named entity, is human-readable in plain text, and is machine-parseable by tooling. @skill:privacy-scan follows the same pattern: readable in prose, extractable by regex (@skill:([a-z0-9-]+)), and meaningless to renderers that don't understand it (rendered as plain text in markdown).

The @namespace:identifier pattern specifically (with colon separator) mirrors:

• Docker image references: registry.io/image:tag@sha256:digest
• Kubernetes resource references: apiVersion:kind/name
• URI schemes: mailto:, tel:, ssh:

This isn't a novel invention — it's applying a well-established convention to a new domain.

[krisrowe]

Implementation note

If @skill:name is adopted, the CONTRIBUTING.md or relevant documentation for the echoskill CLI and spec extension MUST include the precedent analysis above — why this syntax was chosen, what it mirrors, and why it's not arbitrary. This is a design decision record, not just a convention. Future contributors and adopters need to see that it follows established patterns, not that someone made it up.

[krisrowe]

Correction: precedent scoped to .md / documentation contexts

The relevant precedents are those used inline in markdown or documentation files, not code annotations:

Context	Syntax	How it works
GitHub markdown	@username	Inline mention in .md files. Rendered as a link by GitHub. Plain text everywhere else.
JSDoc @see / @link	@see OtherClass, {@link name}	Inline reference in doc comments (which are markdown-adjacent). Parsed by doc generators, plain text otherwise.
Obsidian / wiki-style	[[page-name]]	Inline link to another document. Parsed by the tool, rendered as plain text in standard markdown.
MDX / Docusaurus	{@docusaurus/plugin-name}	References to named plugins/packages inline in docs.
GitHub issue autolinks	#123, owner/repo#123	Inline references in .md that resolve to issues. Pattern-matched by GitHub.

The pattern: a short, recognizable prefix + identifier, inline in prose, that standard markdown ignores but tooling can parse. GitHub's @username and #123 are the most direct analogues — they're inline in .md files, machine-parseable, human-readable, and no-ops in renderers that don't understand them.

@skill:privacy-scan follows exactly this model. Markdown renders it as plain text. Our tooling extracts it via regex. Readers understand it in context.

[krisrowe]

Rendering test results (empirical, GitHub markdown)

Tested on a GitHub-rendered .md file (private repo). Screenshot verified.

Syntax	Rendered as	Mention triggered?	Machine-parseable
@skill:privacy-scan (bare)	Plain text	No — colon breaks GitHub's mention parser	@skill:([a-z0-9-]+)
`@skill:privacy-scan` (backtick)	Code span (monospace)	No	Same regex inside backticks
[[skill:privacy-scan]]	Plain text (brackets literal)	No	Yes but ugly
#skill:privacy-scan	Plain text	No — colon breaks issue autolink	Conflict risk with #123
(skill:privacy-scan)	Plain text	No	Looks like a parenthetical
<skill:privacy-scan>	Plain text	No (on GitHub — risky in other renderers)	Yes
:privacy-scan:	Plain text	No	Conflicts with emoji :name: syntax
skill/privacy-scan	Plain text	No	Confused with file paths

Caveat

Tested on a private repo only. The @skill GitHub user exists (verified via API — user "Skill" with public repos). Public repo rendering may differ — GitHub may still notify the @Skill user even if the mention isn't rendered as a link. Must test on a public repo before adopting bare @skill:. Until then, backtick-wrapped `@skill:name` is the safe default.

Recommendation

• Bare @skill:name if public repo test confirms no mention/notification
• Backtick `@skill:name` as safe fallback (zero risk across all renderers)
• Regex for both: @skill:([a-z0-9-]+)

Action: migrate all research into repo documentation

This issue and its comments now contain substantial research that should not live only in GitHub comments. Before closing this issue, all findings must be migrated into appropriate .md files in the repo:

• CONTRIBUTING.md — the decided convention (syntax, regex, frontmatter field), with rationale
• docs/research/skill-reference-syntax.md (or similar) — the full research: ecosystem scan (agentskills.io, Claude Code, Gemini CLI, Vercel Labs), precedent analysis (@namespace:identifier pattern), rendering test results with screenshots, caveats about public repo testing
• develop-skill SKILL.md — update the skill authoring guide with the convention once adopted

Do not close this issue until the research is in the repo, not just in comments.

[krisrowe]

Complete frontmatter field inventory across all platforms

agentskills.io specification

Field	Required	Description
name	Yes	Max 64 chars. Lowercase letters, numbers, hyphens.
description	Yes	Max 1024 chars. What the skill does and when to use it.
license	No	License name or reference to bundled license file.
compatibility	No	Max 500 chars. Environment requirements (free text).
metadata	No	Arbitrary key-value mapping for custom extensions.
allowed-tools	No	Space-delimited list of pre-approved tools. (Experimental)

No dependency field. No tools:, skills:, depends:, requires:.

Claude Code skills

Field	Required	Description
name	No	Display name. Defaults to directory name.
description	Recommended	What the skill does and when to use it.
argument-hint	No	Hint shown during autocomplete.
disable-model-invocation	No	true prevents auto-loading.
user-invocable	No	false hides from / menu.
allowed-tools	No	Tools Claude can use without permission when skill is active.
model	No	Model to use when skill is active.
effort	No	Effort level override.
context	No	fork to run in a forked subagent.
agent	No	Subagent type when context: fork.
hooks	No	Hooks scoped to this skill.
paths	No	Glob patterns limiting auto-activation.
shell	No	bash (default) or powershell.

No dependency field. allowed-tools pre-approves but does not declare dependencies.

Claude Code sub-agents (for comparison)

Agents DO have skills: which preloads full skill content into context. But this is agent-level, not skill-to-skill. A skill cannot declare "I require skill X."

Agents also have tools: (allowlist) and disallowedTools: (denylist) — but these control what tools the agent can use, not dependencies.

Gemini CLI

Field	Required	Description
name	Yes	Skill name.
description	Yes	Primary triggering mechanism. Must be single-line.

Two fields only. Docs state: "Do not include any other fields in YAML frontmatter."

Conclusion

No platform supports skill-to-skill dependency declaration. The metadata map in agentskills.io is the only spec-compliant extensibility point. Any dependency convention we adopt (e.g., metadata.references + @skill:name inline) is our own invention, informed by precedent but not standardized.