# Augment

> Gives this project a NEW capability on demand. Use the moment the user needs something the current setup can't do well — a new framework, a service integration (Stripe, Postgres, Twilio…), a deploy target, a niche workflow. Searches the open ecosystem for a fitting skill/MCP across platforms, installs the best vetted one, and if nothing fits, forges a bespoke skill. Triggers: 'can you also…', 'I need to…', 'set up…', 'integrate…', 'how do I … here', or any task with no matching installed skill.

- Skill: `shivae372/augment` (Agent Skill)
- Install (CLI): `npx skillmds@latest add shivae372/augment`
- Raw SKILL.md: https://api.skillmd.com/api/skills/shivae372/augment/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: DevOps & Infra
- Author: shivae372 (https://skillmd.com/u/shivae372)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/shivae372/augment

---


## Purpose
Close the gap between what the user wants and what this setup can do — in the moment,
without them leaving the conversation. This is the engine that makes a fresh Claude
Code project grow into exactly the toolkit THIS user needs.

## When to use this
- The user asks for a capability with no matching skill/command/agent (check the
  capability manifest: `python3 .claude/engine/doctor.py --manifest`).
- A `[gap]` nudge was injected by the real-time hook (`.claude/state/needs.jsonl`).
- The user explicitly says "augment", "find a skill for…", "add support for…".

## Steps

### 1. Name the capability precisely
Restate what's missing as a short search phrase (e.g. "stripe payments",
"deploy to fly.io", "supabase row level security"). Confirm with the user in one line.

### 2. Search the open ecosystem (across platforms)
```bash
python3 .claude/engine/skill_finder.py "<capability>" --json
```
This queries, in parallel and offline-tolerant: Anthropic's official skills,
GitHub (topic + repo search), the MCP Registry, and Smithery (if `SMITHERY_API_KEY`
is set). Results come back ranked by relevance with a `trust` score and `flags`.
Set `GITHUB_TOKEN` first if available — it lifts GitHub's rate limit.

### 3. Vet before you trust (never auto-install blindly)
Reject or down-rank a candidate that is: brand-new (<30d) with no stars, has a vague
or missing description, grants `Bash` with no constraint, or fetches remote code at
runtime. Prefer: official (`anthropic/skills`), `verified` (Smithery), pinned commit
SHAs, and repos with real usage. Show the user the top 1–3 with their trust/flags and
let them pick when it's a close call.

### 4a. Install a good match
- **Official skill / plugin:** add it with `/marketplace` (enter `<owner/repo>` when prompted), then `/plugin install <name>@<marketplace>`.
- **MCP server:** `claude mcp add <name> ...` (it activates next session — tell the user).
  Record it in `.mcp.json` so the team gets it too.
- **A SKILL.md in a repo:** fetch it, read it end-to-end, then write it into
  `.claude/skills/<name>/SKILL.md`. Validate: `python3 .claude/engine/skill_forge.py validate <path>`.

### 4b. Nothing fits → forge it
Invoke the **forge** skill to author a detailed, project-specific skill. Do NOT settle
for a generic one — a vague skill is worse than none.

### 4c. Found it another way? Teach the finder (self-extending discovery)
If the web search missed it but you located the capability another way — a specific GitHub
org, a vendor's own JSON search endpoint, or simply "X lives at Y" — record that source so
the engine searches it next time TOO, alongside the web. Discovery then heals and compounds:
```bash
# a whole org that publishes the skills you needed:
echo '{"kind":"github_org","org":"<org>","note":"has <capability> skills/servers"}' \
  | python3 .claude/engine/learn.py source-add
# or a queryable JSON endpoint, or a durable hint:
# {"kind":"http_json","name":"acme","url":"https://api.acme/s?q={query}","name_field":"slug","url_field":"link"}
# {"kind":"hint","name":"...","text":"For <X>, check <Y>"}
```
The next discovery run includes it automatically.

### 5. Make it real now, then learn
- Verify the new capability works (run it once if safe).
- Record what you added so the setup remembers:
```bash
echo '{"category":"stack","text":"Added <capability> via <skill/mcp>","tags":["augment"]}' \
  | python3 .claude/engine/learn.py add
```
- Tell the user the new command/skill is live and how to use it.

## Output
A new, working capability in `.claude/` (skill, command, or MCP server), vetted and
validated, plus a one-line summary of what was added and how to invoke it.

## Guardrails
- Never install a skill you haven't read. Never run a skill's setup script without
  inspecting it. Surface trust flags honestly.
- If discovery returns nothing and the domain is unfamiliar, ask the user one
  clarifying question rather than forging something generic.

## Ecosystem note — codebase understanding → nodo
If the capability the user needs is *understanding the codebase itself* — architecture,
blast radius, "what calls X", dependency/call graph, where a concept lives — that's the
**nodo** sibling, not a web skill. If nodo is installed (`.nodo/` or the `/nodo` skill exists),
use `/nodo` and read `.nodo/nodo-context.json`. If not, offer to install it from the same
marketplace: run `/marketplace` and enter `shivae372/claude-bootstrap`, then `/plugin install nodo@claude-bootstrap`
(or clone `shivae372/nodo`). claude-bootstrap reads nodo's map automatically at session start.