SKILLmama

See it in action

📖 Build-in-public series on Dev.to:

Part 1 — scoring formula, 5-tier search, end-to-end example. Part 2 — security gate, SQP rules, companion skills. Part 3 — project scanner, Flow B, gap analysis. Part 4 — Phase 1.5, constraint confirmation in Flow A. Part 5 — tested my own install instructions, found they were wrong. Part 6 — eval harness, trigger-classification tests, bugs found by testing instead of assuming. Part 7 — paired skill-on/skill-off ablation, the deployment persistence check it exposed, and the live CVE it later caught. Part 8 — building the live OSV.dev and npm publisher-continuity checks, and the real CVE that proved them.

Install

Known upstream bug — read this first. For Codex and Antigravity, npx skills add ... -g prints Done! and exits 0 while writing to ~/.agents/skills/, which neither agent reads. Verified against [email protected] (latest) on 2026-08-08. Root cause is isUniversalAgent(): agents whose project dir is .agents/skills get misclassified, and their globalSkillsDir is discarded. Tracked in #1060 and #1470; fix pending in PR #1483. 13 agents are affected.

Until that merges, copy the file yourself using the per-agent instructions below. Each one is two lines and lands in the directory that agent actually reads.

Optional — install and verify in one command

skill-land does every agent at once and exits non-zero if the file didn't land:

npx skill-land Magithar/SKILLmama --for claude-code,codex,antigravity
npx skill-land Magithar/SKILLmama --for codex --verify

Not required. The copy commands below work on their own.

Claude Code

The upstream CLI works correctly for Claude Code:

npx skills add Magithar/SKILLmama -a claude-code -g

Installs to ~/.claude/skills/skillmama/. Pass -a claude-code explicitly: without it the CLI auto-detects the calling agent from the environment, so running it from inside another agent's shell installs to that agent instead.

Then type /skillmama in any Claude Code session.

Claude.ai (Web / Desktop)

1. Clone or download this repo
2. Zip the skillmama/ folder:

   zip -r skillmama.zip skillmama/
   

3. Go to Customize → Skills → + and upload skillmama.zip
4. Type /skillmama in any Claude.ai conversation

OpenAI Codex

Codex has a native global skills directory, ~/.codex/skills/. The upstream CLI does not write there (see the bug notice above), so copy it yourself:

mkdir -p ~/.codex/skills/skillmama
curl -sL https://raw.githubusercontent.com/Magithar/SKILLmama/main/skillmama/SKILL.md \
  -o ~/.codex/skills/skillmama/SKILL.md

Then ask naturally: codex "find me the best job queue for this project".

Antigravity

Global skills live in ~/.gemini/config/skills/, which is shared by all three Antigravity surfaces (2.0, IDE, and the agy CLI) since Google consolidated their config. Confirmed by live testing here and independently in #1470, including extraction from the agy binary's own embedded docs.

mkdir -p ~/.gemini/config/skills/skillmama
curl -sL https://raw.githubusercontent.com/Magithar/SKILLmama/main/skillmama/SKILL.md \
  -o ~/.gemini/config/skills/skillmama/SKILL.md

Fully restart Antigravity (skills load at startup), then ask "Which skills are installed?" to confirm. SKILLmama should appear in the list and in the / command picker.

For a project-scoped install instead, put it in <workspace>/.agents/skills/skillmama/SKILL.md.

Usage — invoke explicitly, confirmed working via live testing: type / and select SKILLmama from the picker (or type SKILLmama before your request), then your capability question:

SKILLmama find me the best vector database for a Python project

This triggered the real pipeline in testing — a Phase 1.5 constraint question ("do you have any specific constraints or preferences? ... Reply 'none' to search with no filters"), not a generic answer. Plain natural-language prompts with no explicit SKILLmama invocation were not confirmed to auto-trigger the skill — invoke it explicitly for reliable results.

Per Antigravity's official Agent Skills docs, the agent is also supposed to auto-trigger relevant skills from context alone, without explicit invocation — driven by the skill's description: frontmatter. We haven't verified that mode here (only explicit invocation was tested), so treat auto-trigger as unconfirmed and invoke explicitly for now.

⚠️ npx skills add Magithar/SKILLmama -a antigravity -g reports success but writes to ~/.agents/skills/, which Antigravity never reads. Still reproduces on [email protected] (2026-08-08). See the bug notice at the top of Install.

Usage

/skillmama ← scans your project and asks what to find
/skillmama find me a vector database for my FastAPI project
/skillmama what auth library should I use for my Next.js app?
/skillmama find a .dwg parser for Node.js

AI Adapters

One file, skillmama/SKILL.md, runs on every platform. Only the install location differs.

Project-scoped installs go in .claude/skills/ for Claude Code and .agents/skills/ for Codex and Antigravity.

Notes:

• The ❌ rows are the upstream bug described at the top of Install, not a problem with this skill. Verified against [email protected] on 2026-08-08.
• The skills CLI only discovers files named SKILL.md. Repos that ship per-platform variants under other names are invisible to it.
• Claude.ai is not CLI-installable. Zip the skillmama/ folder and upload via Customize → Skills.

Core Workflow

                    ┌─────────────────────────────────────────────────────────┐
                    │                      USER REQUEST                       │
                    └──────────────────────────┬──────────────────────────────┘
                                               │
                                               ▼
                                        ◇ Capability
                                          named?
                                        /         \
                                      YES           NO
                                       │             │
             ──────────────────────────┘             └──────────────────────────
            │                                                                   │
            ▼                                                                   ▼
┌───────────────────────┐                                         ┌─────────────────────────┐
│  FLOW A               │                                         │  FLOW B                 │
│  Capability Search    │                                         │  Project Scanner        │
└───────────┬───────────┘                                         └──────────┬──────────────┘
            │                                                                │
            ▼                                                                ▼
┌───────────────────────┐                                         ┌─────────────────────────┐
│  PHASE 0              │                                         │  PHASE B1               │
│  Parse Request        │                                         │  Deep Project Scan      │
│  Extract: capability, │                                         │  Build Stack Profile:   │
│  stack, constraints   │                                         │  lang, framework, DB,   │
└───────────┬───────────┘                                         │  auth, cache, AI/LLM,   │
            │                                                     │  queue, search, email…  │
            ▼                                                     └──────────┬──────────────┘
     ◇ Capability                                                            │
       vague?                                                                ▼
      /       \                                                   ┌─────────────────────────┐
    YES        NO                                                 │  PHASE B2               │
     │          │                                                 │  Gap Analysis           │
     ▼          │                                                 │  Missing categories →   │
  Ask 1         │                                                 │  High / Medium / Low    │
  clarifying    │                                                 └──────────┬──────────────┘
  question      │                                                            │
     │          │                                                            ▼
     └────┬─────┘                                                ┌─────────────────────────┐
          │                                                      │  PHASE B3               │
          ▼                                                      │  Ask 3 questions:       │
┌───────────────────────┐                                        │  1. Which gap(s)?       │
│  PHASE 1              │                                        │  2. Constraints?        │
│  Architecture Scan    │                                        │  3. Anything missed?    │
│  Read: package files, │                                        │                         │
│  Dockerfile, README,  │                                        │  ◀ STOP — await reply ▶ │
│  source files         │                                        └──────────┬──────────────┘
│  Extract: lang,       │                                                   │
│  frameworks, DBs      │                                                   │ user picks capability
└───────────┬───────────┘                                                   │
            │                                                               │
            ▼                                                               │
┌───────────────────────┐                                                   │
│  PHASE 1.5            │                                                   │
│  Confirm Constraints  │                                                   │
│  (only if none        │                                                   │
│  stated): ask 1       │                                                   │
│  informed question    │                                                   │
│  STOP — await reply   │                                                   │
└───────────┬───────────┘                                                   │
            │                                                               │
            └───────────────────────────┬───────────────────────────────────┘
                                        │
                                        ▼
                         ┌──────────────────────────────┐
                         │   PHASE 2                    │
                         │   Derive Search Terms        │
                         │   capability + stack →       │
                         │   3–5 search terms           │
                         └──────────────┬───────────────┘
                                        │
                                        ▼
                         ┌──────────────────────────────┐
                         │   PHASE 3 — 5-Tier Search    │
                         └──────────────┬───────────────┘
                                        │
                    ┌───────────────────┴─────────────────────────┐
                    │         Search loop (tiers in order)        │
                    │                                             │
                    │  Tier 1 ── GitHub (stars, recency, contrib) │
                    │     ↓                                       │
                    │  Tier 2 ── MCP Ecosystem                    │
                    │     ↓                                       │
                    │  Tier 3 ── npm / PyPI registries            │
                    │     ↓                                       │
                    │  Tier 4 ── Templates & Cookbooks            │
                    └─────────────────┬───────────────────────────┘
                                      │
                          ◇ 8+ candidates
                            found?
                           /        \
                         YES          NO
                          │            │
                     Skip remaining    │
                     tiers             │
                          │            │
                          └─────┬──────┘
                                │
                                ▼
              ┌────────────────────────────────────────┐
              │   PHASE 3.5 — Security Gate (Libraries)│
              │                                        │
              │   Live checks (per candidate):         │
              │   OSV.dev advisory lookup (npm/PyPI/   │
              │     Go/crates.io, exact version)       │
              │   npm publisher-continuity check       │
              │                                        │
              │   Hard Gate (per candidate):           │
              │   🚫 BLOCKED → discard, never score    │
              │   ⚠️  WARN   → show, user confirms     │
              │                                        │
              │   Quality flags (SQP rules):           │
              │   SQP-1  Vague triggers                │
              │   SQP-2  Missing user warnings         │
              │   SQP-3  Policy violations             │
              └───────────────┬────────────────────────┘
                              │
                              ▼
              ┌──────────────────────────────────────────┐
              │   PHASE 3.6 — Companion Skills Search    │
              │   (REQUIRED — never skip)                │
              │                                          │
              │   For each candidate:                    │
              │   Search: site:skills.sh [name]          │
              │   Search: terminalskills.io/skills [name]│
              │   Search: site:skillsmp.com [name]       │
              │   Search: github.com "SKILL.md" [name]   │
              └───────────────┬──────────────────────────┘
                              │
                              ▼
              ┌────────────────────────────────────────┐
              │   PHASE 3.7 — Security Gate (Skills)   │
              │                                        │
              │   🚫 BLOCKED → discard                 │
              │   ⚠️  SQP-1/2/3 → flag, keep           │  
              │   ⚠️  WARN → show with caution         │
              └───────────────┬────────────────────────┘
                              │
                              ▼
              ┌────────────────────────────────────────┐
              │   PHASE 4 — Score Each Candidate       │
              │                                        │
              │   Score = (C × 0.40) +                 │
              │           (P × 0.30) +                 │
              │           (M × 0.15) +                 │
              │           (S × 0.15)                   │
              │                                        │
              │   C — Compatibility   (stack fit)      │
              │   P — Popularity      (stars/downloads)│
              │   M — Maintenance     (last commit)    │
              │   S — Simplicity      (install effort) │
              │                                        │
              │   Each factor: 1–10                    │
              └───────────────┬────────────────────────┘
                              │
                              ▼
              ┌────────────────────────────────────────┐
              │   PHASE 5 — Present Results            │
              │                                        │
              │   #1, #2, #3 — full score breakdown    │
              │   Also Considered — table              │
              │   MCP callout (if found)               │
              │   Companion Skills (if found)          │
              │   Next Steps (3 actions)               │
              └────────────────────────────────────────┘

Security & Quality Gate

Before scoring, every candidate passes through the gate (Phase 3.5). The first two layers query live data rather than relying on the model's recall:

Known limits. Stated plainly, because a gate that oversells what it checks is worse than no gate:

• Publisher continuity is npm-only. PyPI exposes no per-release uploader identity, so Python candidates report N/A (unsupported ecosystem) rather than implying the check ran.
• It catches handoffs, not account takeovers. In the ua-parser-js, rc, and coa compromises the attacker published under the real maintainer's name, so this check reads clean. Only the advisory lookup catches those, and only after disclosure.
• Only recent handoffs are reported (under 12 months, most recent only). Measured across 98 popular npm packages: 51% carry a stale handoff somewhere in their history, so reporting all of them would fire on more than half of npm and train you to ignore the warning. With the recency filter, 7%.
• Advisory lookup covers the direct package, not the full transitive dependency tree.
• Unreachable service means N/A (unverified), never a silent pass.

SQP rules are inspired by NVIDIA/SkillSpector (Apache 2.0). For deeper static analysis with 64 vulnerability patterns, run SkillSpector directly:

uv tool install git+https://github.com/NVIDIA/skillspector.git
skillspector scan <repo-url>

Earlier versions of this README said pip install skillspector. That package does not exist on PyPI (404); SkillSpector installs from git via uv. Corrected 2026-08-08.

skill-land runs this scan before writing a skill to disk and reports the findings. It does not block on them: measured against 18 known-good installed skills, SkillSpector's static mode returns DO_NOT_INSTALL for 44% of them. Pass --strict if you want it to refuse.

This skill scores 7 / LOW / SAFE. It previously scored 100 / CRITICAL / DO_NOT_INSTALL, because its own Phase 3.7 DISCARD criteria contained phrases like "instructions to bypass safety checks" and the static matcher read the checklist as the attack. Four criteria were reworded to say the same thing in different words. No rule was weakened, and adding a user-consent section was tested and made the score worse, not better: describing a safeguard trips the same patterns as describing the danger.

Ranking Formula

Every candidate that passes the gate is scored 1–10 on four dimensions:

Total = (Compat × 0.40) + (Pop × 0.30) + (Maint × 0.15) + (Simp × 0.15)

5-Tier Search Hierarchy

Output Format

Results open with a scoring table prefixed by the detected stack, then a ranked card per pick:

**Scoring all candidates against [stack]:**

| Candidate | Compat | Pop | Maint | Simple | Score |
|-----------|--------|-----|-------|--------|-------|
| Name      | X      | X   | X     | X      | X.X   |

#1 — [Name] · Score: X.X/10
[One sentence on why it wins for this stack]
- Compatibility: X/10 — [reason]
- Popularity:    X/10 — [stars/downloads]
- Maintenance:   X/10 — [last commit / release cadence]
- Simplicity:    X/10 — [setup effort]
- Security:      [PASS | ⚠️ SQP-N — finding | 🚫 BLOCKED]
- Install: `[command]`
- Links: [npm] · [PyPI] · [pkg.go.dev] · [Smithery] · [GitHub]

Followed by:

• Also Considered table with Name · Score · Why not #1 · Links
• MCP Option callout with Smithery + GitHub links
• Companion Skills — installable agent skills for top picks (if found)
• Next Steps — 3 concrete actions

Security findings from the internal gate surface inline on each candidate's Security: line — there is no separate gate section in the output.

End-to-End Example

User prompt:

find me a vector database for my FastAPI + Python project

Step 1 — Architecture Scan

✓ pyproject.toml    → Python 3.11, FastAPI, SQLAlchemy → PostgreSQL
✓ Dockerfile        → containerized, no GPU
✓ .env.example      → OPENAI_API_KEY present → RAG use case confirmed

Detected stack: Python / FastAPI / PostgreSQL / Docker / OpenAI

Step 2 — Confirm Constraints (Phase 1.5 — no constraints were stated, so SKILLmama asks one informed question and stops)

SKILLmama: I see you're on Python / FastAPI / PostgreSQL / Docker / OpenAI.
Before I search — any constraints? (e.g. self-hosted, open-source only,
free tier, must integrate with PostgreSQL). Reply "none" to search with no filters.

User: containerizable, Python client, must stay open-source

Step 3 — Capability Detection

CAPABILITY : vector database for RAG / semantic search
STACK      : Python / FastAPI / PostgreSQL / Docker / OpenAI
CONSTRAINTS: containerizable, Python client, open-source

Step 4 — 5-Tier Search

Tier 1 GitHub    → qdrant/qdrant (17k★), chroma-core/chroma (14k★),
                   pgvector/pgvector (11k★), milvus-io/milvus (29k★)
Tier 2 MCP       → qdrant-mcp-server, chroma-mcp
Tier 3 PyPI      → qdrant-client (380k/wk), chromadb (620k/wk), pgvector (180k/wk)
Tier 4 Templates → LangChain + Qdrant RAG template, FastAPI + Chroma starter
Skills (3.6)     → "qdrant-memory-skill", "chroma-rag-skill" on skills.sh + TerminalSkills.io + SkillsMP

Step 5 — Output

## SKILLmama Results

Capability: vector database for RAG
Stack: Python / FastAPI / PostgreSQL / Docker / OpenAI
Sources searched: Tier 1 (GitHub) · Tier 2 (MCP) · Tier 3 (PyPI) · Tier 4 (Templates) · Skills (skills.sh + TerminalSkills.io + SkillsMP + GitHub SKILL.md)

---

**Scoring all candidates against Python / FastAPI / PostgreSQL / Docker / OpenAI:**

| Candidate | Compat | Pop | Maint | Simple | Score    |
|-----------|--------|-----|-------|--------|----------|
| Qdrant    | 9      | 8   | 10    | 9      | **9.05** |
| pgvector  | 10     | 7   | 9     | 7      | **8.65** |
| Chroma    | 8      | 8   | 9     | 10     | **8.55** |
| Milvus    | 6      | 9   | 10    | 4      | **7.05** |

---

#1 — Qdrant · Score: 9.05/10
Docker-native, official Python client, active MCP server for AI workflows.
- Compatibility: 9/10  — official qdrant-client SDK, FastAPI examples in docs
- Popularity:    8/10  — 17k GitHub stars, 380k PyPI downloads/week
- Maintenance:  10/10  — committed 2 days ago, weekly releases
- Simplicity:   9/10  — docker run + pip install, 5-min setup
- Security:     PASS  — no findings
- Install: docker run -p 6333:6333 qdrant/qdrant && pip install qdrant-client
- Links: [skills.sh](https://skills.sh/qdrant) · [PyPI](https://pypi.org/project/qdrant-client) · [Smithery](https://smithery.ai/server/qdrant-mcp-server) · [GitHub](https://github.com/qdrant/qdrant)

#2 — pgvector · Score: 8.65/10
Stay on PostgreSQL — no new infra, native SQL queries.
- Links: [PyPI](https://pypi.org/project/pgvector) · [GitHub](https://github.com/pgvector/pgvector)

#3 — Chroma · Score: 8.55/10
Easiest local dev setup; best for prototyping before scaling.
- Links: [PyPI](https://pypi.org/project/chromadb) · [Smithery](https://smithery.ai/server/chroma-mcp) · [GitHub](https://github.com/chroma-core/chroma)

---

Also Considered:
| Name   | Score | Why not #1                        | Links |
|--------|-------|-----------------------------------|-------|
| Milvus | 7.05  | Complex setup, over-engineered for solo/small team | [PyPI](https://pypi.org/project/pymilvus) · [gh](https://github.com/milvus-io/milvus) |

---

MCP Option: qdrant-mcp-server — install as MCP tool for direct AI memory integration.
[Smithery](https://smithery.ai/server/qdrant-mcp-server) · [GitHub](https://github.com/qdrant/mcp-server-qdrant)

---

Companion Skills:
> qdrant/mcp-server-qdrant ships its own skill:
> npx skills add qdrant/mcp-server-qdrant
> [skills.sh](https://skills.sh/qdrant/mcp-server-qdrant) · [GitHub](https://github.com/qdrant/mcp-server-qdrant)
> Security: PASS

Next Steps:
1. docker run qdrant/qdrant and pip install qdrant-client to validate locally
2. Use the LangChain + Qdrant RAG template as a starting point
3. If staying Postgres-only, evaluate pgvector — saves an infra hop

What SKILLmama Is Not

• Not an IDE or autocomplete assistant
• Not a chatbot
• Not a package manager

SKILLmama is a capability oracle: it tells you what to use and why, with evidence.

Project Structure

SKILLmama/
├── skillmama/
│   └── SKILL.md               # the skill — one file, runs on every platform
├── .claude/
│   └── skills/skillmama/
│       └── SKILL.md           # symlink → ../../../skillmama/SKILL.md
├── evals/
│   └── skillmama-ablation.md  # Manual trigger/pipeline eval + result log
└── README.md

One source of truth. Until v1.4.7 this repo carried four hand-maintained copies (codex/AGENTS.md, antigravity/PROMPT.md, .claude/commands/skillmama.md) which had quietly drifted apart more than once. Every platform reads a plain SKILL.md, so the copies were removed and the Claude Code entry is a symlink. Drift is now impossible rather than merely discouraged.

Note for Windows contributors: git needs core.symlinks=true (and Developer Mode) to check out .claude/skills/skillmama/SKILL.md as a real symlink. Without it you'll get a text file containing the target path. It only affects the repo-local slash command, not installs.

Evals

SKILLmama ships a manual eval harness at evals/skillmama-ablation.md: 5 prompts that should trigger the skill, 5 that shouldn't, run skill-on vs. skill-off. It's checked after any change to the Trigger rules or the core phases — the log has already caught and fixed three real bugs: a silent empty scan when the working directory didn't match the stated stack, Maintenance scores presented as verified when they were actually estimated, and a deployment-persistence blind spot (recommending an in-process store without checking whether the target hosting platform's disk actually survives a restart) — the last one found via a genuine paired skill-off/skill-on ablation run, not just inference.

See evals/skill-on-vs-skill-off-comparison.md for the full unedited transcript of that ablation run: the same question asked with and without SKILLmama, side by side.

Inspired by Philipp Schmid's (Google DeepMind) talk "Don't Ship Skills Without Evals," and the paired skill-on/skill-off ablation methodology from SkillsBench (Li et al.), also live at skillsbench.ai.