gh-neondatabase-labs-ai-rules-neon-plugin/skills/add-neon-docs/install-knowledge.md

Install Neon Knowledge to Project - Agent Workflow

When to use: When the user wants to add Neon's best practices reference links to their project's AI documentation.

Required parameter: SKILL_NAME (e.g., "neon-drizzle", "neon-serverless", "neon-toolkit")

---

IMPORTANT - Working Directory Context

This skill reads metadata from its own skill directory (skill-knowledge-map.json), but ALL project file operations (reading/writing CLAUDE.md, AGENTS.md, etc.) MUST happen in the current working directory.

• ✅ Read skill metadata from skill directory (absolute paths provided by system)
• ✅ Read/write project files using relative paths only (e.g., CLAUDE.md, .cursor/rules.md)
• ❌ Never construct project file paths using absolute paths or the skill's base directory

---

Step 1: Load Skill Metadata

Read the skill metadata file to get the reference URLs.

The metadata file is bundled with this skill at:

skill-knowledge-map.json

Use the Read tool to read the local file, then parse the JSON content.

Extract the metadata for the current SKILL_NAME from the JSON.

Store this information - you'll need:

• displayName: Human-readable skill name
• files: Array of .mdc files (each with url, filename, description)

If the skill is not found in metadata, inform the user and exit.

---

Step 2: Detect AI Documentation File

Use your existing tools to detect where to add the reference links in the current working directory. This is a read-only check - no files are created yet.

Check in this priority order:

2.1 Check for CLAUDE.md (most common)

Use the Glob tool to search for CLAUDE.md in the current working directory:

pattern: "CLAUDE.md"

If found: Target is CLAUDE.md file

2.2 Check for AGENTS.md (custom AI docs)

Use the Glob tool to search for AGENTS.md:

pattern: "AGENTS.md"

If found: Target is AGENTS.md file

2.3 Check for Cursor rules file

Use the Glob tool to search for Cursor rules files:

pattern: ".cursor/README.md"
pattern: ".cursor/rules.md"

If found: Target is .cursor/README.md or .cursor/rules.md

2.4 No file found

If none of the above exist, set target as: "Will create CLAUDE.md"

Store the detection result for use in Step 3.

---

Step 3: Present Plan and STOP for User Confirmation

STOP HERE. Do not proceed to Step 4 until the user explicitly confirms.

Now that you know WHAT to add (from Step 1) and WHERE to add it (from Step 2), present this plan to the user in natural language:

---

I've prepared to add ${displayName} best practices references to your project.

Target location: ${detected_location or "Will create CLAUDE.md"}

References to add: ${list each file with a bullet point showing the description and URL}

This helps your AI assistant reference Neon best practices automatically in future conversations without cluttering your project with large documentation files.

Would you like me to proceed with adding these references?

---

Wait for explicit user confirmation (e.g., "yes", "go ahead", "proceed") before continuing to Step 4.

If the user declines or asks to skip, thank them and exit the workflow gracefully.

---

Step 4: Add Reference Links

4.1 Build the reference content

For each file in the metadata, create a reference line:

- **${description}**: ${url}

Combine all references into a section:

## Resources & References

- **${file1.description}**: ${file1.url}
- **${file2.description}**: ${file2.url}

4.2 Check if "Resources & References" section exists

Read the target file and check if it already has a "## Resources & References" section.

If section exists:

• Use the Edit tool to append new references to that section
• Add the new links after existing content in that section
• Ensure proper spacing (blank line between entries)

If section doesn't exist:

• Append the entire section to the end of the file
• Add two blank lines before the section for proper spacing

If target file doesn't exist yet:

• Use the Write tool to create a new file with:

  # Project AI Documentation
  
  ## Resources & References
  
  - **${file.description}**: ${file.url}
  

4.3 Perform the edit/write

IMPORTANT: Use relative paths only when calling Write/Edit tools.

Examples:

• ✅ Correct: file_path: "CLAUDE.md"
• ✅ Correct: file_path: ".cursor/rules.md"
• ❌ Wrong: file_path: "/absolute/path/to/CLAUDE.md"

Execute the appropriate tool operation based on the above conditions.

4.4 Confirm installation

Log: ✓ Added ${displayName} reference links to ${target_location}

---

Step 5: Report Completion

Build a completion message:

✅ Reference links added successfully!

Location: ${target_location}

References added:
${list each reference with title and URL}

---

Your AI assistant can now reference these Neon best practices in future conversations by following the URLs. The documentation includes:
- Connection patterns and configuration
- Best practices and gotchas
- Code examples and templates
- Common patterns and solutions

${if target is CLAUDE.md:}
Note: I'll automatically reference these resources when you ask about ${SKILL_NAME} topics.
${end if}

${if target is Cursor:}
Note: Cursor can access these resources when working on related code.
${end if}

---

Error Handling

If metadata file cannot be read

• Log a clear error message
• Suggest checking internet connection
• Exit workflow

If write permissions denied

• Inform user about permission issue
• Suggest running with appropriate permissions
• Provide manual instructions for adding links

If target file is locked or unavailable

• Inform user of the issue
• Suggest closing editors or checking file permissions
• Provide the reference links for manual addition

---

Testing This Workflow

As Claude, you can test this workflow by:

1. Reading the metadata file
2. Detecting the current project's documentation file
3. Simulating user responses (or asking real questions)
4. Adding references to test locations

Verify:

• Metadata loads correctly
• File detection works for multiple project types
• Permission prompt is clear
• References are added in the correct format
• Existing "Resources & References" sections are preserved
• New sections are created when needed
• Error messages are clear

---

For Skill Developers

To use this workflow in your skill, add at the end of your guide or skill:

## Add Best Practices References?

Setup is complete! Would you like me to add ${SKILL_NAME} best practices reference links to your project?

This helps your AI assistant (me!) remember where to find Neon patterns for future conversations.

${Execute workflow: skills/add-neon-docs/install-knowledge.md with SKILL_NAME="${skill-name}"}

Or explicitly call it:

I'll now add reference links to help you in future conversations.

${Read and execute: skills/add-neon-docs/install-knowledge.md}
${Set SKILL_NAME = "neon-drizzle"}