agent-skill-manager 1.19.0 → 1.21.0

package/README.md

@@ -61,8 +61,8 @@ The more AI agents you use, the worse this gets. Every new tool adds another ski
 - **See everything at once** — List, search, and filter skills across all providers and scopes from one dashboard. No more `ls`-ing through hidden directories.
 - **Install from GitHub in one command** — `asm install github:user/repo` handles cloning, validation, and placement. Supports single-skill repos, multi-skill collections, subfolder URLs, and private repos via SSH.
 - **Catch problems before they bite** — Built-in security scanning flags dangerous patterns (shell execution, network access, credential exposure, obfuscation) before you install. Duplicate audit finds and cleans redundant skills across providers.
-- **Create and test skills locally** — Scaffold new skills with `asm init`, symlink them for live development with `asm link`, audit for security issues, and verify metadata — all before publishing. [See the full local dev workflow ↓](#build-test-and-ship-your-own-skills)
-- **Works with every major agent** — 17 providers built-in: Claude Code, Codex, OpenClaw, Cursor, Windsurf, Cline, Roo Code, Continue, GitHub Copilot, Aider, OpenCode, Zed, Augment, Amp, Gemini CLI, Google Antigravity, and a generic Agents provider. Add custom providers in seconds via config.
+- **Create, test, and publish skills** — Scaffold new skills with `asm init`, symlink them for live development with `asm link`, audit for security issues, verify metadata, and publish to the [ASM Registry](https://github.com/luongnv89/asm-registry) with a single command. [See the full local dev workflow ↓](#build-test-and-ship-your-own-skills)
+- **Works with every major agent** — 18 providers built-in: Claude Code, Codex, OpenClaw, Cursor, Windsurf, Cline, Roo Code, Continue, GitHub Copilot, Aider, OpenCode, Zed, Augment, Amp, Gemini CLI, Google Antigravity, Hermes, and a generic Agents provider. Add custom providers in seconds via config.
 - **Two interfaces, one tool** — Full interactive TUI with keyboard navigation, search, and detail views. Or use the CLI with `--json` for scripting and automation.
 
 <p align="center">
@@ -116,19 +116,49 @@ This creates a `my-skill/SKILL.md` with valid YAML frontmatter and a markdown te
 
 ### 2. Develop with live reload via symlink
 
-Symlink into Claude Code's skill directory:
+`asm link` creates a symlink from your local skill directory into an agent's skill folder. Because it's a symlink, every edit you make to the source is immediately visible to the agent — no reinstall needed.
+
+#### Target a specific tool
 
 ```bash
+# Link into Claude Code
 asm link ./my-skill -p claude
+
+# Link into Codex
+asm link ./my-skill -p codex
+
+# Interactive — pick the tool from a prompt
+asm link ./my-skill
 ```
 
-Or into Codex, or any other tool:
+#### Link multiple skills at once
+
+Pass several paths in a single command to link them all in one step:
 
 ```bash
-asm link ./my-skill -p codex
+asm link ./skill-a ./skill-b ./skill-c -p claude
 ```
 
-Edit the source files — changes are reflected immediately in the agent. No reinstall needed. This is the fastest iteration loop for skill development.
+You can also point at a folder that contains multiple skills (each in its own subdirectory with a `SKILL.md`):
+
+```bash
+# Link every skill found inside ./my-skills-folder
+asm link ./my-skills-folder -p claude
+```
+
+#### Override the symlink name
+
+```bash
+asm link ./my-skill --name my-alias -p claude
+```
+
+#### Force-overwrite an existing symlink
+
+```bash
+asm link ./my-skill -p claude --force
+```
+
+Edit the source files — changes are reflected immediately in the agent. This is the fastest iteration loop for skill development.
 
 ### 3. Audit your skill for security issues
 
@@ -202,6 +232,41 @@ asm install github:you/awesome-skill -p claude --yes --json
 
 This catches issues that local development misses — broken repo structure, missing files, invalid frontmatter in a clean install context.
 
+### 6. Publish to the ASM Registry
+
+Once your skill is ready and on GitHub, submit it to the [ASM Registry](https://github.com/luongnv89/asm-registry) so anyone can install it by name:
+
+```bash
+asm publish ./my-skill
+```
+
+This runs a security audit, generates a signed manifest, forks the registry, and opens a pull request automatically. Once merged, your skill is globally discoverable:
+
+```bash
+# Anyone can install it by name — no URL needed
+asm install my-skill
+```
+
+Preview what the manifest will look like before submitting:
+
+```bash
+asm publish --dry-run ./my-skill
+```
+
+Override security warnings (caution: review findings first):
+
+```bash
+asm publish --force ./my-skill
+```
+
+Skip confirmation in CI:
+
+```bash
+asm publish --yes ./my-skill
+```
+
+> **Requires:** [`gh` CLI](https://cli.github.com) authenticated with `gh auth login`. The publish command uses `gh` to fork the registry, create a branch, write the manifest, and open the PR — all without leaving your terminal.
+
 ### Typical local development workflow
 
 1. **Scaffold** — `asm init awesome-skill -p claude`
@@ -210,8 +275,10 @@ This catches issues that local development misses — broken repo structure, mis
 4. Test with your AI agent
 5. **Security audit** — `asm audit security awesome-skill`
 6. **Verify metadata** — `asm inspect awesome-skill`
-7. Push to GitHub
-8. **Verify install flow** — `asm install github:you/awesome-skill`
+7. **Score quality** — `asm eval ./awesome-skill` (add `--runtime` for skillgrade runtime evals)
+8. Push to GitHub
+9. **Verify install flow** — `asm install github:you/awesome-skill`
+10. **Publish to registry** — `asm publish ./awesome-skill`
 
 Whether you're building skills for yourself or publishing them for the community, `asm` gives you the full create → develop → audit → ship pipeline in one tool.
 
@@ -251,6 +318,91 @@ asm index search "your-skill" --json
 
 Each indexed skill in the output JSON includes `"verified": true` or `"verified": false`. If verification fails, the ingestion debug log (set `ASM_DEBUG=1`) prints the specific reasons.
 
+### Runtime Evaluation (`asm eval`)
+
+Static verification tells you the SKILL.md is well-formed. `asm eval` goes further and answers two orthogonal questions about any skill on disk:
+
+1. **Is it well-written?** — `quality@1.0.0` ships by default and runs a scored rubric over structure, frontmatter, clarity, and safety.
+2. **Does it actually work?** — `asm eval --runtime` shells out to [skillgrade](https://github.com/mgechev/skillgrade) for deterministic + LLM-judge runtime evals in a Docker sandbox, with CI-ready exit codes.
+
+**Zero-setup install:** skillgrade ships as a direct dependency of `asm`. After `npm install -g agent-skill-manager`, `asm eval --runtime` just works — no `npm i -g skillgrade`, no PATH hijacking. Override with `ASM_SKILLGRADE_BIN=/path/to/skillgrade` if you want to point at a different binary.
+
+```bash
+# Static quality lint (default)
+asm eval ./my-skill
+
+# Scaffold eval.yaml for runtime tests
+asm eval ./my-skill --runtime init
+
+# Run the skillgrade runtime provider
+asm eval ./my-skill --runtime --preset smoke
+
+# CI-friendly JSON
+asm eval ./my-skill --runtime --machine --threshold 0.8
+
+# List registered eval providers
+asm eval-providers list
+
+# Diff two provider versions before promoting an upgrade
+asm eval ./my-skill --compare skillgrade@1.0.0,skillgrade@2.0.0-next
+```
+
+The eval surface is a pluggable provider framework: each provider implements a common `EvalProvider` contract and resolves via semver range, so you can pin a version in `~/.asm/config.yml`, diff two versions side-by-side with `--compare`, and add new providers without touching the CLI. See [`docs/eval-providers.md`](./docs/eval-providers.md) for the provider model and [`docs/skillgrade-integration.md`](./docs/skillgrade-integration.md) for skillgrade install, presets, and CI usage.
+
+---
+
+## ASM Registry — Install and Publish Skills by Name
+
+The [ASM Registry](https://github.com/luongnv89/asm-registry) is the curated index of community-published skills. Once a skill is listed, anyone can install it by name — no GitHub URL needed.
+
+### Install from the registry
+
+```bash
+# Install by bare name (searches the registry)
+asm install code-review
+
+# Install by scoped name (author/skill — always unambiguous)
+asm install luongnv89/code-review
+
+# Force a fresh registry fetch (bypasses the 1-hour cache)
+asm install code-review --no-cache
+```
+
+`asm install` resolves the name against the registry index, downloads the manifest, clones the exact pinned commit, and installs the skill to your agent.
+
+### Publish your skill to the registry
+
+```bash
+asm publish ./my-skill
+```
+
+The publish pipeline:
+
+1. **Validates** your `SKILL.md` frontmatter (name, description, version)
+2. **Security audit** — blocks dangerous skills automatically; warns on risky patterns
+3. **Generates a manifest** with the current commit SHA and a `skill_path` for multi-skill repos
+4. **Opens a PR** against [luongnv89/asm-registry](https://github.com/luongnv89/asm-registry) via the `gh` CLI
+
+The registry CI validates schema, checks author identity, runs a duplicate check, typosquat detection, and an independent security scan before any maintainer reviews. Once merged, the index rebuilds automatically and your skill is live.
+
+| Flag        | Description                                |
+| ----------- | ------------------------------------------ |
+| `--dry-run` | Preview the manifest without creating a PR |
+| `--force`   | Override warning-level security findings   |
+| `--yes`     | Skip the confirmation prompt               |
+| `--machine` | Output as a machine-readable JSON envelope |
+
+### How registry resolution works
+
+When you run `asm install code-review`:
+
+1. `asm` fetches the registry index (cached for 1 hour at `~/.config/agent-skill-manager/registry-cache.json`)
+2. Finds the manifest for `code-review` — including the pinned `commit` and `skill_path`
+3. Clones the repository at that exact commit and navigates to the skill subdirectory
+4. Installs as if you had run `asm install github:author/repo#commit:skill_path`
+
+If multiple authors publish a skill with the same name, `asm` shows a disambiguation prompt. Use a scoped name (`author/skill`) to skip it.
+
 ---
 
 ## Get Started in 30 Seconds
@@ -323,7 +475,7 @@ asm install github:anthropics/skills --all
 
 ## Supported Agent Tools
 
-`asm` ships with **17 built-in providers**, all enabled by default. Disable any you don't need via `asm config edit`.
+`asm` ships with **18 built-in providers**, all enabled by default. Disable any you don't need via `asm config edit`.
 
 | Tool               | Global Path                       | Project Path            | Default |
 | ------------------ | --------------------------------- | ----------------------- | :-----: |
@@ -344,6 +496,7 @@ asm install github:anthropics/skills --all
 | Amp                | `~/.amp/skills/`                  | `.amp/skills/`          | enabled |
 | Gemini CLI         | `~/.gemini/skills/`               | `.gemini/skills/`       | enabled |
 | Google Antigravity | `~/.antigravity/skills/`          | `.antigravity/skills/`  | enabled |
+| Hermes             | `~/.hermes/skills/`               | `.hermes/skills/`       | enabled |
 
 Disable a provider — opens config in `$EDITOR`, set `"enabled": false` for any provider:
 
@@ -361,10 +514,10 @@ Need a tool not listed? Add a custom provider entry to the config.
 Yes. `asm` is MIT licensed and free forever. No accounts, no telemetry, no paywalls.
 
 **Is it actively maintained?**
-v1.19.0 shipped on March 28, 2026. The project has had 28 releases. Check the [changelog](docs/CHANGELOG.md) for the full history.
+v1.21.0 shipped on April 19, 2026. The project has had 30 releases. Check the [changelog](docs/CHANGELOG.md) for the full history.
 
 **Which AI agents does it support?**
-17 providers built-in: Claude Code, Codex, OpenClaw, Cursor, Windsurf, Cline, Roo Code, Continue, GitHub Copilot, Aider, OpenCode, Zed, Augment, Amp, Gemini CLI, Google Antigravity, and a generic Agents provider. All 17 are enabled by default; disable any you don't need via `asm config edit`. You can also add any custom agent that stores skills as directories with a `SKILL.md` file.
+18 providers built-in: Claude Code, Codex, OpenClaw, Cursor, Windsurf, Cline, Roo Code, Continue, GitHub Copilot, Aider, OpenCode, Zed, Augment, Amp, Gemini CLI, Google Antigravity, Hermes, and a generic Agents provider. All 18 are enabled by default; disable any you don't need via `asm config edit`. You can also add any custom agent that stores skills as directories with a `SKILL.md` file.
 
 **How does it compare to managing skills manually?**
 Manual management means remembering where each agent stores skills, cloning repos by hand, checking for duplicates yourself, and having no security scanning. `asm` automates all of that with one command.
@@ -413,27 +566,31 @@ asm
 
 ### Commands
 
-| Command                         | Description                                 |
-| ------------------------------- | ------------------------------------------- |
-| `asm list`                      | List all discovered skills                  |
-| `asm search <query>`            | Search by name/description/provider         |
-| `asm inspect <skill-name>`      | Show detailed info for a skill              |
-| `asm install <source>`          | Install a skill from GitHub                 |
-| `asm uninstall <skill-name>`    | Remove a skill (with confirmation)          |
-| `asm init <name>`               | Scaffold a new skill with SKILL.md template |
-| `asm link <path>`               | Symlink a local skill for live development  |
-| `asm audit`                     | Detect duplicate skills                     |
-| `asm audit security <name>`     | Run security audit on a skill               |
-| `asm stats`                     | Show aggregate skill metrics dashboard      |
-| `asm export`                    | Export skill inventory as JSON manifest     |
-| `asm index ingest <repo>`       | Index a skill repo for searching            |
-| `asm index search <query>`      | Search indexed skills                       |
-| `asm index list`                | List indexed repositories                   |
-| `asm index remove <owner/repo>` | Remove a repo from the index                |
-| `asm config show`               | Print current config                        |
-| `asm config path`               | Print config file path                      |
-| `asm config reset`              | Reset config to defaults                    |
-| `asm config edit`               | Open config in $EDITOR                      |
+| Command                         | Description                                           |
+| ------------------------------- | ----------------------------------------------------- |
+| `asm list`                      | List all discovered skills                            |
+| `asm search <query>`            | Search by name/description/provider                   |
+| `asm inspect <skill-name>`      | Show detailed info for a skill                        |
+| `asm install <source>`          | Install a skill from GitHub or the registry           |
+| `asm publish [path]`            | Publish a skill to the ASM Registry                   |
+| `asm uninstall <skill-name>`    | Remove a skill (with confirmation)                    |
+| `asm init <name>`               | Scaffold a new skill with SKILL.md template           |
+| `asm link <path> [<path2> ...]` | Symlink one or more local skills for live development |
+| `asm audit`                     | Detect duplicate skills                               |
+| `asm audit security <name>`     | Run security audit on a skill                         |
+| `asm eval <skill>`              | Score a skill via the pluggable eval framework        |
+| `asm eval <skill> --runtime`    | Runtime evaluation via skillgrade (LLM-judge)         |
+| `asm eval-providers list`       | List registered eval providers and versions           |
+| `asm stats`                     | Show aggregate skill metrics dashboard                |
+| `asm export`                    | Export skill inventory as JSON manifest               |
+| `asm index ingest <repo>`       | Index a skill repo for searching                      |
+| `asm index search <query>`      | Search indexed skills                                 |
+| `asm index list`                | List indexed repositories                             |
+| `asm index remove <owner/repo>` | Remove a repo from the index                          |
+| `asm config show`               | Print current config                                  |
+| `asm config path`               | Print config file path                                |
+| `asm config reset`              | Reset config to defaults                              |
+| `asm config edit`               | Open config in $EDITOR                                |
 
 ### Global Options
 
@@ -485,6 +642,24 @@ Audit all installed skills:
 asm audit security --all
 ```
 
+Score a skill with the static quality provider:
+
+```bash
+asm eval ./my-skill
+```
+
+Run the skillgrade runtime evaluator (requires `skillgrade` on PATH):
+
+```bash
+asm eval ./my-skill --runtime --preset smoke
+```
+
+List registered eval providers:
+
+```bash
+asm eval-providers list
+```
+
 Scaffold a skill, link it for live testing, audit, and inspect:
 
 ```bash
@@ -492,7 +667,11 @@ asm init my-skill -p claude
 ```
 
 ```bash
+# Link globally (available in all projects)
 asm link ./my-skill -p claude
+
+# Link multiple skills at once
+asm link ./skill-a ./skill-b -p claude
 ```
 
 ```bash
@@ -644,7 +823,7 @@ The install command clones the repository, validates `SKILL.md` files, scans for
 <details>
 <summary><strong>Configuration</strong></summary>
 
-On first run, a config file is created at `~/.config/agent-skill-manager/config.json` with 17 default providers, all enabled:
+On first run, a config file is created at `~/.config/agent-skill-manager/config.json` with 18 default providers, all enabled:
 
 ```json
 {
@@ -960,16 +1139,18 @@ agent-skill-manager/
 <details>
 <summary><strong>Documentation</strong></summary>
 
-| Document                              | Description                              |
-| ------------------------------------- | ---------------------------------------- |
-| [Architecture](docs/ARCHITECTURE.md)  | System design, components, and data flow |
-| [Development](docs/DEVELOPMENT.md)    | Local setup, testing, and debugging      |
-| [Deployment](docs/DEPLOYMENT.md)      | Publishing and CI pipeline               |
-| [Changelog](docs/CHANGELOG.md)        | Version history                          |
-| [Brand Kit](docs/brand_kit.md)        | Logo, colors, and typography             |
-| [Contributing](CONTRIBUTING.md)       | How to contribute                        |
-| [Security](SECURITY.md)               | Vulnerability reporting                  |
-| [Code of Conduct](CODE_OF_CONDUCT.md) | Community guidelines                     |
+| Document                                                 | Description                                              |
+| -------------------------------------------------------- | -------------------------------------------------------- |
+| [Architecture](docs/ARCHITECTURE.md)                     | System design, components, and data flow                 |
+| [Eval Providers](docs/eval-providers.md)                 | Pluggable eval framework, `--compare`, adding a provider |
+| [Skillgrade Integration](docs/skillgrade-integration.md) | Install, presets, CI usage, troubleshooting              |
+| [Development](docs/DEVELOPMENT.md)                       | Local setup, testing, and debugging                      |
+| [Deployment](docs/DEPLOYMENT.md)                         | Publishing and CI pipeline                               |
+| [Changelog](docs/CHANGELOG.md)                           | Version history                                          |
+| [Brand Kit](docs/brand_kit.md)                           | Logo, colors, and typography                             |
+| [Contributing](CONTRIBUTING.md)                          | How to contribute                                        |
+| [Security](SECURITY.md)                                  | Vulnerability reporting                                  |
+| [Code of Conduct](CODE_OF_CONDUCT.md)                    | Community guidelines                                     |
 
 </details>