@p_tipso/agentive 1.1.1 → 1.1.4

package/README.md

@@ -20,27 +20,31 @@
 
 ---
 
-Stop maintaining separate rule files for every AI tool. **agentive** scaffolds a universal `.agents/` directory, an `AGENTS.md` file, and an `.aiignore` file in your project — providing a **single source of truth** for all your agent commands, skills, and rules, while significantly saving token usage.
+Stop maintaining separate rule files for every AI tool. **agentive** scaffolds a universal `.agents/` directory, an `AGENTS.md` file, and an `.aiignore` file in your project — providing a **single source of truth** for all your agent commands, skills, libraries, and rules, while significantly saving token usage.
 
 ## ✨ Why Agentive?
 
-| Feature                       | Description                                                          |
-| :---------------------------- | :------------------------------------------------------------------- |
-| 🚀 **Interactive Setup**    | Select your environment (General, Expo, React Native) to get tailored rules. |
-| 🌍 **Universal**              | Framework-agnostic setup. Works with React, Python, Go, you name it. |
-| 🧠 **Single Source of Truth** | Centralize skills and rules for _all_ your AI agents in one place.   |
-| ⚡ **Dynamic Layering**     | Scaffolds base rules and safely merges framework-specific guardrails. |
+| Feature                       | Description                                                                    |
+| :---------------------------- | :----------------------------------------------------------------------------- |
+| 🚀 **Interactive Setup**      | Select your environment (General, Expo, React Native) to get tailored rules.   |
+| 🌍 **Universal**              | Framework-agnostic setup. Works with React, Python, Go, you name it.           |
+| 🧠 **Single Source of Truth** | Centralize skills, libraries, and rules for _all_ your AI agents in one place. |
+| ⚡ **Dynamic Layering**       | Scaffolds base rules and safely merges framework-specific guardrails.          |
 
 ---
 
 ## 📦 Installation & Usage
 
-Run one command, get a fully structured AI agent workspace instantly:
+Run one command to get a fully structured AI agent workspace instantly. 
+**Note for Users:** Always append `@latest` to ensure `npx` downloads the newest public release from the npm registry, avoiding any locally cached versions:
 
 ```bash
-npx @p_tipso/agentive
+npx @p_tipso/agentive@latest
 ```
 
+> **Note for Contributors:** If you are testing this package locally (e.g., via `npm link`), simply run `npx @p_tipso/agentive` (without `@latest`) to execute your local codebase.
+
+
 If you prefer to install it globally for frequent usage:
 
 ```bash
@@ -50,13 +54,13 @@ agentive
 
 ### CLI Commands
 
-| Command                           | Description                                                  |
-| :-------------------------------- | :----------------------------------------------------------- |
-| `npx @p_tipso/agentive init`      | Scaffold `.agents/` workspace instantly in current directory |
-| `npx @p_tipso/agentive install <pkg>`| Install an agent skill or rule from the registry (alias: `add`) |
-| `npx @p_tipso/agentive remove <pkg>` | Remove an installed skill or rule (alias: `rm`)              |
-| `npx @p_tipso/agentive --version` | Print the current CLI version                                |
-| `npx @p_tipso/agentive --help`    | Show available commands and options                          |
+| Command                               | Description                                                               |
+| :------------------------------------ | :------------------------------------------------------------------------ |
+| `npx @p_tipso/agentive init`          | Scaffold `.agents/` workspace instantly in current directory              |
+| `npx @p_tipso/agentive install <pkg>` | Install an agent skill, library, or rule from the registry (alias: `add`) |
+| `npx @p_tipso/agentive remove <pkg>`  | Remove an installed skill, library, or rule (alias: `rm`)                 |
+| `npx @p_tipso/agentive --version`     | Print the current CLI version                                             |
+| `npx @p_tipso/agentive --help`        | Show available commands and options                                       |
 
 ---
 
@@ -77,6 +81,8 @@ your-project/
 │   │   └── fix-issue.md           ← Example zero-error fix command
 │   ├── skills/
 │   │   └── README.md              ← Guide: how to add skills
+│   ├── library/
+│   │   └── README.md              ← Guide: passive library references
 │   └── rules/
 │       └── README.md              ← Guide: how to add rules
 ```
@@ -86,10 +92,12 @@ your-project/
 - **`.aiignore`**: Prevents context pollution and saves tokens by hiding files (like `node_modules` or build outputs) from your AI agents.
 - **`commands/`**: Reusable prompt instructions that agents can execute on demand (e.g. `review.md`).
 - **`skills/`**: Skill definitions that teach agents how to behave in specific roles.
+- **`library/`**: Passive library documentation and API references.
 - **`rules/`**: Project-wide rules that all agents must follow strictly.
 
 ### 🌟 Framework-Specific Guardrails
-By selecting a specific framework (like **Expo** or **React Native**), `agentive` overlays expertly crafted rules into your `.agents/` folder. This ensures your AI understands nuances like *Expo Router*, *Native Modules*, or *Unitless Pixels* right out of the box—preventing common hallucinations.
+
+By selecting a specific framework (like **Expo** or **React Native**), `agentive` overlays expertly crafted rules into your `.agents/` folder. This ensures your AI understands nuances like _Expo Router_, _Native Modules_, or _Unitless Pixels_ right out of the box—preventing common hallucinations.
 
 ---
 
@@ -103,13 +111,7 @@ Please read our [Contributing Guide](CONTRIBUTING.md) to get started with settin
 
 ## ⭐ Star History
 
-<a href="https://star-history.com/#TiPS0/agentive&Date">
- <picture>
-   <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=TiPS0/agentive&type=Date&theme=dark" />
-   <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=TiPS0/agentive&type=Date" />
-   <img alt="Star History Chart" src="https://api.star-history.com/svg?repos=TiPS0/agentive&type=Date" />
- </picture>
-</a>
+[![Star History Chart](https://raw.githubusercontent.com/TiPS0/agentive/star-tracker-data/charts/star-history.svg)](https://star-history.com/#TiPS0/agentive&Date)
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@p_tipso/agentive",
-  "version": "1.1.1",
+  "version": "1.1.4",
   "description": "A universal, framework-agnostic AI agent repository setup CLI. Scaffold a .agents/ workspace, AGENTS.md, and .aiignore to sync and optimize context for Cursor, Claude, and Windsurf.",
   "license": "MIT",
   "author": "Pakawat Tipso",

package/src/commands/init.js

@@ -16,7 +16,7 @@ async function runInit() {
   const projectName = path.basename(cwd);
 
   console.log('');
-  console.log(chalk.bold.cyan('  🤖 agentive') + chalk.gray(' — Universal AI Agent Workspace Setup'));
+  console.log(chalk.bold.cyan(`  Agentive v${version}`) + chalk.gray(' — Universal AI Agent Workspace Setup'));
   console.log(chalk.gray('  ─────────────────────────────────────────────'));
   console.log('');
 
@@ -123,6 +123,7 @@ async function runInit() {
   console.log(chalk.gray('    │   ├── review.md               ← code review command'));
   console.log(chalk.gray('    │   └── fix-issue.md            ← zero-error fix command'));
   console.log(chalk.gray('    ├── skills/'));
+  console.log(chalk.gray('    ├── library/'));
   console.log(chalk.gray('    └── rules/'));
   console.log('');
   console.log(chalk.gray('  Edit the markdown files to customise agent behaviour.'));

package/src/commands/install.js

@@ -3,33 +3,23 @@
 const path = require('path');
 const chalk = require('chalk');
 const fs = require('fs/promises');
-const { agentDirectoryExists, addDependency, linkAgentFile } = require('../utils/fileSystem');
-
-// A simple regex to parse YAML frontmatter block at the start of a string
-const frontmatterRegex = /^---\r?\n([\s\S]*?)\r?\n---\r?\n/;
-
-function parseFrontmatter(content) {
-  const match = content.match(frontmatterRegex);
-  const metadata = {};
-  if (match && match[1]) {
-    const lines = match[1].split('\n');
-    lines.forEach(line => {
-      const parts = line.split(':');
-      if (parts.length >= 2) {
-        const key = parts[0].trim();
-        const value = parts.slice(1).join(':').trim().replace(/^['"](.*)['"]$/, '$1');
-        metadata[key] = value;
-      }
-    });
+const prompts = require('prompts');
+const { agentDirectoryExists, addDependency, linkAgentFile, updateLibraryReadme } = require('../utils/fileSystem');
+
+async function checkExists(p) {
+  try {
+    await fs.access(p);
+    return true;
+  } catch {
+    return false;
   }
-  return { metadata, rawMatch: match ? match[0] : '' };
 }
 
 async function runInstall(packageName) {
   const cwd = process.cwd();
 
   console.log('');
-  console.log(chalk.bold.cyan('  🤖 agentive') + chalk.gray(' — Installing Package'));
+  console.log(chalk.bold.cyan('  Agentive') + chalk.gray(' — Installing Library Package'));
   console.log(chalk.gray('  ─────────────────────────────────────────────'));
   console.log('');
 
@@ -46,54 +36,134 @@ async function runInstall(packageName) {
 
   console.log(chalk.gray(`  Fetching ${packageName}...`));
 
-  let fileContent = '';
+  let infoContent = '';
+  let typesContent = '';
+  let rulesContent = '';
+  let combinedContent = '';
+  let name = packageName;
+  let version = '1.0.0';
+  let description = `A library package for ${packageName}`;
+
   try {
-    let url = packageName;
-    if (!url.startsWith('http')) {
-      // Mock registry URL for demonstration
-      url = `https://raw.githubusercontent.com/TiPS0/agentive-registry/main/packages/${packageName}.md`;
+    const response = await fetch(`https://registry.npmjs.org/${packageName}`);
+    if (!response.ok) {
+      throw new Error(`Failed to fetch from NPM registry (Status: ${response.status})`);
     }
+    const npmData = await response.json();
     
-    // Attempt fetch
-    const response = await fetch(url);
-    if (!response.ok) {
-      throw new Error(`Failed to fetch from registry (Status: ${response.status})`);
+    version = npmData['dist-tags']?.latest || '1.0.0';
+    description = npmData.description || description;
+    name = npmData.name || packageName;
+    const homepage = npmData.homepage || npmData.repository?.url || `https://www.npmjs.com/package/${packageName}`;
+    let readmeContent = npmData.readme || '';
+    
+    if (!readmeContent) {
+      try {
+        const unpkgResponse = await fetch(`https://unpkg.com/${packageName}/README.md`);
+        if (unpkgResponse.ok) {
+          readmeContent = await unpkgResponse.text();
+        }
+      } catch (err) {}
     }
-    fileContent = await response.text();
+
+    try {
+      const typesResponse = await fetch(`https://unpkg.com/${packageName}/index.d.ts`);
+      if (typesResponse.ok) {
+        typesContent = await typesResponse.text();
+      }
+    } catch (err) {}
+
+    infoContent = `# ${name} Reference\n\n## Installation Summary\n\`\`\`bash\nnpm install ${name}\n\`\`\`\n\n## Overview\n${description}\n\nFor more information, visit [${name}](${homepage}).\n\n${readmeContent ? `## Documentation\n\n${readmeContent}` : ''}`;
+    
+    const rulesObj = {
+      library: name,
+      constraints: [
+        `Follow standard practices for ${name}.`,
+        `Check official documentation for latest patterns.`
+      ]
+    };
+    rulesContent = JSON.stringify(rulesObj, null, 2);
+
+    combinedContent = `${infoContent}\n\n## Types\n\`\`\`typescript\n${typesContent || '// No types found'}\n\`\`\`\n\n## Rules\n\`\`\`json\n${rulesContent}\n\`\`\``;
+
   } catch (err) {
-    console.log(chalk.yellow('  ⚠ ') + `Fetch failed: ${err.message}`);
-    console.log(chalk.gray('  Creating a mock package for demonstration...'));
-    fileContent = `---
-name: ${packageName}
-type: skill
-version: 1.0.0
-description: A mock skill for ${packageName}
----
-# ${packageName}
-This is a generated placeholder skill because the registry could not be reached.
-`;
+    console.log(chalk.red('  ✖ ') + `Fetch failed: ${err.message}`);
+    console.log(chalk.gray('  Skipping installation. Please check the package name and try again.'));
+    process.exit(1);
   }
 
-  const { metadata } = parseFrontmatter(fileContent);
-  const type = metadata.type || 'skill';
-  const name = metadata.name || packageName;
-  const version = metadata.version || '1.0.0';
-  
-  // Pluralize type for folder name (skill -> skills, rule -> rules)
-  const folderName = type.endsWith('s') ? type : `${type}s`;
   const agentsDir = path.join(cwd, '.agents');
-  const targetFolder = path.join(agentsDir, folderName);
-  const targetFile = path.join(targetFolder, `${packageName}.md`);
+  const targetFolder = path.join(agentsDir, 'library', packageName);
+  const relativePath = `.agents/library/${packageName}/info.md`;
   
+  const choices = [
+    { title: '.agents/library (Agentive Knowledge)', value: 'agents', selected: true }
+  ];
+
+  if (await checkExists(path.join(cwd, '.cursor'))) {
+    choices.push({ title: '.cursor/rules (Cursor Editor)', value: 'cursor' });
+  }
+  if (await checkExists(path.join(cwd, '.windsurfrules'))) {
+    choices.push({ title: '.windsurfrules (Windsurf Editor)', value: 'windsurf' });
+  }
+  if (await checkExists(path.join(cwd, '.claude.md'))) {
+    choices.push({ title: '.claude.md (Claude AI)', value: 'claude' });
+  }
+
+  let selectedDestinations = ['agents'];
+  if (choices.length > 1) {
+    const { dests } = await prompts({
+      type: 'multiselect',
+      name: 'dests',
+      message: 'Where would you like to install this library?',
+      instructions: '\n↑/↓: Move ◦ ←/→ or [Space]: Toggle ◦ A: Toggle all ◦ ↵ Submit',
+      choices,
+      min: 1
+    });
+    if (dests && dests.length > 0) {
+      selectedDestinations = dests;
+    }
+  }
+
   try {
-    await fs.mkdir(targetFolder, { recursive: true });
-    await fs.writeFile(targetFile, fileContent, 'utf-8');
-    
-    await addDependency(agentsDir, packageName, version, type);
-    await linkAgentFile(cwd, `.agents/${folderName}/${packageName}.md`, `[${type.toUpperCase()}] ${name}`);
-    
-    console.log(chalk.green('  ✔ ') + `Successfully installed ${chalk.cyan(name)} v${version}`);
-    console.log(chalk.gray(`      Location: .agents/${folderName}/${packageName}.md`));
+    if (selectedDestinations.includes('agents')) {
+      await fs.mkdir(targetFolder, { recursive: true });
+      await fs.writeFile(path.join(targetFolder, 'info.md'), infoContent, 'utf-8');
+      await fs.writeFile(path.join(targetFolder, 'types.d.ts'), typesContent, 'utf-8');
+      await fs.writeFile(path.join(targetFolder, 'rules.json'), rulesContent, 'utf-8');
+      
+      await addDependency(agentsDir, packageName, version, 'library');
+      await linkAgentFile(cwd, relativePath, `[LIBRARY] ${name}`, '## Installed Libraries');
+      await updateLibraryReadme(agentsDir, packageName, description, version);
+      
+      console.log(chalk.green('  ✔ ') + `Successfully installed ${chalk.cyan(name)} v${version} to .agents/library/${packageName}/`);
+    }
+
+    if (selectedDestinations.includes('cursor')) {
+      const cursorRulesDir = path.join(cwd, '.cursor', 'rules');
+      await fs.mkdir(cursorRulesDir, { recursive: true });
+      const cursorFile = path.join(cursorRulesDir, `${packageName}.mdc`);
+      await fs.writeFile(cursorFile, combinedContent, 'utf-8');
+      console.log(chalk.green('  ✔ ') + `Successfully installed ${chalk.cyan(name)} to .cursor/rules/${packageName}.mdc`);
+    }
+
+    if (selectedDestinations.includes('windsurf')) {
+      const windsurfFile = path.join(cwd, '.windsurfrules');
+      let existing = '';
+      try { existing = await fs.readFile(windsurfFile, 'utf-8'); } catch(e) {}
+      const newContent = existing + `\n\n# Library: ${name}\n\n` + combinedContent;
+      await fs.writeFile(windsurfFile, newContent, 'utf-8');
+      console.log(chalk.green('  ✔ ') + `Successfully appended ${chalk.cyan(name)} to .windsurfrules`);
+    }
+
+    if (selectedDestinations.includes('claude')) {
+      const claudeFile = path.join(cwd, '.claude.md');
+      let existing = '';
+      try { existing = await fs.readFile(claudeFile, 'utf-8'); } catch(e) {}
+      const newContent = existing + `\n\n# Library: ${name}\n\n` + combinedContent;
+      await fs.writeFile(claudeFile, newContent, 'utf-8');
+      console.log(chalk.green('  ✔ ') + `Successfully appended ${chalk.cyan(name)} to .claude.md`);
+    }
   } catch (err) {
     console.log(chalk.red('  ✖ ') + `Failed to write file: ${err.message}`);
     process.exit(1);

package/src/commands/remove.js

@@ -3,13 +3,13 @@
 const path = require('path');
 const chalk = require('chalk');
 const fs = require('fs/promises');
-const { agentDirectoryExists, removeDependency, readSettings, unlinkAgentFile } = require('../utils/fileSystem');
+const { agentDirectoryExists, removeDependency, readSettings, unlinkAgentFile, removeSkillFromReadme, removeLibraryFromReadme } = require('../utils/fileSystem');
 
 async function runRemove(packageName) {
   const cwd = process.cwd();
 
   console.log('');
-  console.log(chalk.bold.cyan('  🤖 agentive') + chalk.gray(' — Removing Package'));
+  console.log(chalk.bold.cyan('  Agentive') + chalk.gray(' — Removing Package'));
   console.log(chalk.gray('  ─────────────────────────────────────────────'));
   console.log('');
 
@@ -38,14 +38,29 @@ async function runRemove(packageName) {
     name = settings.dependencies[packageName].name || packageName;
   }
 
-  const folderName = type.endsWith('s') ? type : `${type}s`;
-  const targetFile = path.join(agentsDir, folderName, `${packageName}.md`);
+  const folderName = type === 'library' ? 'library' : (type.endsWith('s') ? type : `${type}s`);
+  const oldTargetFile = path.join(agentsDir, folderName, `${packageName}.md`);
+  const newTargetFolder = path.join(agentsDir, folderName, packageName);
 
   try {
-    await fs.rm(targetFile, { force: true });
+    await fs.rm(oldTargetFile, { force: true });
+    await fs.rm(newTargetFolder, { recursive: true, force: true });
+    
+    // Also try to remove cursor file if it exists
+    const cursorFile = path.join(cwd, '.cursor', 'rules', `${packageName}.mdc`);
+    await fs.rm(cursorFile, { force: true }).catch(() => {});
+    
     const removedFromSettings = await removeDependency(agentsDir, packageName);
+    
     await unlinkAgentFile(cwd, `.agents/${folderName}/${packageName}.md`, `[${type.toUpperCase()}] ${name}`);
     
+    if (type === 'skill') {
+      await unlinkAgentFile(cwd, `.agents/skills/${packageName}/SKILL.md`, `[${type.toUpperCase()}] ${name}`);
+      await removeSkillFromReadme(agentsDir, packageName);
+    } else if (type === 'library') {
+      await unlinkAgentFile(cwd, `.agents/library/${packageName}/info.md`, `[LIBRARY] ${name}`);
+      await removeLibraryFromReadme(agentsDir, packageName);
+    }
     if (removedFromSettings) {
       console.log(chalk.green('  ✔ ') + `Successfully removed ${chalk.cyan(packageName)}`);
     } else {

package/src/templates/base/AGENTS.md

@@ -17,6 +17,7 @@ All agent configuration lives inside the `.agents/` directory:
 | `.agents/settings.local.json` | Local machine overrides (gitignored) |
 | `.agents/commands/` | Reusable prompt commands your agents can execute |
 | `.agents/skills/` | Skill definitions that teach agents how to behave |
+| `.agents/library/` | Passive library documentation and API references |
 | `.agents/rules/` | Project-wide rules all agents must follow |
 
 ## Context Management
@@ -29,6 +30,7 @@ Additionally, you must also read and respect any rules defined in `.gitignore`,
 1. Edit the markdown files inside `.agents/` to customise agent behaviour
 2. Add new commands in `.agents/commands/` for common tasks
 3. Add new skills in `.agents/skills/` to teach agents new capabilities
-4. Add new rules in `.agents/rules/` to enforce coding standards
+4. Install NPM packages to `.agents/library/` via `npx agentive install <pkg>`
+5. Add new rules in `.agents/rules/` to enforce coding standards
 
 Re-run `npx @p_tipso/agentive` any time to re-sync changes to your AI tools.

package/src/templates/base/library/README.md

@@ -0,0 +1,17 @@
+# Library Directory
+
+This directory contains passive AI agent references for your NPM packages and libraries.
+
+Unlike **skills** (which are active behaviors and workflows), **libraries** are optimized references (`info.md`, `types.d.ts`, `rules.json`) that teach your AI agents how to correctly write code for specific packages without hallucinating or reading outdated syntax.
+
+## How to Install Libraries
+
+Use the `agentive` CLI to automatically fetch documentation and types for a package:
+
+```bash
+npx agentive install <pkg>
+```
+
+This will automatically create `.agents/library/<pkg>/` and update this file with the new reference.
+
+## Installed Libraries

package/src/utils/fileSystem.js

@@ -31,6 +31,7 @@ async function agentDirectoryExists(cwd) {
  *   ├── settings.local.json
  *   ├── commands/
  *   ├── skills/
+ *   ├── library/
  *   └── rules/
  *
  * @param {string} cwd - The user's current working directory
@@ -42,13 +43,12 @@ async function createAgentDirectory(cwd, overwrite = false) {
 
   if (overwrite) {
     await fs.rm(agentsDir, { recursive: true, force: true });
-    // Also remove old AGENTS.md if overwriting
-    try { await fs.rm(path.join(cwd, 'AGENTS.md'), { force: true }); } catch { /* noop */ }
   }
 
   await fs.mkdir(agentsDir, { recursive: true });
   await fs.mkdir(path.join(agentsDir, 'commands'), { recursive: true });
   await fs.mkdir(path.join(agentsDir, 'skills'), { recursive: true });
+  await fs.mkdir(path.join(agentsDir, 'library'), { recursive: true });
   await fs.mkdir(path.join(agentsDir, 'rules'), { recursive: true });
 
   return agentsDir;
@@ -130,10 +130,21 @@ async function copyTemplates(templatesDir, agentsDir, projectName, projectType =
 
   // 1. Copy AGENTS.md from base to project root
   const agentMdSrc = path.join(templatesDir, 'base', 'AGENTS.md');
+  const targetAgentMdPath = path.join(cwd, 'AGENTS.md');
   try {
     let content = await fs.readFile(agentMdSrc, 'utf-8');
     content = replacePlaceholders(content, projectName);
-    await fs.writeFile(path.join(cwd, 'AGENTS.md'), content, 'utf-8');
+    
+    let finalContent = content;
+    try {
+      const existingContent = await fs.readFile(targetAgentMdPath, 'utf-8');
+      if (existingContent.trim()) {
+        // Prepend the new template content to the existing content
+        finalContent = content + '\n\n' + existingContent;
+      }
+    } catch { /* target may not exist, that's fine */ }
+
+    await fs.writeFile(targetAgentMdPath, finalContent, 'utf-8');
   } catch { /* template may not exist */ }
 
   // 1.5 Copy aiignore from base to project root as .aiignore
@@ -143,7 +154,7 @@ async function copyTemplates(templatesDir, agentsDir, projectName, projectType =
     await fs.writeFile(path.join(cwd, '.aiignore'), content, 'utf-8');
   } catch { /* template may not exist */ }
 
-  const foldersToInclude = ['commands', 'skills', 'rules'];
+  const foldersToInclude = ['commands', 'skills', 'rules', 'library'];
 
   // Helper to copy a specific template layer
   const copyLayer = async (layerPath) => {
@@ -257,13 +268,19 @@ async function removeDependency(agentsDir, packageName) {
 /**
  * Link a downloaded agent file into AGENTS.md
  */
-async function linkAgentFile(cwd, relativePath, title) {
+async function linkAgentFile(cwd, relativePath, title, heading = '## Installed Skills') {
   const agentMdPath = path.join(cwd, 'AGENTS.md');
+  const linkStr = `- [${title}](${relativePath})`;
+  
   try {
     let content = await fs.readFile(agentMdPath, 'utf-8');
-    const linkStr = `- [${title}](${relativePath})`;
+    
     if (!content.includes(linkStr)) {
-      content += `\n${linkStr}\n`;
+      if (content.includes(heading)) {
+        content = content.replace(heading, `${heading}\n${linkStr}`);
+      } else {
+        content = content.trimEnd() + `\n\n${heading}\n${linkStr}\n`;
+      }
       await fs.writeFile(agentMdPath, content, 'utf-8');
     }
   } catch (err) {
@@ -292,6 +309,88 @@ function escapeRegex(string) {
   return string.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
 }
 
+/**
+ * Update the .agents/skills/README.md
+ */
+async function updateSkillsReadme(agentsDir, packageName, description, version) {
+  const readmePath = path.join(agentsDir, 'skills', 'README.md');
+  const heading = '## Installed Skills';
+  const linkStr = `- **[${packageName}](./${packageName}/SKILL.md)** (v${version}): ${description || 'No description available.'}`;
+  
+  try {
+    let content = await fs.readFile(readmePath, 'utf-8');
+    
+    if (!content.includes(linkStr)) {
+      if (content.includes(heading)) {
+        content = content.replace(heading, `${heading}\n${linkStr}`);
+      } else {
+        content = content.trimEnd() + `\n\n${heading}\n${linkStr}\n`;
+      }
+      await fs.writeFile(readmePath, content, 'utf-8');
+    }
+  } catch (err) {
+    // README doesn't exist, create it
+    const content = `# Skills Directory\n\nThis directory contains AI agent skills.\n\n${heading}\n${linkStr}\n`;
+    await fs.writeFile(readmePath, content, 'utf-8');
+  }
+}
+
+/**
+ * Remove a skill from .agents/skills/README.md
+ */
+async function removeSkillFromReadme(agentsDir, packageName) {
+  const readmePath = path.join(agentsDir, 'skills', 'README.md');
+  try {
+    let content = await fs.readFile(readmePath, 'utf-8');
+    const lines = content.split('\n');
+    const newLines = lines.filter(line => !line.includes(`[${packageName}](./${packageName}/SKILL.md)`));
+    await fs.writeFile(readmePath, newLines.join('\n'), 'utf-8');
+  } catch (err) {
+    // If it doesn't exist, do nothing
+  }
+}
+
+/**
+ * Update the .agents/library/README.md
+ */
+async function updateLibraryReadme(agentsDir, packageName, description, version) {
+  const readmePath = path.join(agentsDir, 'library', 'README.md');
+  const heading = '## Installed Libraries';
+  const linkStr = `- **[${packageName}](./${packageName}/info.md)** (v${version}): ${description || 'No description available.'}`;
+  
+  try {
+    let content = await fs.readFile(readmePath, 'utf-8');
+    
+    if (!content.includes(linkStr)) {
+      if (content.includes(heading)) {
+        content = content.replace(heading, `${heading}\n${linkStr}`);
+      } else {
+        content = content.trimEnd() + `\n\n${heading}\n${linkStr}\n`;
+      }
+      await fs.writeFile(readmePath, content, 'utf-8');
+    }
+  } catch (err) {
+    await fs.mkdir(path.dirname(readmePath), { recursive: true });
+    const content = `# Library Directory\n\nThis directory contains AI agent passive library references.\n\n${heading}\n${linkStr}\n`;
+    await fs.writeFile(readmePath, content, 'utf-8');
+  }
+}
+
+/**
+ * Remove a library from .agents/library/README.md
+ */
+async function removeLibraryFromReadme(agentsDir, packageName) {
+  const readmePath = path.join(agentsDir, 'library', 'README.md');
+  try {
+    let content = await fs.readFile(readmePath, 'utf-8');
+    const lines = content.split('\n');
+    const newLines = lines.filter(line => !line.includes(`[${packageName}](./${packageName}/info.md)`));
+    await fs.writeFile(readmePath, newLines.join('\n'), 'utf-8');
+  } catch (err) {
+    // If it doesn't exist, do nothing
+  }
+}
+
 module.exports = {
   agentDirectoryExists,
   createAgentDirectory,
@@ -303,4 +402,8 @@ module.exports = {
   removeDependency,
   linkAgentFile,
   unlinkAgentFile,
+  updateSkillsReadme,
+  removeSkillFromReadme,
+  updateLibraryReadme,
+  removeLibraryFromReadme,
 };