maestro-agent-sdk 0.1.0

package/dist/skills/curator.js

@@ -0,0 +1,162 @@
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { loadUsage } from "../skills/usage.js";
+import { DATA_DIR } from "../platform/config.js";
+import { logger } from "../platform/logger.js";
+const SCHEMA_VERSION = 1;
+/** How many days since `lastTouchedTs` before a previously-viewed skill is
+ *  marked `stale`. Default 30. */
+export const STALE_AFTER_DAYS = 30;
+/** How many days since `firstSeenTs` (and never viewed) before an unused
+ *  agent-created skill is archived. Default 60. Bundled skills are exempt. */
+export const ARCHIVE_AFTER_DAYS = 60;
+const DAY_MS = 24 * 60 * 60 * 1000;
+/** Default state file path. Overridable via `MAESTRO_SKILL_STATE_PATH`. */
+export function defaultStatePath() {
+    return (process.env.MAESTRO_SKILL_STATE_PATH ??
+        join(DATA_DIR, "agents", "maestro", "skills", "state.json"));
+}
+function emptyFile() {
+    return { schemaVersion: SCHEMA_VERSION, states: {} };
+}
+// Write-through cache: curateSkills is the sole writer, runs once per turn
+// at most, and produces an explicit `next` object that we install into the
+// cache after writeAtomic. Eliminates the per-turn state.json readFileSync.
+const stateCacheByPath = new Map();
+/** Read the state file synchronously, or return an empty one on
+ *  ENOENT / schema mismatch / parse error. Cached in-process. */
+export function loadState(path = defaultStatePath()) {
+    const cached = stateCacheByPath.get(path);
+    if (cached)
+        return cached;
+    const fresh = readStateFromDisk(path);
+    stateCacheByPath.set(path, fresh);
+    return fresh;
+}
+function readStateFromDisk(path) {
+    if (!existsSync(path))
+        return emptyFile();
+    try {
+        const raw = readFileSync(path, "utf8");
+        const parsed = JSON.parse(raw);
+        if (parsed.schemaVersion !== SCHEMA_VERSION || typeof parsed.states !== "object") {
+            logger.warn({ path }, "skill curator: state schema mismatch, resetting");
+            return emptyFile();
+        }
+        return parsed;
+    }
+    catch (err) {
+        logger.warn({ err, path }, "skill curator: state read/parse failed, resetting");
+        return emptyFile();
+    }
+}
+/** Atomic tmp + rename write. */
+function writeAtomic(path, contents) {
+    mkdirSync(dirname(path), { recursive: true });
+    const tmp = `${path}.tmp-${process.pid}-${Date.now()}`;
+    writeFileSync(tmp, JSON.stringify(contents, null, 2));
+    renameSync(tmp, path);
+}
+/** A skill is `bundled` if its file lives under the upstream snapshot
+ *  directory (defaults to `~/__KEEP_MAESTRO_AGENT__/skills`, overridable via the
+ *  same `MAESTRO_SKILL_DIR` env that loader.ts uses). Anything outside
+ *  that tree is treated as agent-created. */
+function isBundled(skill) {
+    const snapshotRoot = process.env.MAESTRO_SKILL_DIR ?? `${process.env.HOME ?? ""}/__KEEP_MAESTRO_AGENT__/skills`;
+    return skill.skillDir.startsWith(snapshotRoot);
+}
+/**
+ * Decide the lifecycle for one skill given its counters + provenance + a
+ * reference `now`. Pure function — no I/O. Drives both the in-memory
+ * filter and the state-file persistence.
+ *
+ * Rules:
+ *   - bundled + never viewed     → "active"  (operator shipped it for a reason)
+ *   - viewCount > 0 + recent     → "active"
+ *   - viewCount > 0 + N days old → "stale"
+ *   - agent-created + never viewed + M days old → "archived"
+ *   - default (just-loaded, no record yet)      → "active"
+ */
+export function decideLifecycle(counters, bundled, now = new Date()) {
+    if (!counters)
+        return "active";
+    const lastTouched = Date.parse(counters.lastTouchedTs);
+    const firstSeen = Date.parse(counters.firstSeenTs);
+    const nowMs = now.getTime();
+    if (counters.viewCount > 0) {
+        const idleDays = (nowMs - lastTouched) / DAY_MS;
+        return idleDays >= STALE_AFTER_DAYS ? "stale" : "active";
+    }
+    if (bundled)
+        return "active";
+    const ageDays = (nowMs - firstSeen) / DAY_MS;
+    return ageDays >= ARCHIVE_AFTER_DAYS ? "archived" : "active";
+}
+/**
+ * Walk the loaded catalog, compute each skill's lifecycle from the usage
+ * sidecar, persist the assignments, and return only the `active` + `stale`
+ * entries (callers feed these into the system prompt index builder).
+ *
+ * Archived skills are kept on disk but dropped from the returned list so
+ * the per-turn system prompt stays slim. `skill_view(name=...)` for an
+ * archived skill still works — the model just won't be prompted with it.
+ *
+ * The state-file update is idempotent: skills that didn't change lifecycle
+ * since the last call get a no-op write (still atomic).
+ */
+export function curateSkills(skills, opts = {}) {
+    const usage = loadUsage(opts.usagePath).skills;
+    const prior = loadState(opts.statePath);
+    const now = opts.now ?? new Date();
+    const next = { schemaVersion: SCHEMA_VERSION, states: {} };
+    const out = [];
+    let changed = false;
+    for (const skill of skills) {
+        const bundled = isBundled(skill);
+        const counters = usage[skill.name];
+        const lifecycle = decideLifecycle(counters, bundled, now);
+        const priorState = prior.states[skill.name];
+        let changedTs;
+        if (priorState && priorState.lifecycle === lifecycle && priorState.bundled === bundled) {
+            // Stable — preserve the existing change timestamp.
+            changedTs = priorState.changedTs;
+        }
+        else {
+            changedTs = now.toISOString();
+            changed = true;
+        }
+        const state = { lifecycle, changedTs, bundled };
+        next.states[skill.name] = state;
+        if (lifecycle !== "archived")
+            out.push({ skill, state });
+    }
+    // Skills that were in `prior` but no longer in the catalog (renamed /
+    // deleted) get implicitly dropped — `next.states` only carries the
+    // current catalog. Treat that as a change so the file shrinks too.
+    for (const oldName of Object.keys(prior.states)) {
+        if (!next.states[oldName]) {
+            changed = true;
+            break;
+        }
+    }
+    if (changed && !opts.readOnly) {
+        const path = opts.statePath ?? defaultStatePath();
+        try {
+            writeAtomic(path, next);
+            // Install post-write file as the new cache reference so the next
+            // loadState call sees the freshly-persisted state without re-reading.
+            stateCacheByPath.set(path, next);
+        }
+        catch (err) {
+            logger.warn({ err, path }, "skill curator: state write failed (continuing with in-memory result)");
+        }
+    }
+    return out;
+}
+/** Test-only: drop the in-process state cache. Disk file is NOT erased —
+ *  tests that need filesystem isolation should point
+ *  `MAESTRO_SKILL_STATE_PATH` at a tmp file and remove it themselves. */
+export function __resetForTests() {
+    stateCacheByPath.clear();
+}
+//# sourceMappingURL=curator.js.map

package/dist/skills/curator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"curator.js","sourceRoot":"","sources":["../../src/skills/curator.ts"],"names":[],"mappings":"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"}

package/dist/skills/index-builder.d.ts

@@ -0,0 +1,42 @@
+import { type SkillEntry } from "../skills/loader.js";
+/**
+ * Render the `## Skills (mandatory)` block that gets appended to the Maestro
+ * system prompt.
+ *
+ * Lifted verbatim from upstream `agent/prompt_builder.py::build_skills_prompt`
+ * with two changes:
+ *   1. Maestro-CLI-specific guidance ("load the `__KEEP_MAESTRO_AGENT__` skill first
+ *      when configuring Maestro...") is dropped — Clawgram doesn't ship the
+ *      __KEEP_MAESTRO_AGENT__ skill, and the instruction would suggest a tool the
+ *      model can't reach.
+ *   2. The `skill_manage(action='patch')` invitation is dropped — Phase 4
+ *      (Curator) lands that tool; surfacing it before then would invite a
+ *      `unknown tool` error.
+ *
+ * Everything else is preserved word-for-word because it's the "MUST load /
+ * err on the side of loading" framing that actually raises the skill-call
+ * rate. Empty / softer phrasings tested by upstream regressed activation by
+ * ~30%.
+ *
+ * Why system-prompt placement (not user message): upstream caches this block
+ * (`_SKILLS_PROMPT_CACHE`) and embeds it in the system prompt so Anthropic's
+ * prefix cache covers it across every turn. Putting it in a user message
+ * would invalidate the cache the moment the user sends a follow-up. The
+ * trade-off: skill_view output is large enough that we always want it in a
+ * fresh user/tool message (cache-busting it once per skill load is fine —
+ * it's the index that needs the rolling hit).
+ *
+ * Returns the empty string when there are no skills — the caller can then
+ * skip the append entirely instead of injecting an empty header.
+ */
+export declare function buildSkillsIndex(skills: SkillEntry[]): string;
+/**
+ * Cap a skill description to the index limit (`SKILL_INDEX_DESCRIPTION_CAP`).
+ * Trims trailing whitespace + ellipsis-truncates so the index stays at one
+ * line per skill. The full description still ships with `skill_view`, so the
+ * model can read it in full once it decides to load.
+ *
+ * Empty input returns "" so the caller can suppress the trailing `: …`.
+ */
+export declare function capDescription(desc: string): string;
+//# sourceMappingURL=index-builder.d.ts.map

package/dist/skills/index-builder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index-builder.d.ts","sourceRoot":"","sources":["../../src/skills/index-builder.ts"],"names":[],"mappings":"AAAA,OAAO,EAA+B,KAAK,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAE/E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,UAAU,EAAE,GAAG,MAAM,CA6C7D;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAMnD"}

package/dist/skills/index-builder.js

@@ -0,0 +1,94 @@
+import { SKILL_INDEX_DESCRIPTION_CAP } from "../skills/loader.js";
+/**
+ * Render the `## Skills (mandatory)` block that gets appended to the Maestro
+ * system prompt.
+ *
+ * Lifted verbatim from upstream `agent/prompt_builder.py::build_skills_prompt`
+ * with two changes:
+ *   1. Maestro-CLI-specific guidance ("load the `__KEEP_MAESTRO_AGENT__` skill first
+ *      when configuring Maestro...") is dropped — Clawgram doesn't ship the
+ *      __KEEP_MAESTRO_AGENT__ skill, and the instruction would suggest a tool the
+ *      model can't reach.
+ *   2. The `skill_manage(action='patch')` invitation is dropped — Phase 4
+ *      (Curator) lands that tool; surfacing it before then would invite a
+ *      `unknown tool` error.
+ *
+ * Everything else is preserved word-for-word because it's the "MUST load /
+ * err on the side of loading" framing that actually raises the skill-call
+ * rate. Empty / softer phrasings tested by upstream regressed activation by
+ * ~30%.
+ *
+ * Why system-prompt placement (not user message): upstream caches this block
+ * (`_SKILLS_PROMPT_CACHE`) and embeds it in the system prompt so Anthropic's
+ * prefix cache covers it across every turn. Putting it in a user message
+ * would invalidate the cache the moment the user sends a follow-up. The
+ * trade-off: skill_view output is large enough that we always want it in a
+ * fresh user/tool message (cache-busting it once per skill load is fine —
+ * it's the index that needs the rolling hit).
+ *
+ * Returns the empty string when there are no skills — the caller can then
+ * skip the append entirely instead of injecting an empty header.
+ */
+export function buildSkillsIndex(skills) {
+    if (skills.length === 0)
+        return "";
+    const byCategory = new Map();
+    for (const s of skills) {
+        const bucket = byCategory.get(s.category) ?? [];
+        bucket.push(s);
+        byCategory.set(s.category, bucket);
+    }
+    const lines = [];
+    const sortedCategories = [...byCategory.keys()].sort((a, b) => a.localeCompare(b));
+    for (const category of sortedCategories) {
+        lines.push(`  ${category}:`);
+        const inCat = byCategory.get(category) ?? [];
+        inCat.sort((a, b) => a.name.localeCompare(b.name));
+        for (const s of inCat) {
+            const trimmed = capDescription(s.description);
+            if (trimmed) {
+                lines.push(`    - ${s.name}: ${trimmed}`);
+            }
+            else {
+                lines.push(`    - ${s.name}`);
+            }
+        }
+    }
+    return [
+        "## Skills (mandatory)",
+        "Before replying, scan the skills below. If a skill matches or is even partially relevant " +
+            "to your task, you MUST load it with skill_view(name) and follow its instructions. " +
+            "Err on the side of loading — it is always better to have context you don't need " +
+            "than to miss critical steps, pitfalls, or established workflows. " +
+            "Skills contain specialized knowledge — API endpoints, tool-specific commands, " +
+            "and proven workflows that outperform general-purpose approaches. Load the skill " +
+            "even if you think you could handle the task with basic tools. " +
+            "Skills also encode the user's preferred approach, conventions, and quality standards " +
+            "for tasks like code review, planning, and testing — load them even for tasks you " +
+            "already know how to do, because the skill defines how it should be done here.",
+        "",
+        "<available_skills>",
+        ...lines,
+        "</available_skills>",
+        "",
+        "Only proceed without loading a skill if genuinely none are relevant to the task.",
+    ].join("\n");
+}
+/**
+ * Cap a skill description to the index limit (`SKILL_INDEX_DESCRIPTION_CAP`).
+ * Trims trailing whitespace + ellipsis-truncates so the index stays at one
+ * line per skill. The full description still ships with `skill_view`, so the
+ * model can read it in full once it decides to load.
+ *
+ * Empty input returns "" so the caller can suppress the trailing `: …`.
+ */
+export function capDescription(desc) {
+    const collapsed = desc.replace(/\s+/g, " ").trim();
+    if (!collapsed)
+        return "";
+    if (collapsed.length <= SKILL_INDEX_DESCRIPTION_CAP)
+        return collapsed;
+    // -1 for the ellipsis.
+    return `${collapsed.slice(0, SKILL_INDEX_DESCRIPTION_CAP - 1)}…`;
+}
+//# sourceMappingURL=index-builder.js.map

package/dist/skills/index-builder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index-builder.js","sourceRoot":"","sources":["../../src/skills/index-builder.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,2BAA2B,EAAmB,MAAM,iBAAiB,CAAC;AAE/E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,MAAM,UAAU,gBAAgB,CAAC,MAAoB;IACnD,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,CAAC;IAEnC,MAAM,UAAU,GAAG,IAAI,GAAG,EAAwB,CAAC;IACnD,KAAK,MAAM,CAAC,IAAI,MAAM,EAAE,CAAC;QACvB,MAAM,MAAM,GAAG,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,QAAQ,CAAC,IAAI,EAAE,CAAC;QAChD,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QACf,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;IACrC,CAAC;IAED,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,MAAM,gBAAgB,GAAG,CAAC,GAAG,UAAU,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,CAAC;IACnF,KAAK,MAAM,QAAQ,IAAI,gBAAgB,EAAE,CAAC;QACxC,KAAK,CAAC,IAAI,CAAC,KAAK,QAAQ,GAAG,CAAC,CAAC;QAC7B,MAAM,KAAK,GAAG,UAAU,CAAC,GAAG,CAAC,QAAQ,CAAC,IAAI,EAAE,CAAC;QAC7C,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC;QACnD,KAAK,MAAM,CAAC,IAAI,KAAK,EAAE,CAAC;YACtB,MAAM,OAAO,GAAG,cAAc,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC;YAC9C,IAAI,OAAO,EAAE,CAAC;gBACZ,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,IAAI,KAAK,OAAO,EAAE,CAAC,CAAC;YAC5C,CAAC;iBAAM,CAAC;gBACN,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC;YAChC,CAAC;QACH,CAAC;IACH,CAAC;IAED,OAAO;QACL,uBAAuB;QACvB,2FAA2F;YACzF,oFAAoF;YACpF,kFAAkF;YAClF,mEAAmE;YACnE,gFAAgF;YAChF,kFAAkF;YAClF,gEAAgE;YAChE,uFAAuF;YACvF,mFAAmF;YACnF,+EAA+E;QACjF,EAAE;QACF,oBAAoB;QACpB,GAAG,KAAK;QACR,qBAAqB;QACrB,EAAE;QACF,kFAAkF;KACnF,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACf,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,cAAc,CAAC,IAAY;IACzC,MAAM,SAAS,GAAG,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC;IACnD,IAAI,CAAC,SAAS;QAAE,OAAO,EAAE,CAAC;IAC1B,IAAI,SAAS,CAAC,MAAM,IAAI,2BAA2B;QAAE,OAAO,SAAS,CAAC;IACtE,uBAAuB;IACvB,OAAO,GAAG,SAAS,CAAC,KAAK,CAAC,CAAC,EAAE,2BAA2B,GAAG,CAAC,CAAC,GAAG,CAAC;AACnE,CAAC"}

package/dist/skills/loader.d.ts

@@ -0,0 +1,107 @@
+/**
+ * SKILL.md frontmatter loader for the Maestro TS port.
+ *
+ * Mirrors the v0.13.0 `agent/skill_utils.py::parse_frontmatter` contract: a
+ * SKILL.md file starts with a `---` fenced YAML block containing at least
+ * `name` + `description`, optionally `platforms`, then a markdown body the
+ * model consumes via `skill_view`.
+ *
+ * We don't pull in a full YAML dep (gray-matter / yaml) — SKILL.md
+ * frontmatter is small and stable in shape (top-level scalars + a flat
+ * `platforms: [...]` list), and the upstream `parse_frontmatter` already
+ * ships a minimal fallback for malformed YAML. We use that same fallback
+ * shape exclusively, which keeps the surface area zero-dep and covers every
+ * real-world SKILL.md in the v0.13.0 snapshot.
+ *
+ * Directory layout follows upstream:
+ *     <root>/<category>/<skill-name>/SKILL.md
+ * The penultimate path segment is treated as `category` (used for the
+ * Skills index grouping); a SKILL.md at the root level is bucketed under
+ * "general".
+ *
+ * Filters:
+ *   - Hidden / build dirs (`.git`, `.github`, `.archive`, `.hub`) are
+ *     skipped recursively (same skip set as upstream).
+ *   - Platform mismatch (`platforms: [macos]` on Linux) drops the skill so
+ *     the index doesn't suggest tools that won't run.
+ */
+/** One loaded SKILL.md entry, ready for index rendering or full-load via skill_view. */
+export interface SkillEntry {
+    /** `name:` from frontmatter, falling back to the parent directory name. */
+    name: string;
+    /** Short summary surfaced in the index. Empty string if missing. */
+    description: string;
+    /** Directory bucket = the parent of the skill's own directory. "general" at root. */
+    category: string;
+    /** Absolute path to the directory containing SKILL.md. Used for
+     *  `${MAESTRO_SKILL_DIR}` template substitution and for resolving
+     *  relative paths inside the skill body. */
+    skillDir: string;
+    /** Absolute path to SKILL.md itself. */
+    mdPath: string;
+    /** Raw file contents (frontmatter + body). Kept so skill_view can return
+     *  the body without a second disk read. */
+    raw: string;
+    /** Parsed frontmatter as a flat string map. Multi-value entries (e.g.
+     *  `platforms: [macos, linux]`) are joined with `,`. */
+    frontmatter: Record<string, string>;
+}
+/** Description length cap for the rendered index. Upstream uses 80, but the
+ *  Clawgram routing review settled on 60 to keep the system-prompt block
+ *  tight (~6K tokens hard ceiling once the catalog has 60+ skills). The
+ *  full description survives in `frontmatter.description` for skill_view. */
+export declare const SKILL_INDEX_DESCRIPTION_CAP = 60;
+/**
+ * Walk `rootDir` recursively and return one `SkillEntry` per SKILL.md found,
+ * subject to platform compatibility + the skip-dir filter.
+ *
+ * Errors per-file (unreadable, malformed) are logged at debug and the file
+ * is dropped — one bad SKILL.md never aborts the whole scan, same stance as
+ * upstream `scan_skill_commands`.
+ */
+export declare function loadSkills(rootDir: string): SkillEntry[];
+/**
+ * Parse a `---\n...\n---\n` YAML frontmatter block into a flat string map.
+ *
+ * Supports the SKILL.md surface that matters in v0.13.0:
+ *   - `key: value` scalars (with optional surrounding quotes)
+ *   - `key: [a, b, c]` flow-list literals (joined with "," for storage)
+ *   - Nested blocks (`metadata:\n  maestro:\n    tags: [...]`) are flattened
+ *     by ignoring indented lines — we only need top-level keys for the
+ *     index + platform filter.
+ *
+ * Lines that don't fit the `key: value` shape are dropped silently. This
+ * matches the upstream "fallback" parser; the full YAML parser is omitted
+ * because every real-world SKILL.md in v0.13.0 round-trips cleanly through
+ * this subset.
+ *
+ * Returns `body` as the post-frontmatter text. If no frontmatter is
+ * present, `frontmatter` is empty and `body` is the original input.
+ */
+export declare function parseFrontmatter(content: string): {
+    frontmatter: Record<string, string>;
+    body: string;
+};
+/**
+ * Return true if the skill's `platforms:` list contains the current OS, or
+ * if the field is missing/empty (skill claims cross-platform).
+ *
+ * Match logic is upstream-compatible: any listed platform whose mapped
+ * runtime prefix is a prefix of `process.platform` counts as a hit (so
+ * `darwin` matches `darwin23.6.0`).
+ */
+export declare function matchesPlatform(frontmatter: Record<string, string>, platform?: string): boolean;
+/**
+ * Cached variant of `loadSkills` — same return shape, but memoizes on the
+ * (rootDir, rootDir-mtime) pair with a TTL backstop. Use this from any hot
+ * path (per-turn callers, per-iteration callers). Tests or operators that
+ * need a guaranteed fresh load can call `invalidateSkillsCache()` first.
+ */
+export declare function loadSkillsCached(rootDir: string): SkillEntry[];
+/** Drop the in-memory cache so the next `loadSkillsCached` call rebuilds.
+ *  Call after writing a new SKILL.md to disk, or between tests. */
+export declare function invalidateSkillsCache(): void;
+/** Find a single skill by name. Used by `skill_view`. Returns null if the
+ *  name doesn't resolve to a loaded entry. */
+export declare function findSkillByName(skills: SkillEntry[], name: string): SkillEntry | null;
+//# sourceMappingURL=loader.d.ts.map

package/dist/skills/loader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"loader.d.ts","sourceRoot":"","sources":["../../src/skills/loader.ts"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,wFAAwF;AACxF,MAAM,WAAW,UAAU;IACzB,2EAA2E;IAC3E,IAAI,EAAE,MAAM,CAAC;IACb,oEAAoE;IACpE,WAAW,EAAE,MAAM,CAAC;IACpB,qFAAqF;IACrF,QAAQ,EAAE,MAAM,CAAC;IACjB;;gDAE4C;IAC5C,QAAQ,EAAE,MAAM,CAAC;IACjB,wCAAwC;IACxC,MAAM,EAAE,MAAM,CAAC;IACf;+CAC2C;IAC3C,GAAG,EAAE,MAAM,CAAC;IACZ;4DACwD;IACxD,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACrC;AAMD;;;6EAG6E;AAC7E,eAAO,MAAM,2BAA2B,KAAK,CAAC;AAE9C;;;;;;;GAOG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,UAAU,EAAE,CAgBxD;AAoFD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG;IACjD,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACpC,IAAI,EAAE,MAAM,CAAC;CACd,CAkCA;AAaD;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAC7B,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EACnC,QAAQ,GAAE,MAAyB,GAClC,OAAO,CAaT;AA8CD;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,UAAU,EAAE,CAoB9D;AAED;mEACmE;AACnE,wBAAgB,qBAAqB,IAAI,IAAI,CAE5C;AAED;8CAC8C;AAC9C,wBAAgB,eAAe,CAAC,MAAM,EAAE,UAAU,EAAE,EAAE,IAAI,EAAE,MAAM,GAAG,UAAU,GAAG,IAAI,CAYrF"}