summer-engine 1.5.0 → 2.0.0

package/dist/lib/remote-templates.js

@@ -0,0 +1,86 @@
+/**
+ * Discover and clone open-source Summer Engine project templates hosted at
+ * github.com/SummerEngine/template-*.
+ *
+ * The GitHub API call is cached for one hour in memory to avoid rate-limit
+ * pain when an agent calls back-to-back.
+ */
+import { execSync } from "node:child_process";
+import { existsSync } from "node:fs";
+const ORG = "SummerEngine";
+const TEMPLATE_PREFIX = "template-";
+const CACHE_TTL_MS = 60 * 60 * 1000;
+let cache = null;
+export async function fetchRemoteTemplates(opts = {}) {
+    if (!opts.force && cache && Date.now() - cache.fetchedAt < CACHE_TTL_MS) {
+        return cache.templates;
+    }
+    const url = `https://api.github.com/orgs/${ORG}/repos?per_page=100&type=public`;
+    const headers = {
+        Accept: "application/vnd.github+json",
+        "User-Agent": "summer-engine-cli",
+    };
+    if (process.env.GITHUB_TOKEN)
+        headers.Authorization = `Bearer ${process.env.GITHUB_TOKEN}`;
+    const res = await fetch(url, { headers });
+    if (!res.ok) {
+        throw new Error(`GitHub API ${res.status}: ${res.statusText}. ${res.status === 403 ? "Rate-limited; set GITHUB_TOKEN to raise the cap." : ""}`);
+    }
+    const repos = (await res.json());
+    const templates = repos
+        .filter((r) => r.name.startsWith(TEMPLATE_PREFIX) && !r.archived && !r.fork)
+        .map((r) => ({
+        slug: r.name.slice(TEMPLATE_PREFIX.length),
+        repo: r.name,
+        description: r.description ?? "",
+        branch: r.default_branch,
+        url: r.html_url,
+        cloneUrl: r.clone_url,
+        stars: r.stargazers_count,
+        updatedAt: r.updated_at,
+    }))
+        .sort((a, b) => b.stars - a.stars || a.slug.localeCompare(b.slug));
+    cache = { templates, fetchedAt: Date.now() };
+    return templates;
+}
+export function cloneTemplate(template, opts) {
+    if (existsSync(opts.targetDir)) {
+        throw new Error(`Directory already exists: ${opts.targetDir}`);
+    }
+    // Shallow clone for speed.
+    try {
+        execSync(`git clone --depth 1 --branch ${template.branch} ${template.cloneUrl} "${opts.targetDir}"`, {
+            stdio: ["ignore", "pipe", "pipe"],
+        });
+    }
+    catch (err) {
+        throw new Error(`git clone failed for ${template.repo}. Is git installed? ${err.message}`);
+    }
+    if (opts.detach !== false) {
+        // Default to detached: the user wants their own history.
+        const gitDir = `${opts.targetDir}/.git`;
+        if (existsSync(gitDir)) {
+            try {
+                execSync(process.platform === "win32" ? `rmdir /s /q "${gitDir}"` : `rm -rf "${gitDir}"`, {
+                    stdio: "ignore",
+                });
+            }
+            catch {
+                // best effort — user can clean up manually if it fails
+            }
+        }
+    }
+}
+/** Quick match: exact slug, then prefix, then substring. Returns null if ambiguous or none. */
+export function matchTemplate(query, templates) {
+    const exact = templates.find((t) => t.slug === query || t.repo === query);
+    if (exact)
+        return exact;
+    const prefix = templates.filter((t) => t.slug.startsWith(query));
+    if (prefix.length === 1)
+        return prefix[0];
+    const substring = templates.filter((t) => t.slug.includes(query));
+    if (substring.length === 1)
+        return substring[0];
+    return null;
+}

package/dist/lib/skills-registry.d.ts

@@ -85,7 +85,7 @@ export declare const SKILL_REGISTRY: readonly [{
     readonly category: "scene-and-project";
     readonly public: true;
     readonly clients: readonly ["summer", "codex", "claude-code", "cursor", "windsurf"];
-    readonly recommended: false;
+    readonly recommended: true;
     readonly requiresMcpTools: readonly ["summer_get_agent_playbook", "summer_get_project_context", "summer_create_scene", "summer_open_scene", "summer_save_scene", "summer_add_node", "summer_set_prop", "summer_set_resource_property", "summer_instantiate_scene", "summer_play", "summer_stop", "summer_get_diagnostics"];
     readonly testScenario: "Build one narrow playable prototype from requirements through scene setup, host-edited scripts, and diagnostics.";
 }, {
@@ -96,6 +96,22 @@ export declare const SKILL_REGISTRY: readonly [{
     readonly recommended: true;
     readonly requiresMcpTools: readonly ["summer_get_project_context", "summer_get_scene_tree"];
     readonly testScenario: "Walk a fresh user from \"I want to make a game but I don't know what\" to a 1-page brief saved at .summer/GameSoul.md.";
+}, {
+    readonly name: "new-project";
+    readonly category: "scene-and-project";
+    readonly public: true;
+    readonly clients: readonly ["summer", "codex", "claude-code", "cursor", "windsurf"];
+    readonly recommended: true;
+    readonly requiresMcpTools: readonly ["summer_get_project_context"];
+    readonly testScenario: "User says \"start a blank project\" — skill asks for the name, picks empty vs 3d-basic, runs summer create, opens the engine, and stops to ask what to build.";
+}, {
+    readonly name: "browse-templates";
+    readonly category: "scene-and-project";
+    readonly public: true;
+    readonly clients: readonly ["summer", "codex", "claude-code", "cursor", "windsurf"];
+    readonly recommended: true;
+    readonly requiresMcpTools: readonly ["summer_get_project_context"];
+    readonly testScenario: "User says \"what templates exist?\" — skill runs summer list templates, presents 3-5 curated picks, asks the project name, and runs summer create <slug> <name>.";
 }, {
     readonly name: "design-mechanic";
     readonly category: "gameplay-mechanics";

package/dist/lib/skills-registry.js

@@ -158,7 +158,7 @@ export const SKILL_REGISTRY = [
         category: "scene-and-project",
         public: true,
         clients: ALL_CLIENTS,
-        recommended: false,
+        recommended: true,
         requiresMcpTools: [
             "summer_get_agent_playbook",
             "summer_get_project_context",
@@ -187,6 +187,28 @@ export const SKILL_REGISTRY = [
         ],
         testScenario: "Walk a fresh user from \"I want to make a game but I don't know what\" to a 1-page brief saved at .summer/GameSoul.md.",
     },
+    {
+        name: "new-project",
+        category: "scene-and-project",
+        public: true,
+        clients: ALL_CLIENTS,
+        recommended: true,
+        requiresMcpTools: [
+            "summer_get_project_context",
+        ],
+        testScenario: "User says \"start a blank project\" — skill asks for the name, picks empty vs 3d-basic, runs summer create, opens the engine, and stops to ask what to build.",
+    },
+    {
+        name: "browse-templates",
+        category: "scene-and-project",
+        public: true,
+        clients: ALL_CLIENTS,
+        recommended: true,
+        requiresMcpTools: [
+            "summer_get_project_context",
+        ],
+        testScenario: "User says \"what templates exist?\" — skill runs summer list templates, presents 3-5 curated picks, asks the project name, and runs summer create <slug> <name>.",
+    },
     {
         name: "design-mechanic",
         category: "gameplay-mechanics",

package/dist/lib/telemetry.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Ping the telemetry endpoint once per MCP server lifetime.
+ *
+ * - No await: returns synchronously after kicking off the request.
+ * - No throw: every error is swallowed.
+ * - No retry: a single best-effort attempt.
+ * - Skips entirely if no auth token is on disk (anonymous users still work).
+ */
+export declare function recordMcpSession(): void;
+/**
+ * Reset the once-per-session guard. Test-only.
+ */
+export declare function _resetTelemetryPingedForTests(): void;

package/dist/lib/telemetry.js

@@ -0,0 +1,63 @@
+/**
+ * Pure-telemetry beacon for MCP usage. Fire-and-forget, never blocks, never throws.
+ * One ping per MCP server lifetime — counts daily-active users, not per-tool calls.
+ *
+ * The endpoint /api/mcp/log-local-call always returns allowed:true and never gates.
+ * No quota. The user account is the only thing being attributed; the response is
+ * ignored entirely on the CLI side.
+ */
+import { getAuthToken } from "./auth.js";
+const TELEMETRY_URL = process.env.SUMMER_GATEWAY_URL?.replace(/\/+$/, "") ?? "https://www.summerengine.com";
+const TELEMETRY_PATH = "/api/mcp/log-local-call";
+const TIMEOUT_MS = 5000;
+let pinged = false;
+/**
+ * Ping the telemetry endpoint once per MCP server lifetime.
+ *
+ * - No await: returns synchronously after kicking off the request.
+ * - No throw: every error is swallowed.
+ * - No retry: a single best-effort attempt.
+ * - Skips entirely if no auth token is on disk (anonymous users still work).
+ */
+export function recordMcpSession() {
+    if (pinged)
+        return;
+    pinged = true;
+    // Wrap the entire async pipeline in a void-discarded promise so the caller
+    // never accidentally awaits us.
+    void (async () => {
+        try {
+            const token = await getAuthToken();
+            if (!token)
+                return; // unauthenticated MCP usage is allowed; we just can't attribute it
+            const ctrl = new AbortController();
+            const timer = setTimeout(() => ctrl.abort(), TIMEOUT_MS);
+            try {
+                await fetch(`${TELEMETRY_URL}${TELEMETRY_PATH}`, {
+                    method: "POST",
+                    signal: ctrl.signal,
+                    headers: {
+                        Authorization: `Bearer ${token}`,
+                        "Content-Type": "application/json",
+                    },
+                    body: JSON.stringify({
+                        client: "summer-cli",
+                        event: "mcp_session_start",
+                    }),
+                });
+            }
+            finally {
+                clearTimeout(timer);
+            }
+        }
+        catch {
+            // never throws — telemetry is best-effort
+        }
+    })();
+}
+/**
+ * Reset the once-per-session guard. Test-only.
+ */
+export function _resetTelemetryPingedForTests() {
+    pinged = false;
+}

package/dist/lib/with-engine.d.ts

@@ -0,0 +1,14 @@
+import { EngineApiClient } from "./api-client.js";
+export declare function extractOpError(result: unknown): string | null;
+export declare function buildActionHint(message: string): string | null;
+export declare function checkQuota(): Promise<{
+    allowed: boolean;
+    message?: string;
+}>;
+export declare function getClient(): Promise<EngineApiClient>;
+export declare function resetClient(): void;
+/**
+ * Connect to the engine, check quota, and run the given function.
+ * Throws on errors (quota, connection, op errors).
+ */
+export declare function withEngineClient<T>(fn: (client: EngineApiClient) => Promise<T>): Promise<T>;

package/dist/lib/with-engine.js

@@ -0,0 +1,109 @@
+import { EngineApiClient } from "./api-client.js";
+import { getAuthToken } from "./auth.js";
+const GATEWAY_URL = process.env.SUMMER_GATEWAY_URL || "https://www.summerengine.com";
+export function extractOpError(result) {
+    if (!result || typeof result !== "object")
+        return null;
+    const op = result;
+    if (op.status === "error" && op.error)
+        return op.error;
+    const firstFailed = op.results?.find((r) => r.ok === false && r.error);
+    return firstFailed?.error ?? null;
+}
+export function buildActionHint(message) {
+    const normalized = message.toLowerCase();
+    if (normalized.includes("no scene open") || normalized.includes("no edited scene")) {
+        return "No scene is currently open. Run `summer project context` first, then `summer project open-main` (or `summer scene open` with a known .tscn path).";
+    }
+    if (normalized.includes("failed to open scene")) {
+        return "Scene path could not be opened. Run `summer project context` to get mainScene, then open that exact path. Avoid guessing scene filenames.";
+    }
+    if (normalized.includes("writefile cannot edit .tscn/.scn")) {
+        return "Cannot write .tscn/.scn directly. Use summer scene commands for scene-tree operations, and file-edit tools for .gd scripts.";
+    }
+    return null;
+}
+export async function checkQuota() {
+    const token = await getAuthToken();
+    if (!token) {
+        return {
+            allowed: false,
+            message: "Not signed in. Run: summer login\nOr open: https://www.summerengine.com/login\nEngine tools require a Summer Engine account (free to create).",
+        };
+    }
+    try {
+        const res = await fetch(`${GATEWAY_URL}/api/mcp/log-local-call`, {
+            method: "POST",
+            headers: {
+                Authorization: `Bearer ${token}`,
+                "Content-Type": "application/json",
+            },
+            body: JSON.stringify({}),
+            signal: AbortSignal.timeout(10000),
+        });
+        const data = (await res.json().catch(() => ({})));
+        if ([401, 402, 403, 429].includes(res.status)) {
+            return {
+                allowed: false,
+                message: data.message || "Quota check failed. Try again.",
+            };
+        }
+        // Soft-fail on service/gateway issues so local tools keep working.
+        if (!res.ok) {
+            return { allowed: true };
+        }
+        if (data.allowed === false) {
+            return {
+                allowed: false,
+                message: data.message || "Call limit reached. Upgrade at https://summerengine.com/pricing",
+            };
+        }
+        return { allowed: true };
+    }
+    catch {
+        // Network/transient errors should not brick local usage.
+        return { allowed: true };
+    }
+}
+let cachedClient = null;
+export function getClient() {
+    if (cachedClient)
+        return Promise.resolve(cachedClient);
+    return EngineApiClient.connect().then((c) => {
+        cachedClient = c;
+        return c;
+    });
+}
+export function resetClient() {
+    cachedClient = null;
+}
+/**
+ * Connect to the engine, check quota, and run the given function.
+ * Throws on errors (quota, connection, op errors).
+ */
+export async function withEngineClient(fn) {
+    const quota = await checkQuota();
+    if (!quota.allowed) {
+        throw new Error(quota.message || "Quota exceeded");
+    }
+    try {
+        const client = await getClient();
+        const result = await fn(client);
+        const opError = extractOpError(result);
+        if (opError) {
+            const hint = buildActionHint(opError);
+            throw new Error(hint ? `${opError}\n\nHint: ${hint}` : opError);
+        }
+        return result;
+    }
+    catch (err) {
+        // Reset client on connection errors so next call retries
+        if (err instanceof Error &&
+            (err.message.includes("not running") ||
+                err.message.includes("not responding") ||
+                err.message.includes("ECONNREFUSED"))) {
+            resetClient();
+        }
+        throw err;
+    }
+}

package/dist/mcp/tools/asset-tools.js

@@ -65,14 +65,6 @@ async function searchAssetsApi(params) {
     });
     const data = (await res.json());
     if (!res.ok) {
-        if (res.status === 402) {
-            return {
-                error: "upgrade_required",
-                message: (data.message || "Asset search requires a Pro subscription.") +
-                    "\nUpgrade at: https://www.summerengine.com/pricing\nFree tier includes all other MCP tools (scene editing, debugging, etc).",
-                plan: data.plan,
-            };
-        }
         if (res.status === 401) {
             return {
                 error: "unauthorized",
@@ -80,6 +72,13 @@ async function searchAssetsApi(params) {
                     " The user needs to re-authenticate:\n  npx summer-engine login --force",
             };
         }
+        if (res.status === 429) {
+            return {
+                error: "rate_limited",
+                message: (data.message || "Asset search rate limit hit. Wait a moment and try again.") +
+                    " The public library is free, but rate-limited per user to prevent bulk scraping.",
+            };
+        }
         return {
             error: data.error || "Search failed",
             message: data.message || "Asset search failed",
@@ -88,17 +87,17 @@ async function searchAssetsApi(params) {
     return data;
 }
 export function registerAssetTools(server) {
-    server.tool("summer_search_assets", `Search for game assets in the Summer Engine ecosystem.
+    server.tool("summer_search_assets", `Search for game assets in the Summer Engine ecosystem. **Free for all users** with rate limits.
 
 Sources:
-  - "library" (default) — Public asset library (25k+ community assets). Requires Pro plan.
-  - "my_assets" — Your own generated/uploaded assets. Free for all users. Query is optional.
+  - "library" (default) — Public asset library (25k+ community assets). Free.
+  - "my_assets" — Your own generated/uploaded assets. Free. Query is optional.
   - "all" — Search both library and your assets.
 
 Uses hybrid search: keywords + semantic similarity. Finds assets by name AND by meaning.
 Returns asset names, types, preview URLs, and import-ready file URLs.
 
-Requires authentication: run 'npx summer-engine login' first.`, {
+Requires authentication (so we can attribute usage and apply per-user rate limits): run 'npx summer-engine login' first.`, {
         query: z.string().describe("Natural language search, e.g. 'low-poly tree', 'sci-fi weapon'. For my_assets, can be empty to list recent."),
         assetType: z.enum(["2d_image", "animation", "3d_model", "audio", "music", "all"]).default("all").describe("Filter by asset type"),
         limit: z.number().default(10).describe("Max results (1-20)"),
@@ -110,7 +109,7 @@ Requires authentication: run 'npx summer-engine login' first.`, {
                 content: [
                     {
                         type: "text",
-                        text: JSON.stringify({ error: result.error, message: result.message, plan: result.plan }, null, 2),
+                        text: JSON.stringify({ error: result.error, message: result.message }, null, 2),
                     },
                 ],
                 isError: true,

package/dist/mcp/tools/debug-tools.js

@@ -1,5 +1,6 @@
 import { z } from "zod";
 import { withEngine } from "./with-engine.js";
+import { shapeEngineLogResponse } from "../../lib/log-filters.js";
 export function registerDebugTools(server) {
     server.tool("summer_get_diagnostics", `Quick overview of all errors and warnings from both the editor console and the runtime debugger. Returns error counts and a guidance message.
 
@@ -10,27 +11,49 @@ Typical workflow after making changes:
 2. If errors: summer_get_console or summer_get_debugger_errors for details
 3. Fix the issues
 4. summer_get_diagnostics again to verify`, {}, async () => withEngine(async (client) => client.getDiagnostics()));
-    server.tool("summer_get_console", "Read recent messages from the editor's Output panel. Shows print statements, warnings, and errors from both the editor and scripts. Use after summer_get_diagnostics indicates console issues.", {
-        max_lines: z.number().optional().default(100).describe("Max lines to return (default 100)"),
+    server.tool("summer_get_console", `Read recent messages from the editor's Output panel.
+
+Output is post-processed for token economy: consecutive identical messages collapse into one entry with a "(×N)" count suffix, and the response carries a "_filter" summary so you can see what was hidden. Use errors_only=true (default) to drop info/std noise; use raw=true to bypass all shaping.
+
+Use after summer_get_diagnostics indicates console issues.`, {
+        max_lines: z.number().optional().default(100).describe("Max lines to return after dedupe (default 100)"),
         filter: z.string().optional().describe("Only return lines containing this string"),
-        type: z.enum(["error", "warning", "std", "editor"]).optional().describe("Filter by message type"),
-    }, async ({ max_lines, filter, type }) => withEngine(async (client) => {
+        type: z.enum(["error", "warning", "std", "editor"]).optional().describe("Filter by message type at the engine level"),
+        errors_only: z.boolean().optional().default(true).describe("Drop info/std noise, keep errors and warnings (default true)"),
+        strict_errors: z.boolean().optional().default(false).describe("Drop warnings too — return errors only"),
+        raw: z.boolean().optional().default(false).describe("Bypass dedupe and level filtering — return engine output verbatim"),
+    }, async ({ max_lines, filter, type, errors_only, strict_errors, raw }) => withEngine(async (client) => {
         const op = { op: "GetConsoleOutput", max_lines };
         if (filter)
             op.filter = filter;
         if (type)
             op.type = type;
-        return client.executeOps([op]);
+        const engineResult = await client.executeOps([op]);
+        if (raw)
+            return engineResult;
+        const { result } = shapeEngineLogResponse(engineResult, {
+            errorsOnly: errors_only,
+            errorsOnlyStrict: strict_errors,
+            maxEntries: max_lines,
+        });
+        return result;
     }));
     server.tool("summer_clear_console", "Clear the editor's Output panel. Useful before running the game to get a clean slate for error checking.", {}, async () => withEngine(async (client) => client.executeOps([{ op: "ClearConsoleOutput" }])));
-    server.tool("summer_get_debugger_errors", "Read runtime errors and warnings from the debugger. These are errors that occur while the game is running (null references, missing nodes, physics errors). Different from console output — these come from the debugger, not print statements.", {
-        max_errors: z.number().optional().default(50).describe("Max errors to return"),
+    server.tool("summer_get_debugger_errors", `Read runtime errors and warnings from the debugger. These are errors that occur while the game is running (null references, missing nodes, physics errors). Different from console output — these come from the debugger, not print statements.
+
+Output is deduped: identical errors firing every frame collapse into one entry with a "(×N)" count suffix. A "_filter" summary tells you exactly what was collapsed or truncated. Use raw=true to bypass shaping when you really need every entry.`, {
+        max_errors: z.number().optional().default(50).describe("Max errors to return after dedupe"),
         include_stack: z.boolean().optional().describe("Include stack traces for each error"),
-    }, async ({ max_errors, include_stack }) => withEngine(async (client) => {
+        raw: z.boolean().optional().default(false).describe("Bypass dedupe — return engine output verbatim"),
+    }, async ({ max_errors, include_stack, raw }) => withEngine(async (client) => {
         const op = { op: "GetDebuggerErrors", max_errors };
         if (include_stack !== undefined)
             op.include_stack = include_stack;
-        return client.executeOps([op]);
+        const engineResult = await client.executeOps([op]);
+        if (raw)
+            return engineResult;
+        const { result } = shapeEngineLogResponse(engineResult, { maxEntries: max_errors });
+        return result;
     }));
     server.tool("summer_play", `Start running the game in the engine. The game runs inside Summer Engine's viewport.
 

package/dist/mcp/tools/with-engine.js

@@ -1,4 +1,5 @@
 import { getClient, resetClient } from "../server.js";
+import { recordMcpSession } from "../../lib/telemetry.js";
 function extractOpError(result) {
     if (!result || typeof result !== "object")
         return null;
@@ -24,6 +25,9 @@ function buildActionHint(message) {
     return null;
 }
 export async function withEngine(fn) {
+    // Best-effort, fire-and-forget: count this MCP session as DAU for attribution.
+    // No await, no throw, no quota gating.
+    recordMcpSession();
     try {
         const client = await getClient();
         const result = await fn(client);

package/gemini-extension.json

@@ -1,7 +1,7 @@
 {
   "name": "summer",
-  "version": "1.4.0",
-  "description": "AI game-dev studio for Godot: MCP bridge to the local Summer Engine plus a context primer that teaches Gemini the 19 Summer skill names. Use with the npm CLI for skill files on disk.",
+  "version": "2.0.0",
+  "description": "Superpowers for AI game dev. MCP bridge to the local Summer Engine plus a context primer that teaches Gemini the 22 Summer skills. Use with the npm CLI for skill files on disk.",
   "contextFileName": "GEMINI.md",
   "mcpServers": {
     "summer-engine": {

package/marketplace.json

@@ -7,8 +7,8 @@
     {
       "name": "summer",
       "source": "./",
-      "version": "1.4.0",
-      "description": "AI game-dev studio: 19 skills under summer: namespace, MCP bridge, session-start + pre-commit hooks.",
+      "version": "2.0.0",
+      "description": "Superpowers for AI game dev. 24 auto-trigger skills under summer: namespace, MCP bridge to the local Summer Engine, session-start + pre-commit hooks.",
       "author": { "name": "Summer Engine", "email": "founders@summerengine.com" },
       "category": "game-development",
       "tags": ["game-dev", "godot", "ai-game-engine"],

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "summer-engine",
-  "version": "1.5.0",
-  "description": "CLI and MCP tools for Summer Engine — the AI-native game engine",
+  "version": "2.0.0",
+  "description": "Summer — superpowers for AI game dev. CLI, skills, and MCP tools for Summer Engine.",
   "keywords": [
     "game-engine",
     "godot",
@@ -14,7 +14,7 @@
   "homepage": "https://summerengine.com",
   "repository": {
     "type": "git",
-    "url": "https://github.com/SummerEngine/summer-engine-cli"
+    "url": "https://github.com/SummerEngine/summer"
   },
   "license": "MIT",
   "author": "Summer Engine <founders@summerengine.com>",

package/skills/README.md

@@ -2,7 +2,7 @@
 
 The canonical agent-readable game-dev knowledge source for Claude Code, Cursor, Codex, and Windsurf.
 
-When an agent is asked to make a game in Godot, this is what it reads to learn how.
+When an agent is asked to make a game in Summer Engine, this is what it reads to learn how.
 
 ## Layout
 

package/skills/_meta/skill-create/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: skill-create
-description: Bootstrap a new Summer skill with the canonical folder structure, frontmatter, and stub sections. Use when adding a new skill to the library. Trigger on "create skill", "add skill", "new skill".
+description: Use when a contributor wants to add a new skill to the Summer library — bootstraps the canonical folder structure, frontmatter, and stub sections. Trigger on "create skill", "add skill", "new skill", "scaffold a skill".
 license: MIT
 compatibility: [Cursor, Claude Code, Windsurf, Codex]
 category: _meta

package/skills/_meta/skill-improve/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: skill-improve
-description: Iterate on an existing Summer skill using a parallel-eval harness — run the skill against a behavioral spec with and without proposed changes, compare outputs, ship the version that wins. Use to upgrade a skill that's underperforming. Trigger on "improve skill", "iterate on skill", "make this skill better".
+description: Use when a contributor wants to upgrade a Summer skill that is underperforming or to fix a regression — runs the skill against a behavioral spec with and without proposed changes via parallel-eval harness and ships the version that wins. Trigger on "improve skill", "iterate on skill", "make this skill better".
 license: MIT
 compatibility: [Cursor, Claude Code, Windsurf, Codex]
 category: _meta

package/skills/_meta/skill-test/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: skill-test
-description: Validate a Summer skill against static structural rules and per-skill behavioral specs. Use to lint a skill before commit, audit the whole library, or check a behavioral spec assertion. Trigger on "skill test", "lint skill", "validate skill".
+description: Use when a contributor wants to lint a Summer skill before commit, audit the whole library, or check a behavioral spec assertion — validates against static structural rules and per-skill behavioral specs. Trigger on "skill test", "lint skill", "validate skill".
 license: MIT
 compatibility: [Cursor, Claude Code, Windsurf, Codex]
 category: _meta