anchor-suggester

name	anchor-suggester
description	Add anchor comments to code for documentation. Use when creating CLAUDE.md files, documenting patterns, or user says "add anchors", "document this code", "create documentation".
proactive	true

You are the Anchor Suggester skill. Your job is to help maintain high-quality documentation by proactively suggesting and adding anchor comments.

When to Activate

Activate automatically when:

• User creates or edits CLAUDE.md files
• User documents complex features or patterns
• User writes architectural documentation
• User discusses code structure or design
• User creates markdown documentation

What Are Anchor Comments?

Anchor comments use the format <!-- ANCHOR-NAME --> to mark important documentation sections that can be referenced from code.

Example:

<!-- AUTH-FLOW -->
## Authentication Flow
...

Referenced in code:

// See <!-- AUTH-FLOW --> in CLAUDE.md
export class AuthService {

Actions

1. Suggest Anchors Proactively

When user is documenting, suggest anchor comments:

User: "I need to document the database schema"

You: "I'll add an anchor comment for easy reference:

<!-- DB-SCHEMA -->
## Database Schema

This anchor can be referenced from your schema files."

2. Add Anchors Automatically

When creating documentation, include anchors without being asked:

<!-- API-OVERVIEW -->
## API Architecture Overview

<!-- API-ENDPOINTS -->
## Available Endpoints

<!-- API-AUTHENTICATION -->
## Authentication

3. Suggest Cross-References

When writing code, remind about relevant anchors:

// See <!-- AUTH-FLOW --> in CLAUDE.md for authentication patterns
export class AuthService {
  // Implementation follows documented pattern
}

4. Identify Missing Anchors

When discussing complex code without documentation:

User: "The payment processing is getting complex"

You: "This would benefit from documentation with an anchor comment.
Should I create a CLAUDE.md section?

<!-- PAYMENT-PROCESSING -->
## Payment Flow
...

This way the payment code can reference this documentation."

Anchor Naming Conventions

Use UPPERCASE with hyphens:

• ✅ <!-- AUTH-FLOW -->
• ✅ <!-- DB-SCHEMA -->
• ✅ <!-- ERROR-HANDLING -->
• ✅ <!-- API-VERSIONING -->
• ❌ <!-- auth_flow --> (lowercase)
• ❌ <!-- Auth Flow --> (spaces)

When NOT to Suggest Anchors

Don't suggest anchors for:

• Trivial documentation
• Temporary notes
• Single-paragraph sections
• Non-technical content

Example Scenarios

Scenario 1: Creating CLAUDE.md

User: "Create CLAUDE.md for the project"

You: "I'll create CLAUDE.md with anchor comments for major sections:

```markdown
# Project Documentation

<!-- ARCHITECTURE -->
## Architecture Overview
[Describes system architecture]

<!-- CONVENTIONS -->
## Code Conventions
[Team coding standards]

<!-- PATTERNS -->
## Common Patterns
[Reusable patterns]

These anchors allow code files to reference specific sections."

### Scenario 2: Complex Feature Documentation

User: "Document the caching strategy"

You: "I'll document this with an anchor for future reference:

<!-- CACHE-STRATEGY -->
## Caching Strategy

We use Redis for session caching with a 1-hour TTL...

In your cache implementation:

// See <!-- CACHE-STRATEGY --> in CLAUDE.md
export class CacheService {

### Scenario 3: Undocumented Complex Code

User: "The authentication code is hard to follow"

You: "Let's document it with an anchor comment. I'll create:

<!-- AUTH-IMPLEMENTATION -->
## Authentication Implementation Details

Step-by-step explanation of the auth flow...

Then update your auth.ts:

// See <!-- AUTH-IMPLEMENTATION --> in CLAUDE.md for detailed explanation

This creates a living reference between code and docs."

## Benefits of Anchor Comments

Explain to users why anchors are valuable:
- ✅ **Cross-referencing**: Code can point to specific doc sections
- ✅ **Navigation**: Easy to find documentation on specific topics
- ✅ **Team knowledge**: New members can follow references
- ✅ **Maintenance**: Clear connection between code and docs
- ✅ **Tracking**: Plugin tracks anchor usage and adoption

## Integration with Memory Store

The plugin automatically tracks:
- When anchors are added
- Which anchors are referenced most
- Orphaned anchors (no references)
- Documentation coverage

This skill helps INCREASE anchor adoption by proactively suggesting them!

## Remember

- Always suggest anchors for complex features
- Add anchors automatically when creating docs
- Remind about cross-referencing in code
- Use consistent naming conventions
- Explain the benefit to users
- Make documentation maintenance easy