AI Skills Organization with Symbolic Links

A comprehensive guide to organizing AI coding assistant skills using symbolic links for better project structure and compatibility.

Why Use Symbolic Links
Project Structure
Setup Scripts
Step-by-Step Guide
Example Skills
Troubleshooting

Why Use Symbolic Links?

The Problem

Many AI coding assistants (Claude Code, Cursor, GitHub Copilot) look for project-specific instructions in different locations:

Some use .ai-rules/
Some use .agent/
Some use .cursor/
Some use custom directories

Managing the same skills across multiple directories leads to:

❌ Duplication of content
❌ Synchronization issues
❌ Maintenance overhead

The Solution

Use symbolic links to create a single source of truth:

project/
├── .ai-rules/           ← Source (single source of truth)
│   ├── skill-1.md
│   └── skill-2.md
│
└── .agent/
    └── skills/          ← Symbolic link → ../.ai-rules
        ├── skill-1.md   (accessed via link)
        └── skill-2.md   (accessed via link)

Benefits:

✅ No duplication
✅ Single location to maintain
✅ Compatible with multiple tools
✅ Easy to update

Project Structure

Before Setup

my-todo-app/
├── src/
├── tests/
├── package.json
└── .ai-rules/           ← Your skills directory
    ├── README.md
    ├── api-development.md
    ├── testing-guide.md
    └── ui-patterns.md

After Setup

my-todo-app/
├── src/
├── tests/
├── package.json
├── .ai-rules/                    ← Original files
│   ├── README.md
│   ├── api-development.md
│   ├── testing-guide.md
│   └── ui-patterns.md
│
├── .agent/
│   └── skills/                   ← Symbolic link
│       ├── README.md             (link)
│       ├── api-development.md    (link)
│       ├── testing-guide.md      (link)
│       └── ui-patterns.md        (link)
│
├── setup-skills-link.ps1         ← Setup script
└── setup-skills-link.bat         ← Alternative script

Setup Scripts

PowerShell Script (Recommended)

Create setup-skills-link.ps1:

# AI Skills Symbolic Link Setup
Write-Host "Setting up AI Skills symbolic link..." -ForegroundColor Cyan

# Check admin privileges
$isAdmin = ([Security.Principal.WindowsPrincipal] [Security.Principal.WindowsIdentity]::GetCurrent()).IsInRole([Security.Principal.WindowsBuiltInRole]::Administrator)

if (-not $isAdmin) {
    Write-Host "ERROR: Run as Administrator" -ForegroundColor Red
    Read-Host "Press Enter to exit"
    exit 1
}

# Get paths
$scriptPath = Split-Path -Parent $MyInvocation.MyCommand.Path
$sourceDir = Join-Path $scriptPath ".ai-rules"
$targetParent = Join-Path $scriptPath ".agent"
$targetLink = Join-Path $targetParent "skills"

# Verify source exists
if (-not (Test-Path $sourceDir)) {
    Write-Host "ERROR: .ai-rules directory not found" -ForegroundColor Red
    exit 1
}

# Create .agent directory if needed
if (-not (Test-Path $targetParent)) {
    New-Item -ItemType Directory -Path $targetParent | Out-Null
}

# Remove existing link if present
if (Test-Path $targetLink) {
    $item = Get-Item $targetLink -Force
    if ($item.Attributes -band [System.IO.FileAttributes]::ReparsePoint) {
        Remove-Item $targetLink -Force
    } else {
        Write-Host "ERROR: $targetLink exists but is not a symbolic link" -ForegroundColor Red
        exit 1
    }
}

# Create symbolic link
try {
    New-Item -ItemType SymbolicLink -Path $targetLink -Target $sourceDir | Out-Null
    Write-Host "SUCCESS: Symbolic link created!" -ForegroundColor Green
    Write-Host "  .agent/skills -> .ai-rules" -ForegroundColor Gray
} catch {
    Write-Host "ERROR: Failed to create link: $_" -ForegroundColor Red
    Write-Host "TIP: Enable Developer Mode in Windows Settings" -ForegroundColor Yellow
    exit 1
}

Read-Host "Press Enter to exit"

Batch Script Alternative

Create setup-skills-link.bat:

@echo off
echo Setting up AI Skills symbolic link...

net session >nul 2>&1
if %errorLevel% neq 0 (
    echo ERROR: Run as Administrator
    pause
    exit /b 1
)

set "SOURCE_DIR=%~dp0.ai-rules"
set "TARGET_PARENT=%~dp0.agent"
set "TARGET_LINK=%TARGET_PARENT%\skills"

if not exist "%SOURCE_DIR%" (
    echo ERROR: .ai-rules directory not found
    pause
    exit /b 1
)

if not exist "%TARGET_PARENT%" (
    mkdir "%TARGET_PARENT%"
)

if exist "%TARGET_LINK%" (
    rmdir "%TARGET_LINK%" 2>nul
)

mklink /D "%TARGET_LINK%" "%SOURCE_DIR%"
if %errorLevel% neq 0 (
    echo ERROR: Failed to create symbolic link
    echo TIP: Enable Developer Mode in Windows Settings
    pause
    exit /b 1
)

echo SUCCESS: Symbolic link created!
pause

Step-by-Step Guide

Step 1: Create Your Skills Directory

1
2
3

# In your project root
mkdir .ai-rules
cd .ai-rules

Create sample skills (examples below).

Step 2: Create Setup Script

Copy one of the scripts above and save as:

setup-skills-link.ps1 (PowerShell)
setup-skills-link.bat (Batch)

Step 3: Enable Developer Mode (Windows)

Optional but recommended - Makes symbolic link creation easier:

Open Settings
Go to Update & Security → For developers
Enable Developer Mode
Restart if prompted

Step 4: Run Setup Script

PowerShell (Recommended):

1
2
3

# Right-click PowerShell → "Run as Administrator"
cd path\to\your\project
.\setup-skills-link.ps1

Batch:

1	# Right-click setup-skills-link.bat → "Run as administrator"

Step 5: Verify Setup

# Check link exists
dir .agent\skills

# Should show: <SYMLINKD>     skills [..\..\.ai-rules]

# Verify files accessible
dir .agent\skills\*.md

Step 6: Update .gitignore

Add to .gitignore:

# Ignore symbolic link (source is .ai-rules/)
.agent/skills

# Keep original skills
!.ai-rules/

Example Skills

Minimal Skill Structure

Create these files in .ai-rules/:

1. `README.md`

# Project Skills

AI coding assistant skills for this project.

## Available Skills

- `api-development.md` - REST API development patterns
- `testing-guide.md` - Testing strategy and examples
- `ui-patterns.md` - UI component patterns

## Usage

Reference in prompts:
```markdown
Follow @.agent/skills/api-development.md


#### 2. `api-development.md`

```markdown
# API Development Skill

## REST Endpoint Pattern

### Structure
```python
@app.route('/api/resource', methods=['POST'])
def create_resource():
    try:
        data = request.get_json()

        # Validate
        if not data or 'name' not in data:
            return jsonify({'error': 'Invalid data'}), 400

        # Process
        resource = Resource(name=data['name'])
        db.session.add(resource)
        db.session.commit()

        return jsonify({'id': resource.id, 'name': resource.name}), 201

    except Exception as e:
        db.session.rollback()
        return jsonify({'error': str(e)}), 500

Rules

Always validate input
Use try/except with rollback
Return consistent JSON format
Include HTTP status codes

Testing

1
2
3

curl -X POST http://localhost:5000/api/resource \
  -H "Content-Type: application/json" \
  -d '{"name":"Test"}'


#### 3. `testing-guide.md`

```markdown
# Testing Guide

## Test Structure

```python
import pytest
from app import create_app, db

@pytest.fixture
def client():
    app = create_app('testing')
    with app.test_client() as client:
        with app.app_context():
            db.create_all()
            yield client
            db.drop_all()

def test_create_resource(client):
    response = client.post('/api/resource',
        json={'name': 'Test Resource'})

    assert response.status_code == 201
    assert 'id' in response.json
    assert response.json['name'] == 'Test Resource'

Running Tests

# All tests
pytest

# Specific file
pytest tests/test_api.py

# With coverage
pytest --cov=app tests/

Test Checklist

Happy path works
Invalid input handled
Edge cases covered
Error responses correct


#### 4. `ui-patterns.md`

```markdown
# UI Component Patterns

## Standard Button

```jsx
<button className="btn btn-primary">
  Submit
</button>

Form Input

<div className="form-group">
  <label>Name</label>
  <input
    type="text"
    className="form-control"
    value={name}
    onChange={(e) => setName(e.target.value)}
  />
</div>

Loading State

{isLoading ? (
  <div className="spinner">Loading...</div>
) : (
  <div className="content">{data}</div>
)}

Color Palette

Primary: #007bff
Success: #28a745
Danger: #dc3545
Warning: #ffc107


---

## Using Skills in AI Tools

### Claude Code

```markdown
Create a new API endpoint following @.agent/skills/api-development.md

Cursor

Skills in .agent/ are automatically indexed. Reference directly:

1	Follow the testing patterns in api-development.md

GitHub Copilot

1 2	// Follow .agent/skills/testing-guide.md // Implement test for user creation

Generic Reference

1	See: .agent/skills/ui-patterns.md for button styling

Troubleshooting

Issue 1: “Permission Denied”

Cause: Not running as Administrator

Solution:

Right-click script → “Run as administrator”
Or enable Developer Mode in Windows Settings

Issue 2: “Cannot create symbolic link”

Cause: Windows policy restriction

Solution 1 - Enable Developer Mode:

Settings → Update & Security → For developers → Developer Mode

Solution 2 - Modify Group Policy:

1. Run: gpedit.msc
2. Navigate: Computer Configuration → Windows Settings → Security Settings → Local Policies → User Rights Assignment
3. Find: "Create symbolic links"
4. Add your user account

Issue 3: Link Created but Files Not Accessible

Verify link:

1 2	dir .agent\skills # Should show: <SYMLINKD>

Recreate link:

# Delete
rmdir .agent\skills

# Recreate
.\setup-skills-link.ps1

Issue 4: Works on Windows but Not on Git

Problem: Git may not clone symbolic links correctly

Solution: Add setup to README:

## Setup After Clone

Windows users:
```powershell
.\setup-skills-link.ps1

Linux/Mac users:

1	ln -s .ai-rules .agent/skills


---

## Platform-Specific Notes

### Windows

**Requirements**:
- Administrator privileges OR
- Developer Mode enabled

**Command**:
```cmd
mklink /D target source

Linux / macOS

No special requirements - standard feature

Command:

1	ln -s source target

In your project:

1 2	cd .agent ln -s ../.ai-rules skills

WSL (Windows Subsystem for Linux)

Works like Linux:

1 2	cd .agent ln -s ../.ai-rules skills

Advanced: Multiple Link Targets

You can create links to the same source from multiple locations:

project/
├── .ai-rules/              ← Source
│
├── .agent/
│   └── skills/             ← Link 1
│
├── .cursor/
│   └── skills/             ← Link 2
│
└── .github/
    └── copilot/
        └── skills/         ← Link 3

All point to same source, maximum compatibility!

Best Practices

1. Single Source of Truth

✅ DO: Edit files in .ai-rules/
❌ DON’T: Edit through symbolic link

2. Version Control

✅ DO: Commit .ai-rules/
❌ DON’T: Commit .agent/skills/

3. Documentation

✅ DO: Document setup in README
❌ DON’T: Assume everyone knows about symbolic links

4. Team Setup

Add to project README:

## First-Time Setup

After cloning, create symbolic links:

```powershell
# Windows (as Administrator)
.\setup-skills-link.ps1

1 2	# Linux/Mac ln -s .ai-rules .agent/skills


---

## Example Project: Todo App

Complete example structure:

todo-app/
├── .ai-rules/
│ ├── README.md
│ ├── api-endpoints.md ← REST API patterns
│ ├── database-models.md ← SQLAlchemy models
│ ├── frontend-components.md ← React patterns
│ ├── testing-strategy.md ← Pytest patterns
│ └── deployment.md ← Docker/CI/CD
│
├── .agent/
│ └── skills/ → symbolic link to .ai-rules
│
├── src/
│ ├── api/
│ ├── components/
│ └── models/
│
├── tests/
├── .gitignore
├── setup-skills-link.ps1
└── README.md


**Usage in development**:
```markdown
# In AI assistant prompt
Create a new Todo model following @.agent/skills/database-models.md

Add a React component for the todo list using patterns from @.agent/skills/frontend-components.md

Write tests following @.agent/skills/testing-strategy.md

Quick Start Checklist

Create .ai-rules/ directory
Add skill files (markdown)
Create setup-skills-link.ps1
Run script as Administrator
Verify link: dir .agent\skills
Update .gitignore
Commit .ai-rules/ to git
Document setup in README

Resources

Script Templates

All scripts in this tutorial are production-ready. Copy and adapt for your project.

Directory Names

Common conventions:

.ai-rules/ - General AI instructions
.agent/ - Agent-specific config
.cursor/ - Cursor IDE
.github/copilot/ - GitHub Copilot

Choose what works for your tools.

License

This tutorial and all scripts are released under MIT License. Use freely in your projects.

Contributing

Found an issue or improvement? This is a reference document - adapt it to your needs!