# Cross-Link Syntax Reference

This guide explains how to create effective cross-links between documentation skills and application skills for seamless discovery.

## Core Principles

**1. Bidirectional Linking**
- Docs skill → Application skills (for patterns and usage)
- Application skills → Docs skill (for syntax reference)
- Each skill should know about related skills

**2. Context-Appropriate**
- Link to docs skill for syntax, API reference, concepts
- Link to application skills for patterns, examples, workflows
- Don't duplicate content - link instead

**3. Grep-Driven**
- Include `rg` commands that point to exact locations
- Make links actionable with copy-pasteable grep patterns
- Show users HOW to find, not just WHERE to look

## Syntax Patterns

### From Docs Skill → Application Skills

**Pattern 1: Cross-Reference Section**

```markdown
## Cross-References to Application Skills

### tech-patterns
**Use this skill for**: Basic patterns, common workflows, [framework] integration

**When to cross-reference:**
- Implementing basic features
- Following common patterns
- [Framework]-specific integration

### tech-advanced
**Use this skill for**: Advanced patterns, optimization, performance tuning

**When to cross-reference:**
- Performance optimization
- Complex architectures
- Edge cases and gotchas

### tech-integration
**Use this skill for**: Third-party integrations, [ecosystem] patterns

**When to cross-reference:**
- Integrating with [tool/framework]
- Multi-service architectures
- Cross-platform development
```

**Why this works:**
- Clear skill boundaries
- Explicit use cases
- Users know when to switch skills

**Pattern 2: Inline Cross-References**

```markdown
### Guides (`references/guides/`)

Comprehensive guides covering:
- Getting Started
- Core Concepts
- Best Practices

**Quick grep patterns:**
\```bash
# Getting started
rg "getting started\\|quickstart" references/guides/ -i -l | head -5

# Best practices
rg "best practice\\|recommended" references/guides/ -i -l
\```

**For [Framework]-based patterns using these concepts**, see **tech-patterns skill**.
```

**Why this works:**
- Links appear at natural points
- Contextual - users see link when they need it
- Clearly states what the linked skill provides

### From Application Skills → Docs Skill

**Pattern 1: Quick Pattern Reference Section**

```markdown
## Quick Pattern Reference

**When to use tech-docs:**
- Syntax reference: `rg "KEYWORD" ../tech-docs/references/api-reference/`
- Function reference: `rg "functionName" ../tech-docs/references/`
- Complete guides: `rg "concept" ../tech-docs/references/guides/ -i -l`

**When to use this skill:**
- [Framework]-based patterns
- Common workflows with [Framework]
- Type-safe operations
- Error handling patterns
- Best practices
```

**Why this works:**
- Sets clear skill boundaries upfront
- Provides grep commands for immediate use
- Shows relative path syntax (`../tech-docs/`)

**Pattern 2: Cross-Reference Guide Section**

```markdown
## Cross-Reference Guide

### Syntax Reference → tech-docs

For complete [Technology] syntax, use tech-docs references:

\```bash
# Data types
rg "INT64\\|STRING\\|TIMESTAMP" ../tech-docs/references/api-reference/data-types.md

# Functions
rg "JSON_VALUE\\|ARRAY_AGG" ../tech-docs/references/api-reference/json_functions.md

# DDL syntax
rg "CREATE TABLE\\|ALTER TABLE" ../tech-docs/references/api-reference/data-definition-language.md
\```

### Guides → tech-docs

For conceptual understanding and best practices:

\```bash
# Schema design
rg "primary key\\|index" ../tech-docs/references/guides/ -i -l | head -5

# Query optimization
rg "query plan\\|optimizer" ../tech-docs/references/guides/ -i -l

# Transaction patterns
rg "read-write\\|serializable" ../tech-docs/references/guides/ -i -l
\```
```

**Why this works:**
- Organized by documentation type
- Shows exact grep commands users can run
- Uses relative paths that work from application skill location

**Pattern 3: Inline "See Also" Links**

```markdown
### Basic Pattern 1: Query Execution

\```typescript
const getUser = (client: SpannerGraphClient, userId: string) =>
  Effect.gen(function* () {
    const result = yield* client.sql<{ user: unknown }>`
      SELECT id, email, created_at
      FROM Users
      WHERE id = ${userId}
    `.pipe(Effect.orDie)

    return yield* Schema.decodeUnknown(User)(result.user).pipe(
      Effect.orDie
    )
  })
\```

**Key patterns:**
- Use template literals for parameterized queries
- Always decode query results with `@effect/schema`
- Use `.pipe(Effect.orDie)` for queries that must succeed

**For complete SQL syntax**, see tech-docs: `rg "SELECT.*FROM" ../tech-docs/references/api-reference/`
```

**Why this works:**
- Link appears at point of need
- Provides specific grep pattern for relevant docs
- Doesn't interrupt pattern explanation

## Relative Path Conventions

### Directory Structure Assumption

```
your-plugin/
├── tech-docs/
│   └── references/
└── tech-patterns/
    └── SKILL.md  ← You are here
```

### From Application Skill to Docs Skill

```bash
# From tech-patterns/ to tech-docs/references/
rg "pattern" ../tech-docs/references/

# From tech-advanced/ to tech-docs/references/guides/
rg "pattern" ../tech-docs/references/guides/

# From tech-integration/ to tech-docs/references/samples/
rg "pattern" ../tech-docs/references/samples/
```

**Pattern:** `../tech-docs/references/[category]/`

### From Docs Skill to Application Skills

Docs skill doesn't execute grep, it describes:

```markdown
### tech-patterns
**Use this skill for**: Basic patterns, common workflows

**Example patterns:**
- Repository pattern with SpannerGraphClient
- Effect.gen query execution
- Schema validation
```

**Pattern:** Describe, don't link (docs skill is passive)

## Cross-Link Anti-Patterns

### ❌ Don't: Duplicate Content

**WRONG:**

```markdown
<!-- In tech-patterns SKILL.md -->
## SQL Function Reference

Here are all the SQL functions... [3000 lines]
```

**RIGHT:**

```markdown
<!-- In tech-patterns SKILL.md -->
## SQL Function Reference → tech-docs

For complete SQL function syntax, see tech-docs:

\```bash
rg "JSON_VALUE" ../tech-docs/references/api-reference/json_functions.md
\```
```

### ❌ Don't: Vague Cross-References

**WRONG:**

```markdown
For more info, see tech-docs skill.
```

**RIGHT:**

```markdown
For complete GQL syntax reference, run:
\```bash
rg "MATCH.*WHERE.*RETURN" ../tech-docs/references/api-reference/gql-query-statements.md
\```
```

### ❌ Don't: Circular Dependencies

**WRONG:**

```markdown
<!-- tech-patterns SKILL.md -->
For patterns, see tech-advanced.

<!-- tech-advanced SKILL.md -->
For patterns, see tech-patterns.
```

**RIGHT:**

```markdown
<!-- tech-patterns SKILL.md -->
For advanced optimization patterns, see tech-advanced.

<!-- tech-advanced SKILL.md -->
Assumes familiarity with basic patterns from tech-patterns.
```

### ❌ Don't: Absolute Paths

**WRONG:**

```bash
rg "pattern" /path/to/tech-docs/references/
```

**RIGHT:**

```bash
rg "pattern" ../tech-docs/references/
```

### ✅ Do: Provide Actionable Grep Commands

**GOOD:**

```markdown
### Finding Transaction Patterns → tech-docs

\```bash
# Read-write transactions
rg "BEGIN TRANSACTION\\|COMMIT" ../tech-docs/references/guides/ -A5

# Transaction isolation levels
rg "SERIALIZABLE\\|SNAPSHOT" ../tech-docs/references/guides/ -i -l

# Retry logic
rg "aborted.*retry" ../tech-docs/references/guides/ -i -A3
\```
```

### ✅ Do: Show When to Switch Skills

**GOOD:**

```markdown
## When to Use Which Skill

**Use tech-docs when you need:**
- Exact SQL syntax for a function
- Complete API reference
- Official documentation quotes

**Use tech-patterns when you need:**
- Effect-based query execution
- Repository pattern examples
- Common workflows

**Use tech-advanced when you need:**
- Performance tuning strategies
- Complex optimization scenarios
- Edge case handling
```

## Examples from Spanner Mastery

### Docs Skill Cross-Links

```markdown
<!-- spanner-docs/SKILL.md -->

## Cross-References to Application Skills

### spanner-googlesql
**Use this skill for**: GoogleSQL query patterns, function usage, Effect-based SQL execution

**When to cross-reference:**
- Writing SQL queries with Effect
- Repository pattern implementation
- Type-safe database operations

### spanner-gql
**Use this skill for**: Graph Query Language patterns, GQL execution, schemaless graph patterns

**When to cross-reference:**
- Writing graph traversals
- Implementing graph repositories
- Working with property graph data
```

### Application Skill Cross-Links

```markdown
<!-- spanner-googlesql/SKILL.md -->

## Quick Pattern Reference

**When to use spanner-docs:**
- Syntax reference: `rg "CREATE TABLE" ../spanner-docs/references/googlesql/references/`
- Function reference: `rg "JSON_VALUE" ../spanner-docs/references/googlesql/references/`
- Complete guides: `rg "schema design" ../spanner-docs/references/guides/ -i -l`

**When to use this skill:**
- Effect-based query execution patterns
- Repository implementation with SpannerGraphClient
- Type-safe Schema decoding from query results
- Transaction management with Effect
- Error handling and retry logic

## Cross-Reference Guide

### Syntax Reference → spanner-docs

For complete GoogleSQL syntax, use spanner-docs references:

\```bash
# Data types
rg "INT64\\|STRING\\|TIMESTAMP" ../spanner-docs/references/googlesql/references/data-types.md

# Functions
rg "JSON_VALUE\\|ARRAY_AGG" ../spanner-docs/references/googlesql/references/json_functions.md

# DDL syntax
rg "CREATE TABLE\\|ALTER TABLE" ../spanner-docs/references/googlesql/references/data-definition-language.md
\```
```

## Testing Cross-Links

### Verify Relative Paths Work

```bash
# From tech-patterns/ directory
cd plugins/your-plugin/tech-patterns/

# Test the grep command
rg "pattern" ../tech-docs/references/ -l | head -5

# Should return results - if not, fix the path
```

### Verify Grep Patterns Match

```bash
# Run the exact grep command from your SKILL.md
rg "JSON_VALUE" ../tech-docs/references/api-reference/

# Should return relevant results
# If empty, pattern needs refinement
```

### Verify Skill Boundaries Are Clear

```bash
# Check that docs skill doesn't include patterns
grep -c "Effect.gen" tech-docs/SKILL.md
# Should be 0 or very low

# Check that application skill references docs
grep -c "rg.*../tech-docs" tech-patterns/SKILL.md
# Should be 5-10+
```

## Summary

**Best practices for cross-linking:**

1. **Bidirectional**: Docs ↔ Application skills both link
2. **Actionable**: Provide exact grep commands users can run
3. **Relative paths**: Use `../skill-name/` notation
4. **Contextual**: Link at points where users need the information
5. **Clear boundaries**: Explicitly state what each skill provides
6. **No duplication**: Link instead of copying content
7. **Grep-driven**: Make discovery easy with specific patterns
8. **Tested**: Verify all grep commands actually work

**Remember:** Good cross-links make the plugin feel like one cohesive system, not isolated skills. Users should effortlessly move between skills following their workflow.
