engine: natural "when to use" phrasing for generated skills

The skill description forced the OpenAPI summary (a Title) into a verb clause:
"Use when the user wants to stripe get charges" — reads wrong. Derive the intent
from the HTTP method + resource instead: intentOf() picks the first meaningful
path segment (skipping params and version/api prefixes, so /v1/charges/search ->
"charges" not "v1" or "search") and phrases by verb — "list or search charges",
"create charges", "retrieve a specific charges record".

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: kinlane

src/engine.ts

@@ -195,12 +195,31 @@ export function draftPrompt(op: Operation, tool: ToolDesign): PromptDesign {
   };
 }
 
+// A natural "when to use" phrase from the HTTP verb + resource. Lowercasing an OpenAPI summary
+// (which is a Title, e.g. "Stripe Get Charges") into "…wants to stripe get charges" reads wrong;
+// the method+path intent ("list or search charges") is cleaner and always sensible.
+function intentOf(op: Operation): string {
+  // First meaningful path segment = the primary collection. Skip params, and skip version/api
+  // prefixes (/v1/charges -> "charges", not "v1"); the LAST segment can be a sub-action
+  // (/charges/search -> "search"), so the first real one is the reliable resource name.
+  const segs = op.path.split('/').filter((s) => s && !s.startsWith('{') && !/^(v\d+|\d+\.\d+|api|rest|public|internal)$/i.test(s));
+  const resource = (segs[0] || 'the resource').replace(/[-_]/g, ' ');
+  const onItem = /\}$/.test(op.path);
+  switch (op.method) {
+    case 'get': case 'head': return onItem ? `retrieve a specific ${resource} record` : `list or search ${resource}`;
+    case 'post': return `create ${resource}`;
+    case 'put': case 'patch': return `update ${resource}`;
+    case 'delete': return `delete ${resource}`;
+    default: return `work with ${resource}`;
+  }
+}
+
 export function draftSkill(doc: any, op: Operation, tool: ToolDesign): SkillDesign {
   const title = doc.info?.title || 'the API';
   const name = kebab(tool.name).slice(0, 64);
   return {
     name,
-    description: `${(op.summary || tool.description).replace(/\.$/, '')} via the ${title}. Use when the user wants to ${(op.summary || tool.name).toLowerCase().replace(/\.$/, '')}.`,
+    description: `${(op.summary || tool.description).replace(/\.$/, '')} via the ${title}. Use when the user wants to ${intentOf(op)}.`,
     metadata: { author: '', version: '1.0' },
     body: [
       `# ${op.summary || tool.title || tool.name}`,