Initial commit

skills/add-neon-docs/install-knowledge.md

@@ -0,0 +1,258 @@
+# 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:
+
+```markdown
+- **${description}**: ${url}
+```
+
+Combine all references into a section:
+
+```markdown
+## 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:
+  ```markdown
+  # 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:
+
+```markdown
+✅ 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:
+
+```markdown
+## 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:
+
+```markdown
+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"}
+```