AGENTS.md

1# Agent Skills
2 
3Shared n8n skills live in `.agents/skills`. These are the canonical source for
4skills that should work across Claude Code, OpenCode, and future agent harnesses.
5 
6## Layout
7 
8- Shared skills: `.agents/skills/<name>/SKILL.md`
9- Claude-specific skills and overrides: `.claude/plugins/n8n/skills/<name>/`
10- OpenCode-specific skills and overrides: `.opencode/skills/<name>/`
11 
12Claude plugin skills should usually be symlinks back to `.agents/skills`.
13OpenCode discovers `.agents/skills` directly, so `.opencode/skills` should only
14contain OpenCode-specific real-directory overrides.
15 
16Real directories in a harness path are treated as intentional overrides and are
17preserved by the sync script. The sync script only prunes symlinks that point
18back into `.agents/skills` (stale shared-skill links); hand-placed symlinks
19pointing elsewhere are left untouched.
20 
21The Claude plugin links are git symlinks, so a checkout needs symlink support.
22On Windows, enable it (`git config core.symlinks true`, plus Developer Mode or
23WSL) before checking out — otherwise git writes the links as plain text stubs
24and Claude Code fails to load those skills. `--check` reports stubs with an
25actionable error. (OpenCode reads `.agents/skills` directly and is unaffected.)
26 
27## Editing
28 
29- Edit shared skills under `.agents/skills`, not through symlinked copies.
30- Only put a skill in `.agents/skills` if it can work across supported agent
31  harnesses. Avoid hardcoded harness tool names, commands, or UI flows unless
32  the skill includes a clear availability check and fallback.
33- Keep harness-specific commands out of shared skills unless guarded by clear
34  tool availability checks.
35- Put harness-specific workflows, such as MCP setup commands, in real
36  directories under the matching harness path.
37- Run `pnpm sync:skill-links` after adding or removing shared skills to update
38  Claude plugin symlinks.
39- Run `pnpm check:skill-links` before submitting changes.
40