Skip to main content

​
Linking Commands

Linking commands create symlinks between skills and AI agent workspaces, making skills discoverable by agents. Link a skill to all detected AI agent workspaces. 
tank link
Run from a skill directory (directory containing skills.json).

​
Linking Flow

  1. Read skills.json to get skill name
  2. Detect installed AI agents on the system
  3. Create wrapper directory with frontmatter (if SKILL.md exists)
  4. Create symlinks in each agent’s skills directory
  5. Record links in ~/.tank/links.json

​
Example Output

$ cd my-skill
$ tank link
✓ OpenCode
✓ Cursor
✓ Windsurf
✓ Linked my-skill to 3 agent(s)

​
Detected Agents

Tank automatically detects these agents:
  • OpenCode - ~/.config/opencode/skills/
  • Cursor - ~/.cursor/skills/
  • Windsurf - ~/.windsurf/skills/
  • Cline - ~/.cline/skills/
  • Continue - ~/.continue/skills/
See source: apps/cli/src/lib/agents.ts:10

​
No Agents Detected

If no agents are installed: 
$ tank link
ℹ No AI agents detected. Skills linked to agents will be available once agents are installed.
Install an agent and run tank link again.

​
Already Linked

If skill is already linked to an agent: 
$ tank link
⚠ - OpenCode (already linked)
✓ Cursor
✓ Linked my-skill to 1 agent(s)

​
Frontmatter Generation

If your skill has a SKILL.md file without frontmatter, Tank generates a wrapper:

​
Before (SKILL.md)

# My Skill

This skill does amazing things.

​
After (agent-skills/my-skill/SKILL.md)

---
name: my-skill
description: AI skill for data processing
---

# My Skill

This skill does amazing things.
The wrapper directory is created in ~/.tank/agent-skills/ and symlinked to agent directories.

​
Custom Frontmatter

If SKILL.md already has frontmatter, Tank uses it as-is: 
---
name: my-custom-skill
description: Custom description
author: Alice Developer
version: 1.0.0
---

# My Custom Skill
No wrapper is created; the skill directory is linked directly.

​
Development Linking

~/my-skill/                     # Your skill directory
  ├── skills.json
  └── SKILL.md

~/.tank/
  ├── agent-skills/
  │   └── my-skill/             # Wrapper with frontmatter
  │       └── SKILL.md          # Generated frontmatter + content
  └── links.json                # Link registry

~/.config/opencode/skills/
  └── my-skill -> ~/.tank/agent-skills/my-skill  # Symlink

​
Global Installation Linking

For globally installed skills: 
~/.tank/
  ├── skills/
  │   └── @acme/
  │       └── analytics/        # Extracted skill files
  ├── agent-skills/
  │   └── acme-analytics/       # Wrapper with frontmatter
  └── links.json                # Link registry

~/.config/opencode/skills/
  └── acme-analytics -> ~/.tank/agent-skills/acme-analytics
Remove skill symlinks from all agent workspaces. 
tank unlink
Run from a skill directory (directory containing skills.json).

​
Example Output

$ cd my-skill
$ tank unlink
✓ Unlinked my-skill from 3 agent(s)
If skill is not linked: 
$ tank unlink
ℹ No links found for my-skill

​
Cleanup

Unlinking:
  • Removes symlinks from agent directories
  • Deletes wrapper directory from ~/.tank/agent-skills/
  • Updates ~/.tank/links.json
Tank tracks links in ~/.tank/links.json: 
{
  "links": {
    "my-skill": {
      "source": "dev",
      "sourceDir": "/home/alice/my-skill",
      "agents": ["opencode", "cursor", "windsurf"]
    },
    "@acme/analytics": {
      "source": "global",
      "sourceDir": "/home/alice/.tank/skills/@acme/analytics",
      "agents": ["opencode"]
    }
  }
}
  • dev - Development link from local directory (tank link)
  • global - Global installation link (tank install --global)
  • local - Project installation link (tank install)

​
Automatic Linking

Tank automatically links skills during installation: 
$ tank install @acme/analytics
⠹ Installing @acme/[email protected]...
ℹ Linked to 2 agent(s)
✓ Installed @acme/[email protected]

$ tank install @acme/analytics --global
⠹ Installing @acme/[email protected]...
ℹ Linked to 3 agent(s)
✓ Installed @acme/[email protected]
No need to run tank link manually after install.

​
Automatic Unlinking

Tank automatically unlinks during removal: 
$ tank remove @acme/analytics
ℹ Unlinked from 2 agent(s)
✓ Removed @acme/analytics

​
Same Skill, Different Sources

If you link a dev version while a global version is installed: 
$ tank link
⚠ - OpenCode (already linked)
Tank skips the link to avoid conflicts. To override:
  1. Unlink the existing link: tank unlink (from global install)
  2. Link your dev version: tank link

​
Scoped Packages

Scoped packages (@org/skill) are symlinked with flattened names: 
@acme/analytics → acme-analytics
@org-name/processor → org-name-processor
This avoids filesystem issues with @ and / in symlink names.

​
Testing Skills Locally

Use tank link to test skills during development: 
# 1. Create skill
mkdir my-skill
cd my-skill
tank init

# 2. Add SKILL.md
echo '# My Skill\n\nTest skill.' > SKILL.md

# 3. Link to agents
tank link

# 4. Test in agent (e.g., OpenCode)
# Open OpenCode, skill should appear in skills list

# 5. Make changes to SKILL.md
# Changes are immediately visible (symlinked)

# 6. Unlink when done
tank unlink

​
Agent Compatibility

All agents must support the Tank skill format:
  • SKILL.md with frontmatter
  • name field in frontmatter
  • Optional description, author, version fields
See Skills for skill format details.

​
Troubleshooting

​
Permission Denied

✗ Failed to link to opencode: EACCES: permission denied
Fix: Check directory permissions on ~/.config/opencode/skills/. 
⚠ - OpenCode (already linked)
Fix: Run tank unlink first, then tank link again.

​
No skills.json

✗ No skills.json found. Run this command from a skill directory.
Fix: Run tank link from a directory with skills.json, or run tank init first.

​
Agent Not Detected

If Tank doesn’t detect your agent:
  1. Check agent config directory exists: 
    ls ~/.config/opencode/skills/
  2. Manually verify agent detection: 
    node -e "console.log(require('os').homedir())"
  3. Check Tank’s agent detection logic: See apps/cli/src/lib/agents.ts:10
If linking fails for a specific agent, Tank continues: 
✓ OpenCode
✓ Cursor
⚠ Failed to link to windsurf: ENOENT: no such file or directory
✓ Linked my-skill to 2 agent(s)
This is non-fatal; skills are still available in successfully linked agents.

Build docs developers (and LLMs) love

Get started for freeTalk to us