Skip to content

Commit 6dba94a

Browse files
aallamaallam
authored
feat: add algolia-cli skill for managing Algolia via CLI (#3)
1 parent 78f1805 commit 6dba94a

File tree

8 files changed

+1375
-84
lines changed

8 files changed

+1375
-84
lines changed

‎.claude-plugin/marketplace.json‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,15 @@
1717
"skills": [
1818
"./skills/algolia-mcp"
1919
]
20+
},
21+
{
22+
"name": "algolia-cli",
23+
"description": "Skill for managing Algolia indices, records, settings, rules, and synonyms using the Algolia CLI.",
24+
"source": "./",
25+
"strict": false,
26+
"skills": [
27+
"./skills/algolia-cli"
28+
]
2029
}
2130
]
2231
}

‎.github/workflows/validate.yml‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
name: Validate Skills
2+
3+
on:
4+
push:
5+
branches: [main]
6+
pull_request:
7+
branches: [main]
8+
9+
jobs:
10+
validate:
11+
runs-on: ubuntu-latest
12+
steps:
13+
- uses: actions/checkout@v4
14+
- uses: actions/setup-python@v5
15+
with:
16+
python-version: "3.x"
17+
- run: pip install pyyaml
18+
- run: python scripts/validate_skills.py

‎README.md‎

Lines changed: 55 additions & 84 deletions
Original file line numberDiff line numberDiff line change
@@ -1,119 +1,90 @@
1-
# Algolia Agent Skill
1+
# Algolia Skills
22

3-
An [Agent Skill](https://agentskills.io/) that connects to Algolia for natural language search, analytics, and recommendations.
3+
[Agent skills](https://agentskills.io/) for managing Algolia search, analytics, recommendations, and index configuration.
44

5-
### ✨ Features
5+
## ✨ Skills
66

7-
- 🔍 **Natural Language Search** - Search your Algolia indices conversationally
8-
- 📊 **Analytics Insights** - Get search analytics through simple questions
9-
- 🎯 **Smart Recommendations** - Product recommendations (bought-together, related, trending, similar)
10-
- 🚀 **Easy Setup** - Connect in minutes with `/algolia-mcp:connect` in Claude Code
11-
- 📚 **Usage Examples** - Run `/algolia-mcp:examples` for copy-paste prompts
7+
Pick the skill that fits your workflow.
128

13-
### 🛠️ Usage
9+
| Skill | Description |
10+
|-----------------------------|-------------------------------------------------------------------|
11+
| [algolia-mcp](#algolia-mcp) | Search, analytics, and recommendations via the Algolia MCP server |
12+
| [algolia-cli](#algolia-cli) | Manage indices, settings, rules, and synonyms via the Algolia CLI |
1413

15-
The skill gives you `/algolia-mcp:connect` and `/algolia-mcp:examples` slash commands, plus guided setup and interactive examples.
14+
### algolia-mcp
1615

17-
#### Installation
16+
Search your Algolia indices with natural language, explore search analytics, and get product recommendations (bought-together, related, trending, similar) — all through the Algolia MCP server.
1817

19-
##### Option 1: From Marketplace (Recommended)
18+
#### Commands
2019

21-
**Two steps:**
20+
| Command | Description | Docs |
21+
|-------------------------|----------------------------------------------------|-------------------------------------|
22+
| `/algolia-mcp:connect` | Set up or update your Algolia MCP connection | [connect.md](commands/connect.md) |
23+
| `/algolia-mcp:examples` | Interactive usage examples with copy-paste prompts | [examples.md](commands/examples.md) |
2224

23-
1. Add the Algolia marketplace:
24-
```bash
25-
/plugin marketplace add algolia/skills
26-
```
25+
`/algolia-mcp:examples` accepts an optional category: `search`, `analytics`, or `recommendations`.
2726

28-
2. Install the plugin:
29-
```bash
30-
/plugin install algolia-mcp
31-
```
27+
#### Prerequisites
3228

33-
**Or direct install (one step):**
29+
- [Algolia account](https://www.algolia.com/users/sign_up) with at least one index containing data
30+
- Algolia MCP enabled in Dashboard (Generate AI > MCP Servers > Productivity)
31+
- MCP client — Claude Code, Codex, VS Code, Cursor, etc.
32+
- Node.js 18+ (required for `mcp-remote` bridge on non-Claude Code clients)
3433

35-
```bash
36-
/plugin install algolia-mcp@algolia-skills
37-
```
34+
### algolia-cli
3835

39-
##### Option 2: Via npx
36+
Manage Algolia indices, records, settings, rules, and synonyms from the terminal using the [Algolia CLI](https://www.algolia.com/doc/tools/cli/get-started).
4037

41-
```bash
42-
npx skills add https://github.com/algolia/skills
43-
```
38+
#### Commands
4439

45-
##### Option 3: Manual
40+
| Command | Description | Docs |
41+
|----------------------|-------------------------------------------------|-------------------------------|
42+
| `/algolia-cli:setup` | Install the Algolia CLI and configure a profile | [setup.md](commands/setup.md) |
4643

47-
1. Clone this repository:
48-
```bash
49-
git clone https://github.com/algolia/skills.git
50-
cd skills
51-
```
44+
#### Prerequisites
5245

53-
2. Copy the skill to your Claude skills directory:
54-
```bash
55-
mkdir -p ~/.claude/skills
56-
cp -r skills/algolia-mcp ~/.claude/skills/
57-
```
46+
- [Algolia account](https://www.algolia.com/users/sign_up) with Application ID and Admin API key ([Dashboard > Settings > API Keys](https://dashboard.algolia.com/account/api-keys/all))
47+
- Homebrew (macOS) or a compatible package manager
5848

59-
3. Restart Claude Code to load the skill.
49+
## 🛠️ Installation
6050

61-
#### Verify Installation
51+
### From Marketplace (recommended)
6252

53+
```bash
54+
/plugin marketplace add algolia/skills
55+
/plugin install algolia-mcp # or algolia-cli
6356
```
64-
What skills are available?
65-
```
66-
67-
You should see `algolia-mcp` in the list.
68-
69-
#### Getting Started
70-
71-
Once installed, set up your Algolia MCP connection:
72-
73-
- **If your client supports commands**, run `/algolia-mcp:connect` — it will guide you through the entire setup.
74-
- **Otherwise**, ask the agent to set up Algolia MCP (e.g. *"Set up Algolia MCP"*) and it will follow the skill's instructions.
7557

76-
Then try:
58+
Or install directly:
7759

60+
```bash
61+
/plugin install algolia-mcp@algolia-skills # or algolia-cli@algolia-skills
7862
```
79-
"Search my products index for laptop under $1000"
80-
"What were the top searches yesterday?"
81-
"Show me trending products in electronics"
82-
```
83-
84-
#### Commands
85-
86-
##### `/algolia-mcp:connect`
8763

88-
Set up or update your Algolia MCP connection.
64+
### Via npx
8965

66+
```bash
67+
npx skills add https://github.com/algolia/skills
9068
```
91-
/algolia-mcp:connect
92-
```
93-
94-
[Full command documentation](commands/connect.md)
9569

96-
##### `/algolia-mcp:examples`
70+
### Clone / Copy
9771

98-
Interactive usage examples with copy-paste prompts.
72+
Clone the repo and copy the skill folder to your agent's skills directory:
9973

74+
```bash
75+
git clone https://github.com/algolia/skills.git
76+
cp -r skills/algolia-mcp <skills-directory> # or algolia-cli
10077
```
101-
/algolia-mcp:examples # All examples
102-
/algolia-mcp:examples search # Search patterns
103-
/algolia-mcp:examples analytics # Analytics patterns
104-
/algolia-mcp:examples recommendations # Recommendations patterns
105-
```
106-
107-
[Full command documentation](commands/examples.md)
10878

109-
### 📋 Prerequisites
79+
| Agent | Skills directory |
80+
|--------------|------------------------------|
81+
| Claude Code | `~/.claude/skills/` |
82+
| Cursor | `~/.cursor/skills/` |
83+
| OpenAI Codex | `~/.codex/skills/` |
84+
| OpenCode | `~/.config/opencode/skills/` |
11085

111-
- **Algolia account** - [Sign up free](https://www.algolia.com/users/sign_up)
112-
- **At least one index** with data in your Algolia application
113-
- **Algolia MCP enabled** in Dashboard (Generate AI → MCP Servers → Productivity)
114-
- **MCP client** - Claude Code (for the full skill experience), or Codex, VS Code, Cursor, etc.
115-
- **Node.js 18+** - Required for the `mcp-remote` bridge used by non-Claude Code clients
86+
Restart your agent to load the skill.
11687

117-
### 📄 License
88+
## 📄 License
11889

119-
MIT License - see [LICENSE](LICENSE) file for details.
90+
MIT — see [LICENSE](LICENSE) for details.

‎commands/setup.md‎

Lines changed: 84 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,84 @@
1+
---
2+
name: setup
3+
description: Install the Algolia CLI and configure a profile with credentials.
4+
skill: algolia-cli
5+
---
6+
7+
# Algolia CLI Setup
8+
9+
Guide the user through installing the Algolia CLI and configuring their credentials.
10+
11+
## Step 1: Check if the CLI is installed
12+
13+
Run:
14+
15+
```bash
16+
algolia --version
17+
```
18+
19+
- **If the command succeeds**, skip to Step 3.
20+
- **If the command fails** (command not found), proceed to Step 2.
21+
22+
## Step 2: Install the CLI
23+
24+
Detect the platform and install:
25+
26+
**macOS (Homebrew):**
27+
28+
```bash
29+
brew install algolia/algolia-cli/algolia
30+
```
31+
32+
**Linux (Debian/Ubuntu):**
33+
34+
```bash
35+
echo "deb [trusted=yes] https://algolia.github.io/cli/deb/ /" | sudo tee /etc/apt/sources.list.d/algolia-cli.list
36+
sudo apt update && sudo apt install algolia
37+
```
38+
39+
**Other platforms:** Direct the user to https://www.algolia.com/doc/tools/cli/get-started for download options.
40+
41+
After installation, verify:
42+
43+
```bash
44+
algolia --version
45+
```
46+
47+
## Step 3: Check for existing profiles
48+
49+
Run:
50+
51+
```bash
52+
algolia profile list
53+
```
54+
55+
- **If profiles exist**, ask the user if they want to use an existing profile or create a new one.
56+
- **If no profiles exist** (or the command shows an empty list), proceed to Step 4.
57+
58+
## Step 4: Create a profile
59+
60+
Ask the user for:
61+
1. **Application ID** — Found in Algolia Dashboard → Settings → API Keys
62+
2. **Admin API key** — Same location. Needed for write operations.
63+
64+
Then run:
65+
66+
```bash
67+
algolia profile add --name "default" --app-id "<APP_ID>" --api-key "<API_KEY>" --default
68+
```
69+
70+
> **Important:** Always provide all three flags to avoid interactive prompts.
71+
72+
## Step 5: Verify the connection
73+
74+
Run:
75+
76+
```bash
77+
algolia indices list
78+
```
79+
80+
- **If indices are listed**, setup is complete. Tell the user they're ready to go.
81+
- **If an error occurs**, check:
82+
- Invalid API key → ask user to double-check credentials
83+
- Network error → ask user to check connectivity
84+
- No indices → that's fine, the connection works but the app has no indices yet

0 commit comments

Comments
 (0)