🧠 skillbase

Local skill manager for AI-assisted development environments.

skillbase is a Node.js CLI that empowers you to manage skills for your AI agents using symbolic links (symlinks) or local installations per workspace, preventing context saturation.

---

🌐 Language / Idioma

• 🇪🇸 Ver documentación en Español

---

🤔 The Problem: Context Bloat

When developing with AI assistance (using tools like Cursor, Copilot, or custom agents), having a global directory with hundreds of skills in .agents/skills/ destroys model precision:

• Hallucinations: The LLM gets confused by having too many irrelevant tools at its disposal.
• Token Consumption: Sending the manifest of hundreds of skills in every prompt is slow and expensive.
• Lack of Focus: One project doesn't need the same skills as another.

💡 The Solution

skillbase maintains a single global registry on your machine (~/.skillbase/skills) and allows you to install only what you need in your current project.

Imagine you're working on the frontend of an e-commerce site. No need for the AI to see DevOps or Backend tools; you only need your React skills and maybe some SEO skills. With skillbase, you give your agent exactly that context.

---

🚀 Installation

Install the package globally:

npm install -g @ariasbruno/skillbase
# Or clone and link locally:
# npm link

💻 Quickstart

1. Initialize your project Detect technologies and suggest compatible skills:

skillbase init

2. Add necessary skills

skillbase add seo-analyzer
# Or open the interactive selector:
skillbase add

3. Install from manifest If you already have a skillbase.json, recreate the environment:

skillbase install

---

🛠️ Command Reference

Command	Alias	Description
skillbase ls [-g]	l [-g]	List skills in local project. Use -g for global registry.
skillbase init [--hard]		Detect technologies and suggests skills (use --hard for deep analysis).
skillbase add [<skill>] [-s]	a	Install global skill. Without name, opens interactive selector. -s for symlinks.
skillbase install	i	Install from skillbase.json. Supports -r (remote) and -f (force).
skillbase install <ref> -r	i -r	Install remote skill (URL or GitHub). Requires -k <name> if it's a Git repo.
skillbase remove [<skill>] [-g] [-a]	rm	Remove skill from project. Without name, opens interactive selector. Use -a to remove all, or -g for global registry.
skillbase check [-r]	c	Check for updates. With -r, searches only in remote sources.
skillbase update [<skill>] [-r] [-f]	up	Update one or all skills. -r for remote, -f to force.
skillbase migrate [-p] [-y]	m	Migrate (~/.agents) or promote local skills with -p. Use -y for auto-mode.
skillbase config [sources|autoupdate|lang]	cfg	Configure skill sources, auto-updates, and language.
skillbase lang <en|es>		Change CLI language (alias for config lang).

🚩 Detailed Flags

• -h, --help: Show detailed help.
• -s, --sym: Create a symbolic link instead of copying files (useful for development).
• -r, --remote: Indicates that the operation should consult external sources (GitHub or skills.sh API).
• -f, --force: Ignore "already exists" errors and overwrite files/configurations.
• -k, --skill: Name of the specific skill to extract when installing from a GitHub repository.
• -g, --global: Operate on the global registry (for ls and remove).
• -y, --yes: Perform automated migration without prompts (installs and overwrites everything).
• -a, --all: Removes all installed skills within a specific context (used with remove).

⌨️ Command Aliases

For speed, you can use initials: l (ls), a (add), i (install), rm (remove), c (check), up (update), m (migrate), cfg (config).

---

📂 How does it work under the hood?

skillbase organizes your tools efficiently:

Your Computer
├── ~/.skillbase/skills/           <-- (Your physical global registry)
│   ├── seo-analyzer/              <-- (Real source code)
│   └── react-helper/
│
└── /Projects/my-great-app/        <-- (Your current workspace)
    ├── skillbase.json             <-- (Project manifest)
    └── .agents/skills/            <-- (Clean context for the AI)
        └── seo-analyzer/          <-- (Link or local copy)

You can change the global registry location by setting the SKILLBASE_HOME environment variable.

---

🌐 Remote Sources

Install skills directly from GitHub repositories:

skillbase install <repo-url> --remote
# Example:
skillbase install https://github.com/user/my-skills --remote --skill analyzer

---

🤝 Contributions

Contributions are welcome! If you have ideas to improve context management, open an Issue or a Pull Request.

📄 License

MIT