@iambarryking/ag 3.0.1 → 3.1.1

package/README.md

@@ -50,39 +50,42 @@ export OPENROUTER_API_KEY=sk-or-v1-...
 
 ## REPL Commands
 
+All commands follow the pattern: `/noun` to show, `/noun subcommand` to act.
+
 ```
-/help              Show all commands
-/model <name>      Switch model (e.g. /model openai/gpt-4o)
-/model             Show current model
-/models [query]    List OpenRouter models (e.g. /models claude, /models gemini)
-/tools             List loaded tools (built-in + custom)
-/config            Show persistent config (API key, model, base URL)
-/config set <k> <v>  Set a config value (e.g. /config set model openai/gpt-4o)
-/stats             Memory status
-/memory            Show global memory
-/project           Show project memory
-/plan              Show current (latest) plan
-/plan use <name>   Activate an older plan (copies as latest)
-/plans             List all plans
-/paths             Show memory file paths
-/clear project     Clear project memory, plans, and history
-/clear all         Clear everything including global memory
-/exit              Exit
+/help                       Show all commands
+/model                      Show current model
+/model <name>               Switch model (persists to config)
+/model search [query]       Browse OpenRouter models
+/memory                     Show all memory + stats
+/memory global              Show global memory
+/memory project             Show project memory
+/memory clear project|all   Clear memory
+/plan                       Show current plan
+/plan list                  List all plans
+/plan use <name>            Activate an older plan
+/config                     Show config + file paths
+/config set <k> <v>         Set a config value
+/tools                      List loaded tools
+/skill                      List installed skills
+/skill search [query]       Search skills.sh registry
+/skill add <source>         Install skill from registry
+/skill remove <name>        Uninstall a skill
+/exit                       Exit
 ```
 
 ## Tools
 
-| Tool | Purpose |
-|------|---------|
-| `bash` | Run any shell command. The universal tool. |
-| `save_memory` | Persist a fact to global or project memory. |
-| `save_plan` | Save a task plan (timestamped, latest auto-loaded). |
-| `list_plans` | List or read previous plans. |
-| `git_status` | Compact status: branch, ahead/behind, file counts, recent commits. |
-| `git_init` | Initialize a repo, optionally set remote. No-op if already init'd. |
-| `git_branch` | Create branch from latest main/master. Fetches first to ensure latest. |
-| `git_commit` | Stage and commit changes (all or specific files). |
-| `git_push` | Push branch to origin. Outputs a compare URL for creating a PR. |
+All action-based tools follow the pattern: `tool(action, ...params)`.
+
+| Tool | Actions | Purpose |
+|------|---------|---------|
+| `bash` | — | Run any shell command |
+| `memory` | `save` | Persist a fact to global or project memory |
+| `plan` | `save`, `list`, `read` | Manage task plans |
+| `git` | `status`, `init`, `branch`, `commit`, `push` | Git workflow |
+| `web` | `fetch`, `search` | Fetch web pages, search for current info |
+| `skill` | — | Activate a skill by name |
 
 ## Custom Tools
 
@@ -117,6 +120,37 @@ export default {
 
 That's it. No config, no registry. Use `/tools` in the REPL to see what's loaded.
 
+## Skills
+
+Skills are reusable prompt instructions (with optional tools) that the agent activates on-demand. Browse and install from [skills.sh](https://skills.sh):
+
+```bash
+/skill search frontend        # search the registry
+/skill add anthropic/skills@frontend   # install
+/skill                        # list installed
+/skill remove frontend        # uninstall
+```
+
+Skills are SKILL.md files with YAML frontmatter:
+
+```
+~/.ag/skills/          # global (all projects)
+.ag/skills/            # project-local (overrides global)
+```
+
+```markdown
+---
+name: my-skill
+description: When to use this skill. The agent sees this to decide activation.
+---
+
+Your instructions here. The agent loads this content when the skill is activated.
+```
+
+Frontmatter fields: `name` (required), `description` (required), `tools: true` (look for tools.mjs alongside), `always: true` (always inject, don't wait for activation).
+
+The agent sees skill names + descriptions in every prompt. When a task matches, it activates the skill automatically via the `skill` tool, loading the full instructions into context.
+
 ## Configuration
 
 Persistent settings are stored in `~/.ag/config.json`:
@@ -126,12 +160,22 @@ Persistent settings are stored in `~/.ag/config.json`:
   "apiKey": "sk-or-v1-...",
   "model": "anthropic/claude-sonnet-4.6",
   "baseURL": "https://openrouter.ai/api/v1",
-  "maxIterations": 25
+  "maxIterations": 25,
+  "tavilyApiKey": "tvly-..."
 }
 ```
 
 Set values via the REPL (`/config set model openai/gpt-4o`) or edit the file directly. CLI flags and environment variables always take priority over config file values.
 
+For web search, get a free Tavily API key at [tavily.com](https://tavily.com) (no credit card needed). The agent prompts for it on first use, or set it manually:
+
+```bash
+export TAVILY_API_KEY=tvly-...
+# or in the REPL:
+/config set tavilyApiKey tvly-...
+/config set TAVILY_API_KEY tvly-...    # env var name also works
+```
+
 ## Memory
 
 Three tiers, all plain markdown you can edit directly:
@@ -140,6 +184,9 @@ Three tiers, all plain markdown you can edit directly:
 ~/.ag/
   config.json                       # settings: API key, default model, base URL
   memory.md                         # global: preferences, patterns
+  skills/                           # installed skills (from skills.sh or manual)
+    frontend/SKILL.md
+  tools/                            # custom tools (.mjs files)
   projects/
     <id>/
       memory.md                     # project: architecture, decisions
@@ -148,7 +195,7 @@ Three tiers, all plain markdown you can edit directly:
       history.jsonl                 # conversation history
 ```
 
-All memory is injected into the system prompt on every API call (capped at ~6000 chars total to avoid context bloat). The agent reads it automatically and writes via `save_memory` and `save_plan`.
+All memory is injected into the system prompt on every API call (capped at ~6000 chars total to avoid context bloat). The agent reads it automatically and writes via the `memory` and `plan` tools.
 
 ### Git workflow with memory
 
@@ -186,7 +233,7 @@ Or set it permanently:
 ## When to use something else
 
 - **Claude Code** -- if you have a subscription and want the full harness with parallel tool calls, MCP, and a polished UI. ag is not trying to replace it.
-- **aider** -- if your workflow is git-centric (commit-per-change, diff-based editing). ag doesn't know about git.
+- **aider** -- if your workflow is git-centric (commit-per-change, diff-based editing).
 - **Cursor / Windsurf** -- if you want IDE integration. ag is terminal-only.
 
 ag is for when you want a hackable, persistent, model-agnostic agent you fully control in ~600 lines of TypeScript.
@@ -197,15 +244,21 @@ ag is for when you want a hackable, persistent, model-agnostic agent you fully c
 src/
   cli.ts              # entry point
   cli/parser.ts       # arg parsing + help
-  cli/repl.ts         # interactive REPL
-  core/agent.ts       # the loop
+  cli/repl.ts         # interactive REPL (unified /noun commands)
+  core/agent.ts       # the loop + skill activation
   core/config.ts      # persistent config (~/.ag/config.json)
+  core/skills.ts      # skill discovery, parsing, loading
+  core/registry.ts    # skills.sh search + GitHub install
   core/types.ts       # interfaces
   core/colors.ts      # ANSI colors (respects NO_COLOR)
+  core/version.ts     # version from package.json
   memory/memory.ts    # three-tier file memory
   tools/bash.ts       # shell execution
-  tools/memory.ts     # save_memory tool
-  tools/plan.ts       # save_plan + list_plans
+  tools/memory.ts     # memory tool
+  tools/plan.ts       # plan management tool
+  tools/git.ts        # git operations tool
+  tools/web.ts        # web fetch + search tool
+  tools/skill.ts      # skill activation tool
 ```
 
 Zero npm dependencies. Node.js 18+ and TypeScript.

package/dist/cli/parser.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"parser.d.ts","sourceRoot":"","sources":["../../src/cli/parser.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAE9C,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,UAAU,GAAG;IAAE,UAAU,EAAE,MAAM,EAAE,CAAA;CAAE,CAiB/E;AAED,wBAAgB,QAAQ,IAAI,IAAI,CA2C/B"}
+{"version":3,"file":"parser.d.ts","sourceRoot":"","sources":["../../src/cli/parser.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAE9C,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,UAAU,GAAG;IAAE,UAAU,EAAE,MAAM,EAAE,CAAA;CAAE,CAiB/E;AAED,wBAAgB,QAAQ,IAAI,IAAI,CAiC/B"}

package/dist/cli/parser.js

@@ -24,7 +24,7 @@ export function parseArgs(args) {
 }
 export function showHelp() {
     console.log(`
-ag - Persistent AI coding agent with memory (any model via OpenRouter)
+ag - Persistent AI coding agent with memory and skills (any model via OpenRouter)
 
 Usage:
   ag                              # Interactive REPL
@@ -41,29 +41,19 @@ Options:
       --stats               Show memory file locations and status
   -h, --help                Show this help
 
-Config:
-  On first run, ag prompts for your API key and saves it to ~/.ag/config.json.
-  Use /config in the REPL to view or change persistent settings.
-
-Memory (all files editable):
-  ~/.ag/config.json                      Settings: API key, default model, base URL
-  ~/.ag/memory.md                        Global: patterns, preferences, facts
-  ~/.ag/projects/<id>/memory.md          Project: architecture, decisions, gotchas
-  ~/.ag/projects/<id>/plans/             Plans: timestamped, latest auto-loaded
-  ~/.ag/projects/<id>/history.jsonl      Conversation history
-
 REPL commands:
-  /help, /model, /models, /tools, /config, /stats, /memory,
-  /project, /plan, /plans, /paths, /clear, /exit
+  /model [name|search]     Show, switch, or browse models
+  /memory [global|project|clear]  Show or manage memory
+  /plan [list|use <name>]  Show or manage plans
+  /config [set <k> <v>]    Show or set config
+  /tools                   List loaded tools
+  /skill [search|add|remove]  Manage skills from skills.sh
+  /help                    Show all commands
+  /exit                    Exit
 
 Install:
-  npx @iambarryking/ag                      # Run directly
-  npm install -g @iambarryking/ag           # Install globally
-
-Examples:
-  ag "debug this typescript error"
-  ag -m google/gemini-2.5-flash "refactor this"
-  ag -b http://localhost:11434/v1 "hello"   # Local Ollama
+  npx @iambarryking/ag     # Run directly
+  npm install -g @iambarryking/ag  # Install globally
 `);
 }
 //# sourceMappingURL=parser.js.map

package/dist/cli/parser.js.map

@@ -1 +1 @@
-{"version":3,"file":"parser.js","sourceRoot":"","sources":["../../src/cli/parser.ts"],"names":[],"mappings":"AAEA,MAAM,UAAU,SAAS,CAAC,IAAc;IACtC,MAAM,OAAO,GAAe,EAAE,CAAC;IAC/B,MAAM,UAAU,GAAa,EAAE,CAAC;IAEhC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACrC,MAAM,GAAG,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC;QACpB,IAAI,CAAC,GAAG,KAAK,SAAS,IAAI,GAAG,KAAK,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC,MAAM;YAAE,OAAO,CAAC,KAAK,GAAG,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC;aACrF,IAAI,CAAC,GAAG,KAAK,OAAO,IAAI,GAAG,KAAK,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC,MAAM;YAAE,OAAO,CAAC,GAAG,GAAG,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC;aACtF,IAAI,CAAC,GAAG,KAAK,UAAU,IAAI,GAAG,KAAK,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC,MAAM;YAAE,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC;aAC5F,IAAI,CAAC,GAAG,KAAK,YAAY,IAAI,GAAG,KAAK,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC,MAAM;YAAE,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC;aAC/F,IAAI,CAAC,GAAG,KAAK,kBAAkB,IAAI,GAAG,KAAK,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC,MAAM;YAAE,OAAO,CAAC,aAAa,GAAG,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;aACzH,IAAI,GAAG,KAAK,SAAS;YAAE,OAAO,CAAC,KAAK,GAAG,IAAI,CAAC;aAC5C,IAAI,GAAG,KAAK,QAAQ,IAAI,GAAG,KAAK,IAAI;YAAE,OAAO,CAAC,IAAI,GAAG,IAAI,CAAC;aAC1D,IAAI,CAAC,GAAG,CAAC,UAAU,CAAC,GAAG,CAAC;YAAE,UAAU,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IACtD,CAAC;IAED,OAAO,EAAE,GAAG,OAAO,EAAE,UAAU,EAAE,CAAC;AACpC,CAAC;AAED,MAAM,UAAU,QAAQ;IACtB,OAAO,CAAC,GAAG,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAyCb,CAAC,CAAC;AACH,CAAC"}
+{"version":3,"file":"parser.js","sourceRoot":"","sources":["../../src/cli/parser.ts"],"names":[],"mappings":"AAEA,MAAM,UAAU,SAAS,CAAC,IAAc;IACtC,MAAM,OAAO,GAAe,EAAE,CAAC;IAC/B,MAAM,UAAU,GAAa,EAAE,CAAC;IAEhC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACrC,MAAM,GAAG,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC;QACpB,IAAI,CAAC,GAAG,KAAK,SAAS,IAAI,GAAG,KAAK,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC,MAAM;YAAE,OAAO,CAAC,KAAK,GAAG,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC;aACrF,IAAI,CAAC,GAAG,KAAK,OAAO,IAAI,GAAG,KAAK,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC,MAAM;YAAE,OAAO,CAAC,GAAG,GAAG,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC;aACtF,IAAI,CAAC,GAAG,KAAK,UAAU,IAAI,GAAG,KAAK,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC,MAAM;YAAE,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC;aAC5F,IAAI,CAAC,GAAG,KAAK,YAAY,IAAI,GAAG,KAAK,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC,MAAM;YAAE,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC;aAC/F,IAAI,CAAC,GAAG,KAAK,kBAAkB,IAAI,GAAG,KAAK,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC,MAAM;YAAE,OAAO,CAAC,aAAa,GAAG,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;aACzH,IAAI,GAAG,KAAK,SAAS;YAAE,OAAO,CAAC,KAAK,GAAG,IAAI,CAAC;aAC5C,IAAI,GAAG,KAAK,QAAQ,IAAI,GAAG,KAAK,IAAI;YAAE,OAAO,CAAC,IAAI,GAAG,IAAI,CAAC;aAC1D,IAAI,CAAC,GAAG,CAAC,UAAU,CAAC,GAAG,CAAC;YAAE,UAAU,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IACtD,CAAC;IAED,OAAO,EAAE,GAAG,OAAO,EAAE,UAAU,EAAE,CAAC;AACpC,CAAC;AAED,MAAM,UAAU,QAAQ;IACtB,OAAO,CAAC,GAAG,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA+Bb,CAAC,CAAC;AACH,CAAC"}

package/dist/cli/repl.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"repl.d.ts","sourceRoot":"","sources":["../../src/cli/repl.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,KAAK,EAA0B,MAAM,kBAAkB,CAAC;AAUjE,qBAAa,IAAI;IACf,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAQ;IAC9B,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAY;gBAEnB,KAAK,EAAE,KAAK;IAKlB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;YAiCd,aAAa;IA2L3B,OAAO,CAAC,GAAG;CAGZ"}
+{"version":3,"file":"repl.d.ts","sourceRoot":"","sources":["../../src/cli/repl.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,KAAK,EAA0B,MAAM,kBAAkB,CAAC;AAWjE,qBAAa,IAAI;IACf,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAQ;IAC9B,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAY;gBAEnB,KAAK,EAAE,KAAK;IAKlB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;YAuCd,aAAa;IAiP3B,OAAO,CAAC,GAAG;CAGZ"}