| name | agent-compatibility |
| description | Verifies that a skill or workspace rule stays portable across AI agents. Provides a portability checklist for SKILL.md files and applies the portable/generated/agent-specific trichotomy for workspace rules. Use whenever creating or modifying skills, rules, or subagent prompts. |
Agent Compatibility
Skills authored in this repository are deployed to multiple agents via Nix (Cursor, Claude Code, Gemini CLI, Antigravity, Codex, Copilot, and any agent that scans ~/.agents/skills/). This skill ensures new or modified artifacts remain portable.
Portability checklist for SKILL.md files
Apply this checklist when creating or modifying any skill:
Frontmatter
- Use base spec fields.
name and description are required and universal. All 32+ SKILL.md-compatible agents read them.
- Accepted extensions.
disable-model-invocation, paths, and metadata are safe -- agents that don't recognise them silently ignore unknown fields.
- Avoid agent-specific-only fields that would break discovery in other agents. If you need an agent-specific field (e.g. Claude's
context: fork), verify it is ignored (not errored) by other agents before adding it.
Body content
- No hard references to agent-specific tools. Do not write "Call
SwitchMode" without a graceful degradation path. Instead: "If mode switching is available, use it; otherwise, state the constraint and proceed." The mode-gate skill already handles this pattern.
- Cross-references use the portable
**skill-name** pattern. Write "Follow the commit-conventions skill" rather than "Read ~/.cursor/skills/knowledge/commit-conventions/SKILL.md". All agents resolve skill references by name.
- No absolute paths to agent directories. Use relative references like "the canonical source at
home/file/agents/skills/" rather than ~/.cursor/skills/ or ~/.claude/skills/.
Supporting files
- POSIX-compatible scripts. If the skill includes
scripts/, use #!/usr/bin/env bash and POSIX utilities. Avoid agent-specific script APIs.
- Relative paths in references.
reference.md, guide.md, and other sibling files should be referenced with relative paths from the SKILL.md.
Trichotomy for workspace rules
When a skill creates or references workspace rules, classify each asset:
| Category | What to do | Example |
|---|
| Portable | Content that works in plain markdown for any agent. Deploy to AGENTS.md at repo root. | Coding conventions, build commands, architecture notes |
| Generated | Same intent, different format per agent. Author once, render into each format. | .cursor/rules/*.mdc (with globs:) and .claude/rules/*.md (with paths:) |
| Agent-specific | Unique to one agent, no equivalent elsewhere. Keep in the agent's native directory. | Cursor alwaysApply: true, Claude @import syntax |
See the workspace-rules skill for the full decision process and format examples.
Deployment verification
After creating or modifying a skill in this dotfiles repo:
- Verify the file is under
home/file/agents/skills/ (not a stale home/file/cursor/ path).
- Nix deployment fans out skills to:
~/.agents/skills/, ~/.cursor/skills/, ~/.claude/skills/, ~/.gemini/skills/. Codex reads ~/.agents/skills/ natively; Copilot reads ~/.copilot/skills/.
- The
AGENTS.md is deployed to: ~/.agents/AGENTS.md, ~/.gemini/AGENTS.md, ~/.codex/AGENTS.md. Codex, Gemini CLI, and Antigravity read these at session start.
- The
CLAUDE.md at ~/.claude/CLAUDE.md imports @~/.agents/AGENTS.md for Claude Code.
- Copilot (Agent mode) reads
AGENTS.md at repo root; no separate global deployment is needed beyond the repo-root file.
