neko-harness 0.2.3 → 0.2.4

package/dist/gateway.js

@@ -1192,6 +1192,7 @@ ${text}
 };
 
 // packages/core/src/prompt/resources.ts
+import { existsSync as existsSync2 } from "fs";
 import { readFile as readFile3 } from "fs/promises";
 import { homedir as homedir3 } from "os";
 import { join as join4 } from "path";
@@ -1200,7 +1201,15 @@ var userAgentsFile = (home) => join4(home, ".agents", "AGENTS.md");
 var userSkillsDir = (home) => join4(home, ".agents", "skills");
 var workspaceAgentsFile = (workspace) => join4(workspace, "AGENTS.md");
 var workspaceSkillsDir = (workspace) => join4(workspace, ".agents", "skills");
-var BUILTIN_SKILLS_DIR = fileURLToPath(new URL("../../skills/", import.meta.url));
+var resolveBuiltinSkillsDir = () => {
+  for (const url of [new URL("./skills/", import.meta.url), new URL("../../skills/", import.meta.url)]) {
+    const path = fileURLToPath(url);
+    if (existsSync2(join4(path, "skill-creator", "SKILL.md")))
+      return path;
+  }
+  return null;
+};
+var BUILTIN_SKILLS_DIR = resolveBuiltinSkillsDir();
 var readResources = async (workspace, home, builtinDir, report, invocationName) => {
   const contextFiles = [];
   for (const path of [userAgentsFile(home), workspaceAgentsFile(workspace)]) {

package/dist/neko.js

@@ -1098,11 +1098,19 @@ var init_prompt = __esm(() => {
 });
 
 // packages/core/src/prompt/resources.ts
+import { existsSync as existsSync2 } from "fs";
 import { readFile as readFile3 } from "fs/promises";
 import { homedir as homedir3 } from "os";
 import { join as join4 } from "path";
 import { fileURLToPath } from "url";
-var userAgentsFile = (home) => join4(home, ".agents", "AGENTS.md"), userSkillsDir = (home) => join4(home, ".agents", "skills"), workspaceAgentsFile = (workspace) => join4(workspace, "AGENTS.md"), workspaceSkillsDir = (workspace) => join4(workspace, ".agents", "skills"), BUILTIN_SKILLS_DIR, readResources = async (workspace, home, builtinDir, report, invocationName) => {
+var userAgentsFile = (home) => join4(home, ".agents", "AGENTS.md"), userSkillsDir = (home) => join4(home, ".agents", "skills"), workspaceAgentsFile = (workspace) => join4(workspace, "AGENTS.md"), workspaceSkillsDir = (workspace) => join4(workspace, ".agents", "skills"), resolveBuiltinSkillsDir = () => {
+  for (const url of [new URL("./skills/", import.meta.url), new URL("../../skills/", import.meta.url)]) {
+    const path = fileURLToPath(url);
+    if (existsSync2(join4(path, "skill-creator", "SKILL.md")))
+      return path;
+  }
+  return null;
+}, BUILTIN_SKILLS_DIR, readResources = async (workspace, home, builtinDir, report, invocationName) => {
   const contextFiles = [];
   for (const path of [userAgentsFile(home), workspaceAgentsFile(workspace)]) {
     try {
@@ -1168,7 +1176,7 @@ var userAgentsFile = (home) => join4(home, ".agents", "AGENTS.md"), userSkillsDi
 };
 var init_resources = __esm(() => {
   init_skills();
-  BUILTIN_SKILLS_DIR = fileURLToPath(new URL("../../skills/", import.meta.url));
+  BUILTIN_SKILLS_DIR = resolveBuiltinSkillsDir();
 });
 
 // packages/core/src/prompt/snapshots.ts
@@ -5491,7 +5499,7 @@ var init_src2 = __esm(() => {
 
 // packages/tui/src/gateway.ts
 import { spawn as spawn2 } from "child_process";
-import { existsSync as existsSync2, readFileSync as readFileSync2 } from "fs";
+import { existsSync as existsSync3, readFileSync as readFileSync2 } from "fs";
 import { basename as basename6, dirname as dirname8, join as join11 } from "path";
 import { isServerId as isServerId2 } from "@earendil-works/pi-protocol";
 async function connectToGateway(options = {}) {
@@ -5513,7 +5521,7 @@ async function connectToGateway(options = {}) {
   }
   const socketPath = options.socketPath ?? config.gateway?.socketPath ?? (fileServerId !== undefined ? join11(nekoDir, `${fileServerId}.sock`) : undefined);
   const serverIdFor = (path) => fileServerId ?? serverIdFromSocketPath2(path) ?? readServerId(join11(nekoDir, SERVER_ID_FILENAME2));
-  if (socketPath !== undefined && existsSync2(socketPath)) {
+  if (socketPath !== undefined && existsSync3(socketPath)) {
     const serverId = serverIdFor(socketPath);
     if (serverId !== undefined) {
       try {
@@ -5574,7 +5582,7 @@ ${outputTail()}`);
     const generated = await waitForValue(() => readServerId(join11(plan.nekoDir, SERVER_ID_FILENAME2)), "gateway serverId file", timeoutMs, child, outputTail, spawnError);
     socketPath = join11(plan.nekoDir, `${generated}.sock`);
   }
-  await waitForValue(() => existsSync2(socketPath) ? true : undefined, `gateway ready (socket: ${socketPath})`, timeoutMs, child, outputTail, spawnError);
+  await waitForValue(() => existsSync3(socketPath) ? true : undefined, `gateway ready (socket: ${socketPath})`, timeoutMs, child, outputTail, spawnError);
   const serverId = plan.fileServerId ?? serverIdFromSocketPath2(socketPath) ?? readServerId(join11(plan.nekoDir, SERVER_ID_FILENAME2));
   if (serverId === undefined) {
     throw new Error(`Cannot determine gateway serverId (socket: ${socketPath})`);
@@ -7644,7 +7652,7 @@ switch (command2) {
   }
   case "--version":
   case "-v":
-    console.log("0.2.3");
+    console.log("0.2.4");
     break;
   case undefined:
   case "-h":

package/dist/skills/skill-creator/LICENSE.txt

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Anthropic, PBC.
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/dist/skills/skill-creator/SKILL.md

@@ -0,0 +1,270 @@
+---
+name: skill-creator
+description: Create new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance, or optimize a skill's description for better triggering accuracy.
+---
+
+<!--
+  Adapted from anthropics/skills `skill-creator` (Apache-2.0, see LICENSE.txt in this directory).
+  Trimmed for neko-harness: removed Claude.ai / Cowork platform sections, the subagent-based
+  parallel eval machinery, the eval-viewer server scripts, blind comparison, and
+  package_skill.py / present_files packaging. The test loop is adapted to neko mechanics:
+  project-level skill directories, `/skill:<name>` explicit invocation, and fresh sessions.
+  Update via a dedicated change when refreshing from upstream.
+-->
+
+# Skill Creator
+
+A skill for creating new skills and iteratively improving them.
+
+At a high level, the process of creating a skill goes like this:
+
+- Decide what you want the skill to do and roughly how it should do it
+- Write a draft of the skill
+- Create a few test prompts and run them with the skill active
+- Help the user evaluate the results, qualitatively and (where outputs are objectively checkable) quantitatively
+- Rewrite the skill based on feedback
+- Repeat until you're satisfied
+- Expand the test set and try again at larger scale
+
+Your job when using this skill is to figure out where the user is in this process and then jump in and help them progress through these stages. Maybe they're like "I want to make a skill for X" — help narrow down what they mean, write a draft, write the test cases, figure out how they want to evaluate, and repeat. Or maybe they already have a draft — go straight to the test/iterate part of the loop.
+
+Of course, be flexible: if the user is like "I don't need to run a bunch of evaluations, just vibe with me", do that instead.
+
+After the skill is done (order is flexible), you can also optimize the description for better triggering — there's a dedicated section below.
+
+## Communicating with the user
+
+The skill creator is liable to be used by people across a wide range of familiarity with coding jargon. Pay attention to context cues to understand how to phrase your communication. In the default case:
+
+- "evaluation" and "benchmark" are borderline, but OK
+- for "JSON" and "assertion" you want to see serious cues from the user that they know what those things are before using them without explaining them
+
+It's OK to briefly explain terms if you're in doubt.
+
+---
+
+## Skills in neko
+
+Where skills live and how they load, because this shapes how you test:
+
+- **Locations**: `~/.agents/skills/<name>/` (user level, every workspace) and `<workspace>/.agents/skills/<name>/` (project level, this workspace only). Same-named project skills override user-level ones.
+- **SKILL.md format**: YAML frontmatter + Markdown body. `description` is required (max ~1000 characters); `name` is optional and falls back to the directory name (max 64 characters, no whitespace). Optional `disable-model-invocation: true` hides the skill from the model's automatic discovery while keeping `/skill:<name>` available.
+- **Loading**: only name + description + location go into the system prompt; the body is read on demand. New or edited skill files take effect on the user's **next submitted message** — there is no hot reload mid-run.
+- **Explicit testing**: `/skill:<name> [args]` injects the skill body into a fresh run. This is your main testing tool.
+
+## Creating a skill
+
+### Capture Intent
+
+Start by understanding the user's intent. The current conversation might already contain a workflow the user wants to capture (e.g., they say "turn this into a skill"). If so, extract answers from the conversation history first — the tools used, the sequence of steps, corrections the user made, input/output formats observed. The user may need to fill the gaps, and should confirm before proceeding.
+
+1. What should this skill enable the agent to do?
+2. When should this skill trigger? (what user phrases/contexts)
+3. What's the expected output format?
+4. Should we set up test cases to verify the skill works? Skills with objectively verifiable outputs (file transforms, data extraction, code generation, fixed workflow steps) benefit from test cases. Skills with subjective outputs (writing style, art) often don't need them. Suggest the appropriate default based on the skill type, but let the user decide.
+
+### Interview and Research
+
+Proactively ask questions about edge cases, input/output formats, example files, success criteria, and dependencies. Wait to write test prompts until you've got this part ironed out. If research would help (searching docs, finding similar skills, looking up best practices), do it before asking — come prepared with context to reduce burden on the user.
+
+### Write the SKILL.md
+
+Based on the user interview, fill in these components:
+
+- **name**: Skill identifier (usually just the directory name)
+- **description**: When to trigger, what it does. This is the primary triggering mechanism — include both what the skill does AND specific contexts for when to use it. All "when to use" info goes here, not in the body. Models tend to *undertrigger* skills, so make descriptions a little bit "pushy". For instance, instead of "How to build a dashboard for internal data.", write "How to build a simple fast dashboard to display internal data. Make sure to use this skill whenever the user mentions dashboards, data visualization, internal metrics, or wants to display any kind of company data, even if they don't explicitly ask for a 'dashboard.'"
+- **compatibility**: Required tools, dependencies (optional, rarely needed)
+- **the rest of the skill :)**
+
+Write drafts into the workspace's `.agents/skills/<name>/` (project level) while iterating — it keeps experiments out of the user-level directory and makes cleanup a single `rm -rf`.
+
+### Skill Writing Guide
+
+#### Anatomy of a Skill
+
+```
+skill-name/
+├── SKILL.md (required)
+│   ├── YAML frontmatter (name, description required)
+│   └── Markdown instructions
+└── Bundled Resources (optional)
+    ├── scripts/    - Executable code for deterministic/repetitive tasks
+    ├── references/ - Docs loaded into context as needed
+    └── assets/     - Files used in output (templates, icons, fonts)
+```
+
+#### Progressive Disclosure
+
+Skills use a three-level loading system:
+1. **Metadata** (name + description) - Always in context (~100 words)
+2. **SKILL.md body** - In context whenever skill triggers (<500 lines ideal)
+3. **Bundled resources** - As needed (unlimited, scripts can execute without loading)
+
+These word counts are approximate and you can feel free to go longer if needed.
+
+**Key patterns:**
+- Keep SKILL.md under 500 lines; if you're approaching this limit, add an additional layer of hierarchy along with clear pointers about where the model using the skill should go next to follow up.
+- Reference files clearly from SKILL.md with guidance on when to read them. Relative references resolve against the skill directory (the parent of SKILL.md).
+- For large reference files (>300 lines), include a table of contents.
+
+**Domain organization**: When a skill supports multiple domains/frameworks, organize by variant:
+
+```
+cloud-deploy/
+├── SKILL.md (workflow + selection)
+└── references/
+    ├── aws.md
+    ├── gcp.md
+    └── azure.md
+```
+
+The model reads only the relevant reference file.
+
+#### Principle of Lack of Surprise
+
+Skills must not contain malware, exploit code, or any content that could compromise system security. A skill's contents should not surprise the user in their intent if described. Don't go along with requests to create misleading skills or skills designed to facilitate unauthorized access, data exfiltration, or other malicious activities. Things like a "roleplay as an XYZ" are OK though.
+
+#### Writing Patterns
+
+Prefer using the imperative form in instructions.
+
+**Defining output formats** - You can do it like this:
+
+```markdown
+## Report structure
+ALWAYS use this exact template:
+# [Title]
+## Executive summary
+## Key findings
+## Recommendations
+```
+
+**Examples pattern** - It's useful to include examples:
+
+```markdown
+## Commit message format
+**Example 1:**
+Input: Added user authentication with JWT tokens
+Output: feat(auth): implement JWT-based authentication
+```
+
+### Writing Style
+
+Try to explain to the model why things are important in lieu of heavy-handed musty MUSTs. Use theory of mind and try to make the skill general and not super-narrow to specific examples. Start by writing a draft and then look at it with fresh eyes and improve it.
+
+### Test Cases
+
+After writing the skill draft, come up with 2-3 realistic test prompts — the kind of thing a real user would actually say. Share them with the user: "Here are a few test cases I'd like to try. Do these look right, or do you want to add more?" Then run them.
+
+Save test cases to `evals/evals.json` inside the skill directory. Don't write assertions yet — just the prompts. You'll draft assertions while reviewing the first runs.
+
+```json
+{
+  "skill_name": "example-skill",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "User's task prompt",
+      "expected_output": "Description of expected result",
+      "files": []
+    }
+  ]
+}
+```
+
+## Running and evaluating test cases in neko
+
+neko runs one conversation at a time, so the test loop is conversational rather than scripted:
+
+1. **With-skill runs**: ask the user to open a **new session** and submit `/skill:<name> <test prompt>` for each test case. A fresh session matters — the current conversation already knows how the skill was written, which contaminates the test. Save notable outputs under `<skill-name>-workspace/iteration-<N>/eval-<id>/with_skill/` as a sibling of the skill directory when the outputs are files worth comparing across iterations.
+2. **Baseline runs**: for a new skill, the baseline is the same prompt in a fresh session *without* invoking the skill. For improving an existing skill, snapshot the old version first (`cp -r <skill> <workspace>/skill-snapshot/`) so you can diff behavior.
+3. **Draft assertions while waiting**: good assertions are objectively verifiable and have descriptive names ("output CSV has a profit_margin column", not "output looks right"). Subjective skills (writing style, design) are better evaluated qualitatively — don't force assertions onto things that need human judgment. Add them to `evals/evals.json` as an `expectations` array per eval.
+4. **Grade**: when outputs come back, check each assertion against them. For programmatically checkable assertions, write and run a small script rather than eyeballing it — scripts are faster, more reliable, and reusable across iterations. Record results next to the outputs (e.g. `grading.json` with `{text, passed, evidence}` entries per assertion).
+5. **Review with the user**: present the outputs and grading inline — for each test case, show the prompt, what happened, and what passed/failed. Ask: "How does this look? Anything you'd change?"
+
+## Improving the skill
+
+This is the heart of the loop. You've run the test cases, the user has reviewed the results, and now you need to make the skill better based on their feedback.
+
+1. **Generalize from the feedback.** The skill should work across a million future prompts, not just the few examples you're iterating on. Rather than fiddly overfit changes or oppressively constrictive MUSTs, if there's a stubborn issue, try different metaphors or different patterns of working.
+2. **Keep the prompt lean.** Remove things that aren't pulling their weight. Read the transcripts, not just the final outputs — if the skill makes the model waste time on unproductive steps, cut the parts causing that.
+3. **Explain the why.** Today's LLMs are smart and have good theory of mind. If you find yourself writing ALWAYS or NEVER in all caps, that's a yellow flag — reframe and explain the reasoning so the model understands why the thing you're asking for matters.
+4. **Look for repeated work across test cases.** If every test run independently wrote a similar helper script or took the same multi-step approach, that's a strong signal the skill should bundle that script in `scripts/` and reference it. This saves every future invocation from reinventing the wheel.
+
+Take your time and really mull improvements over. Write a draft revision, then look at it anew.
+
+### The iteration loop
+
+After improving the skill:
+
+1. Apply your improvements to the skill
+2. Rerun all test cases in fresh sessions (new iteration directory), including baselines
+3. Review with the user, read the feedback, improve again, repeat
+
+Keep going until the user is happy, the feedback is all empty, or you're not making meaningful progress.
+
+---
+
+## Description Optimization
+
+The description field in SKILL.md frontmatter is the primary mechanism that determines whether the skill triggers. After creating or improving a skill, offer to optimize it.
+
+### Step 1: Generate trigger eval queries
+
+Create 20 eval queries — a mix of should-trigger and should-not-trigger. Save as JSON:
+
+```json
+[
+  {"query": "the user prompt", "should_trigger": true},
+  {"query": "another prompt", "should_trigger": false}
+]
+```
+
+The queries must be realistic — concrete and specific, with file paths, personal context, column names, company names, URLs, a little backstory. Some lowercase, some with typos or casual speech. Focus on edge cases rather than clear-cut ones.
+
+Bad: `"Format this data"`, `"Extract text from PDF"`
+
+Good: `"ok so my boss just sent me this xlsx file (its in my downloads, called something like 'Q4 sales final FINAL v2.xlsx') and she wants me to add a column that shows the profit margin as a percentage..."`
+
+For **should-trigger** queries (8-10), cover different phrasings of the same intent — formal and casual — including cases where the user doesn't name the skill or file type but clearly needs it. For **should-not-trigger** queries (8-10), the valuable ones are near-misses: adjacent domains, ambiguous phrasing sharing keywords but needing something different. "Write a fibonacci function" as a negative for a PDF skill is too easy — it tests nothing.
+
+Note that models only consult skills for tasks they can't easily handle on their own — simple one-step queries may not trigger a skill even with a perfect description. Make your eval queries substantive enough that consulting a skill would actually help.
+
+### Step 2: Review with user
+
+Present the eval set for review using the HTML template in this skill's `assets/eval_review.html`:
+
+1. Read the template
+2. Replace the placeholders: `__EVAL_DATA_PLACEHOLDER__` → the JSON array (no quotes — it's a JS assignment), `__SKILL_NAME_PLACEHOLDER__` → the skill's name, `__SKILL_DESCRIPTION_PLACEHOLDER__` → the current description
+3. Write to a temp file (e.g. `/tmp/eval_review_<skill-name>.html`) and open it with `open` (macOS) or tell the user the path
+4. The user can edit queries, toggle should-trigger, add/remove entries, then "Export Eval Set" downloads the final JSON
+
+This step matters — bad eval queries lead to bad descriptions.
+
+### Step 3: Iterate the description
+
+For each should-trigger query, reason honestly about whether the current description would make a model pick this skill; for each should-not-trigger query, whether it would wrongly fire. Rewrite the description to fix the failures, keeping it pushy but honest. Show the user before/after. The real confirmation is behavioral: the user tries a few of the trigger queries in fresh sessions and sees whether the skill gets picked up.
+
+---
+
+## Packaging for the skill market
+
+When the user wants to share a skill through the skill market, package the directory as a zip with the skill folder as the single top-level entry (the market requires exactly one SKILL.md per package):
+
+```bash
+cd <parent-of-skill-dir> && zip -r <name>.zip <name>
+```
+
+Hand the resulting zip to the user — uploads are done by market administrators, not from this client.
+
+---
+
+Repeating the core loop for emphasis:
+
+- Figure out what the skill is about
+- Draft or edit the skill (in the workspace's `.agents/skills/`)
+- Test via fresh sessions and `/skill:<name>`
+- Evaluate with the user, improve, repeat
+- Package the final skill and hand it to the user
+
+Good luck!

package/dist/skills/skill-creator/assets/eval_review.html

@@ -0,0 +1,146 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>Eval Set Review - __SKILL_NAME_PLACEHOLDER__</title>
+  <link rel="preconnect" href="https://fonts.googleapis.com">
+  <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+  <link href="https://fonts.googleapis.com/css2?family=Poppins:wght@500;600&family=Lora:wght@400;500&display=swap" rel="stylesheet">
+  <style>
+    * { box-sizing: border-box; margin: 0; padding: 0; }
+    body { font-family: 'Lora', Georgia, serif; background: #faf9f5; padding: 2rem; color: #141413; }
+    h1 { font-family: 'Poppins', sans-serif; margin-bottom: 0.5rem; font-size: 1.5rem; }
+    .description { color: #b0aea5; margin-bottom: 1.5rem; font-style: italic; max-width: 900px; }
+    .controls { margin-bottom: 1rem; display: flex; gap: 0.5rem; }
+    .btn { font-family: 'Poppins', sans-serif; padding: 0.5rem 1rem; border: none; border-radius: 6px; cursor: pointer; font-size: 0.875rem; font-weight: 500; }
+    .btn-add { background: #6a9bcc; color: white; }
+    .btn-add:hover { background: #5889b8; }
+    .btn-export { background: #d97757; color: white; }
+    .btn-export:hover { background: #c4613f; }
+    table { width: 100%; max-width: 1100px; border-collapse: collapse; background: white; border-radius: 6px; overflow: hidden; box-shadow: 0 1px 3px rgba(0,0,0,0.08); }
+    th { font-family: 'Poppins', sans-serif; background: #141413; color: #faf9f5; padding: 0.75rem 1rem; text-align: left; font-size: 0.875rem; }
+    td { padding: 0.75rem 1rem; border-bottom: 1px solid #e8e6dc; vertical-align: top; }
+    tr:nth-child(even) td { background: #faf9f5; }
+    tr:hover td { background: #f3f1ea; }
+    .section-header td { background: #e8e6dc; font-family: 'Poppins', sans-serif; font-weight: 500; font-size: 0.8rem; color: #141413; text-transform: uppercase; letter-spacing: 0.05em; }
+    .query-input { width: 100%; padding: 0.4rem; border: 1px solid #e8e6dc; border-radius: 4px; font-size: 0.875rem; font-family: 'Lora', Georgia, serif; resize: vertical; min-height: 60px; }
+    .query-input:focus { outline: none; border-color: #d97757; box-shadow: 0 0 0 2px rgba(217,119,87,0.15); }
+    .toggle { position: relative; display: inline-block; width: 44px; height: 24px; }
+    .toggle input { opacity: 0; width: 0; height: 0; }
+    .toggle .slider { position: absolute; inset: 0; background: #b0aea5; border-radius: 24px; cursor: pointer; transition: 0.2s; }
+    .toggle .slider::before { content: ""; position: absolute; width: 18px; height: 18px; left: 3px; bottom: 3px; background: white; border-radius: 50%; transition: 0.2s; }
+    .toggle input:checked + .slider { background: #d97757; }
+    .toggle input:checked + .slider::before { transform: translateX(20px); }
+    .btn-delete { background: #c44; color: white; padding: 0.3rem 0.6rem; border: none; border-radius: 4px; cursor: pointer; font-size: 0.75rem; font-family: 'Poppins', sans-serif; }
+    .btn-delete:hover { background: #a33; }
+    .summary { margin-top: 1rem; color: #b0aea5; font-size: 0.875rem; }
+  </style>
+</head>
+<body>
+  <h1>Eval Set Review: <span id="skill-name">__SKILL_NAME_PLACEHOLDER__</span></h1>
+  <p class="description">Current description: <span id="skill-desc">__SKILL_DESCRIPTION_PLACEHOLDER__</span></p>
+
+  <div class="controls">
+    <button class="btn btn-add" onclick="addRow()">+ Add Query</button>
+    <button class="btn btn-export" onclick="exportEvalSet()">Export Eval Set</button>
+  </div>
+
+  <table>
+    <thead>
+      <tr>
+        <th style="width:65%">Query</th>
+        <th style="width:18%">Should Trigger</th>
+        <th style="width:10%">Actions</th>
+      </tr>
+    </thead>
+    <tbody id="eval-body"></tbody>
+  </table>
+
+  <p class="summary" id="summary"></p>
+
+  <script>
+    const EVAL_DATA = __EVAL_DATA_PLACEHOLDER__;
+
+    let evalItems = [...EVAL_DATA];
+
+    function render() {
+      const tbody = document.getElementById('eval-body');
+      tbody.innerHTML = '';
+
+      // Sort: should-trigger first, then should-not-trigger
+      const sorted = evalItems
+        .map((item, origIdx) => ({ ...item, origIdx }))
+        .sort((a, b) => (b.should_trigger ? 1 : 0) - (a.should_trigger ? 1 : 0));
+
+      let lastGroup = null;
+      sorted.forEach(item => {
+        const group = item.should_trigger ? 'trigger' : 'no-trigger';
+        if (group !== lastGroup) {
+          const headerRow = document.createElement('tr');
+          headerRow.className = 'section-header';
+          headerRow.innerHTML = `<td colspan="3">${item.should_trigger ? 'Should Trigger' : 'Should NOT Trigger'}</td>`;
+          tbody.appendChild(headerRow);
+          lastGroup = group;
+        }
+
+        const idx = item.origIdx;
+        const tr = document.createElement('tr');
+        tr.innerHTML = `
+          <td><textarea class="query-input" onchange="updateQuery(${idx}, this.value)">${escapeHtml(item.query)}</textarea></td>
+          <td>
+            <label class="toggle">
+              <input type="checkbox" ${item.should_trigger ? 'checked' : ''} onchange="updateTrigger(${idx}, this.checked)">
+              <span class="slider"></span>
+            </label>
+            <span style="margin-left:8px;font-size:0.8rem;color:#b0aea5">${item.should_trigger ? 'Yes' : 'No'}</span>
+          </td>
+          <td><button class="btn-delete" onclick="deleteRow(${idx})">Delete</button></td>
+        `;
+        tbody.appendChild(tr);
+      });
+      updateSummary();
+    }
+
+    function escapeHtml(text) {
+      const div = document.createElement('div');
+      div.textContent = text;
+      return div.innerHTML;
+    }
+
+    function updateQuery(idx, value) { evalItems[idx].query = value; updateSummary(); }
+    function updateTrigger(idx, value) { evalItems[idx].should_trigger = value; render(); }
+    function deleteRow(idx) { evalItems.splice(idx, 1); render(); }
+
+    function addRow() {
+      evalItems.push({ query: '', should_trigger: true });
+      render();
+      const inputs = document.querySelectorAll('.query-input');
+      inputs[inputs.length - 1].focus();
+    }
+
+    function updateSummary() {
+      const trigger = evalItems.filter(i => i.should_trigger).length;
+      const noTrigger = evalItems.filter(i => !i.should_trigger).length;
+      document.getElementById('summary').textContent =
+        `${evalItems.length} queries total: ${trigger} should trigger, ${noTrigger} should not trigger`;
+    }
+
+    function exportEvalSet() {
+      const valid = evalItems.filter(i => i.query.trim() !== '');
+      const data = valid.map(i => ({ query: i.query.trim(), should_trigger: i.should_trigger }));
+      const blob = new Blob([JSON.stringify(data, null, 2)], { type: 'application/json' });
+      const url = URL.createObjectURL(blob);
+      const a = document.createElement('a');
+      a.href = url;
+      a.download = 'eval_set.json';
+      document.body.appendChild(a);
+      a.click();
+      document.body.removeChild(a);
+      URL.revokeObjectURL(url);
+    }
+
+    render();
+  </script>
+</body>
+</html>

package/dist/skills/skill-finder/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: skill-finder
+description: Discover and suggest installable skills from the neko skill market. Use when the user asks "how do I do X", "is there a skill for X", "find a skill that can...", or expresses interest in extending the agent's capabilities — especially for specialized domains like documents, frontend, testing, or workflow automation.
+---
+
+# Skill Finder
+
+Help the user discover skills from the neko skill market. You search and present; the user installs.
+
+## When to use
+
+- The user asks "how do I do X" where X might be a common task with an existing skill
+- The user says "find a skill for X", "is there a skill for X", "can you do X" where X is a specialized capability
+- The user expresses interest in extending your capabilities or mentions a recurring workflow
+
+## How to search
+
+The market has a read-only JSON API that needs no credentials. Search it with bash:
+
+```bash
+curl -s "<market-url>/api/skills?q=<query>"
+```
+
+Each result has `name`, `description`, `category`, `metadata.source`, `version`, and `size_bytes`. Try a couple of keyword variants if the first query misses (e.g. "pdf", then "document").
+
+The default market URL is `https://skill.kirineko.tech`. If the user has configured a different one (`skills.marketUrl` in `neko.config.json`), use that instead.
+
+## Presenting candidates
+
+Present matches compactly: name, one-line description, category and source. Example:
+
+```
+I found a couple of skills that might help:
+
+- **pdf** (documents · Anthropic) — read, extract, merge, and manipulate PDF files
+- **read** (research · Tw93/Waza) — fetch URLs and PDFs into clean Markdown
+
+To install one, open the skill market: the market page in the Web UI, or `/skills` in the TUI.
+```
+
+## The install boundary
+
+Do not download or install skills yourself — no fetching the zip, no writing into skills directories. Installation belongs to the user through the market interface, which shows install status, previews, and overwrite confirmations. Your job ends at a good recommendation plus pointing at the entry point.
+
+If neither market interface is available in this environment, say so and give the user the exact skill name to install later.
+
+## When nothing matches
+
+1. Say that no existing skill matched.
+2. Offer to help with the task directly with your general capabilities.
+3. If it looks like a recurring need, suggest creating one — the `skill-creator` skill walks through that.

package/package.json

@@ -24,7 +24,7 @@
 	},
 	"packageManager": "bun@1.4.2",
 	"trustedDependencies": [],
-	"version": "0.2.3",
+	"version": "0.2.4",
 	"description": "A local AI coding assistant with terminal and web interfaces, powered by Pi and Bun.",
 	"license": "MIT",
 	"repository": {