@neta-art/neta-search-cli 0.2.45 → 0.2.50

package/README.md

@@ -13,12 +13,18 @@ npx -y @neta-art/neta-search-cli@latest skills init <name>               # scaff
 npx -y @neta-art/neta-search-cli@latest skills lint <name>               # static check before submitting (local; nothing is sent)
 npx -y @neta-art/neta-search-cli@latest skills submit <name>             # submit .agents/skills/<name>/ to the hub and wait for the result
 npx -y @neta-art/neta-search-cli@latest skills feedback [name]           # read Neta's review feedback on your own skills
+npx -y @neta-art/neta-search-cli@latest skills propose <name> --note "…"  # send your changes to an installed skill's author as a suggestion
+npx -y @neta-art/neta-search-cli@latest skills proposals [name] [id]      # suggestions others sent for your skills (--mine: the ones you sent)
 ```
 
 `<id>` is what `find` prints: a handle such as `neta-skills/holo-pack-opening` or `cohub/agent-browser`. Skills without a handle are listed as `cohub:<spaceId>/<name>`, which works everywhere a handle does. `update` and `remove` also accept the directory name under `.agents/skills/`.
 
 `remove` deletes installed skills only. Skills you wrote yourself (no install record) are left alone unless you pass `--force`.
 
+An installed skill you changed after installing it is marked `[edited locally]` in `list` (`"edited": true` in `--json`, plus `"changed": {"modified", "added", "removed"}` file lists for skills installed with this version or later). `update` keeps your changes even when a newer version is out, and `remove` leaves it alone; `update <name> --force` / `remove <name> --force` discard the changes (`update --force` needs names).
+
+`add` does not replace what is already in the target directory unless it is the same skill, unchanged: a copy you changed, a skill from another source, a pointer or a skill written in this space are left alone and `add` exits 1 saying what is there. Pass `--force` to replace it.
+
 `use` prints the skill directory and the full SKILL.md, so an agent can follow it right away; relative paths in SKILL.md resolve against that directory. If the local entry is a pointer (frontmatter `metadata.neta-skill-id`, a handle or an id), `use` fetches the full skill it points to; with `metadata.neta-skill-version: verified` it fetches the version that passed Neta's review. `use <id> --verified` does the same directly: it fails if there is no reviewed version and never falls back to the latest.
 
 Every result has a trust level: `platform` (published by the Neta team), `verified` (made or reviewed by the Neta team) or `community` (shared by a Cohub user, not reviewed). `find --json` items carry it as `trust`, plus `basic: true` for built-in Cohub abilities and `author` for community skills. `use` and `add` say so when a skill is a community one; read those before relying on them.
@@ -27,9 +33,13 @@ Each `find --json` item carries a ready-to-run `use` command (`skills use <id> -
 
 Use `@latest` (or an exact version): with a range such as `@0.2`, npx keeps running whatever matching version it cached earlier and never checks for a newer one.
 
+Improving someone else's skill: install it with `add`, change it, then either send your changes to its author with `propose <name> --note "what you changed and why"` (nothing is published; only the author and you can see it; the author is read from the install record, or give `--to <handle>`), or `submit` it as your own adaptation. Whether that publishes depends on the original: a creator's skill accepts changes as suggestions only unless its author writes `neta-adaptations: open` in its frontmatter metadata (then `submit` is refused and points you to `propose`); Neta's own skills allow adaptations. Keep the install record `.neta-source.json`: it is how where the skill came from is recorded. An unchanged copy cannot be submitted. `propose <name> --withdraw` takes your suggestion back; `proposals --mine` shows what became of the ones you sent.
+
+Suggestions for your own skills: `proposals` lists the skills that have them, `proposals <name>` lists them, and `proposals <name> <id>` saves one to `.neta-search/skill-proposals/<name>/<id>/` with a comparison to your current files (`changes.md`). To adopt one, change your skill and run `submit <name> --adopts <id>`: the sender is credited together with the publication, and the result lists who was credited. If you forgot `--adopts`, submit the same version again with it, or run `proposals <name> <id> --adopted-in <digest>`. `proposals <name> <id> --decline --reason "…"` declines it (the sender sees the reason). `list` marks your skills that have open suggestions.
+
 `submit` publishes one of your skills and works inside a Cohub sandbox only, from a chat started by the space owner: it runs the static check first (see `lint`), sends this version, and waits for the result: published (with its digest) or why not. Nothing is shared until you submit: `use` only runs a skill. `submit --withdraw <name>` takes it down again; deleting the directory does not.
 
-`lint [name-or-dir]` checks a skill folder locally and sends nothing. **Errors** are what the skills site would reject (a missing frontmatter or description, a SKILL.md saved with Windows line endings or a byte-order mark, size limits, a SKILL.md or skill folder that is a symbolic link, anything that looks like a secret, a folder installed from someone else); `submit` stops on them. **Warnings** are suggestions and never block: other symbolic links (skipped when publishing), paths the skill mentions that are not in it, hard-coded `/workspace/...` paths (use paths relative to the skill folder or the current folder), missing or incomplete test declarations (`evals/matrix.json`), common writing problems (no rule that replies follow the user's language, no hand-off card, no `--work-title`, no out-of-scope section, non-English text hard-coded in the deliverable), ready-made non-English words for the agent to say to users, instructions not written in English (recommended, not required), and the optional `listing.json` (your skill's name and description in `en` / `zh` and up to 6 showcase Works for Studio; only Works made in Studio and shared publicly are shown, not links to other sites). It is a static check, not a review: passing it says nothing about how well the skill works. `--json` for agents.
+`lint [name-or-dir]` checks a skill folder locally and sends nothing. **Errors** are what the skills site would reject (a missing frontmatter or description, a SKILL.md saved with Windows line endings or a byte-order mark, size limits, a SKILL.md or skill folder that is a symbolic link, anything that looks like a secret, a folder installed from someone else); `submit` stops on them. **Warnings** are suggestions and never block: other symbolic links (skipped when publishing), paths the skill mentions that are not in it, hard-coded `/workspace/...` paths (use paths relative to the skill folder or the current folder), missing or incomplete test declarations (`evals/matrix.json`), common writing problems (no rule that replies follow the user's language, no hand-off card, no `--work-title`, no out-of-scope section, non-English text hard-coded in the deliverable), ready-made non-English words for the agent to say to users, instructions not written in English (recommended, not required), and the optional `listing.json` (your skill's name and description in `en` / `zh` and up to 6 showcase Works for Studio; only Works made in Studio and shared publicly are shown, not links to other sites; refer to a Work by its id or its `https://neta.art/w/<id>` link). After `submit`, the result says which languages of the name and description were read and which showcase Works can be shown, and why not. It is a static check, not a review: passing it says nothing about how well the skill works. `--json` for agents.
 
 `feedback [name]` reads Neta's review feedback on your own skills (Neta reviews skills it nominates; when one needs changes, the feedback says what, where in the files, and how to fix it). Like `submit`, it works only inside a Cohub sandbox, in a chat the space owner started in that space: the server checks that you are the author before showing anything. `skills list` also marks your own skills that have feedback (it does the same check while it looks for updates; if it cannot check, it just shows the list). Without a name, `feedback` lists your skills that have feedback; with a name it saves the latest feedback to `.neta-search/skill-feedback/<name>/<version>/` (`fix-pack.json` for agents, `feedback.md` for people) and prints it. `--digest` picks a version.