@sanity-labs/oclif-plugin-skills-flag 0.1.2 → 0.2.0

package/README.md

@@ -40,11 +40,37 @@ my-cli functions test --skill
 The second command uses `skills/functions-test.md`. A single-command CLI uses `skills/index.md`.
 Include `skills` in the CLI's npm `files` list if it has one.
 
+## Configuration
+
+Add `oclif-plugin-skills-flag` at the top level of the CLI's `package.json` to change the runtime
+flag names or skills directory:
+
+```json
+{
+  "oclif-plugin-skills-flag": {
+    "flag": "agents",
+    "aliases": ["agent-help"],
+    "directory": "docs/agents"
+  }
+}
+```
+
+| Option | Type | Default | Description |
+| --- | --- | --- | --- |
+| `flag` | string | `"llms"` | Main flag name, without leading dashes |
+| `aliases` | string[] | `["skill"]` | Additional names; one-character aliases use a single dash |
+| `directory` | string | `"skills"` | Skills directory relative to the CLI package root |
+
+Configuration belongs to the CLI package that owns the command. If one oclif CLI is installed as a
+plugin in another, each CLI can use different flag names and directories for its own commands.
+Include the configured directory in the CLI's npm `files` list if it has one.
+
 ## Show the flag in help
 
 An oclif plugin cannot add flags to the host commands' generated help. The hook still recognizes
-both flags before oclif parses the command. To advertise `--llms`, add the exported config to the
-CLI's existing base command:
+the configured names before oclif parses the command, but they do not appear in help automatically.
+To advertise the default `--llms` flag, add the exported definition to the CLI's existing base
+command and set `hidden` to `false`:
 
 ```ts
 import {Command, Flags} from '@oclif/core'
@@ -53,17 +79,46 @@ import {llmsFlagConfig} from '@sanity-labs/oclif-plugin-skills-flag'
 export abstract class BaseCommand extends Command {
   static baseFlags = {
     ...super.baseFlags,
-    llms: Flags.boolean(llmsFlagConfig),
+    llms: Flags.boolean({...llmsFlagConfig, hidden: false}),
   }
 }
 ```
 
 The plugin handles the flag, so command implementations do not need to read `flags.llms`.
 
+For custom names, create a matching definition:
+
+```ts
+import {Command, Flags} from '@oclif/core'
+import {createSkillsFlagDefinition} from '@sanity-labs/oclif-plugin-skills-flag'
+
+const skillsFlag = createSkillsFlagDefinition(
+  {
+    flag: 'agents',
+    aliases: ['agent-help'],
+  },
+  {
+    description: 'Show instructions for coding agents',
+    hidden: false,
+  },
+)
+
+export abstract class BaseCommand extends Command {
+  static baseFlags = {
+    ...super.baseFlags,
+    [skillsFlag.name]: Flags.boolean(skillsFlag.definition),
+  }
+}
+```
+
+The names passed to `createSkillsFlagDefinition` must match the package configuration. `hidden` and
+`description` affect only the flag definition owned by the host CLI; they do not change runtime
+plugin behavior.
+
 ## Limitations
 
 - The plugin targets oclif v4.
-- `--llms` and `--skill` take precedence over same-named host flags.
+- Configured flag names take precedence over same-named host flags.
 - The init hook writes the skill and exits immediately. Later oclif lifecycle hooks do not run.
 
 ## Development

package/dist/hooks/init.d.ts

@@ -1,4 +1,5 @@
 import type { Hook } from "@oclif/core";
+import { type SkillsFlagConfig } from "../skills.ts";
 export interface SkillsFlagRuntime {
     exit(code: number): never;
     write(output: string): void;
@@ -8,6 +9,7 @@ export interface SkillsFlagOptions {
     bin: string;
     commandExists(commandId: string): boolean;
     commandId: string | undefined;
+    config: SkillsFlagConfig;
     error(message: string): void;
     isSingleCommandCLI: boolean;
     root: string;

package/dist/hooks/init.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"init.d.ts","sourceRoot":"","sources":["../../src/hooks/init.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,aAAa,CAAA;AAQvC,MAAM,WAAW,iBAAiB;IAChC,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,KAAK,CAAA;IACzB,KAAK,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAA;CAC5B;AAED,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,MAAM,EAAE,CAAA;IACd,GAAG,EAAE,MAAM,CAAA;IACX,aAAa,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAA;IACzC,SAAS,EAAE,MAAM,GAAG,SAAS,CAAA;IAC7B,KAAK,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;IAC5B,kBAAkB,EAAE,OAAO,CAAA;IAC3B,IAAI,EAAE,MAAM,CAAA;CACb;AAWD,wBAAsB,gBAAgB,CACpC,OAAO,EAAE,iBAAiB,EAC1B,OAAO,GAAE,iBAAkC,GAC1C,OAAO,CAAC,IAAI,CAAC,CAkBf;AAED,QAAA,MAAM,IAAI,EAAE,IAAI,CAAC,IAUhB,CAAA;eAEc,IAAI"}
+{"version":3,"file":"init.d.ts","sourceRoot":"","sources":["../../src/hooks/init.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,aAAa,CAAA;AACvC,OAAO,EAML,KAAK,gBAAgB,EAEtB,MAAM,cAAc,CAAA;AAIrB,MAAM,WAAW,iBAAiB;IAChC,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,KAAK,CAAA;IACzB,KAAK,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAA;CAC5B;AAED,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,MAAM,EAAE,CAAA;IACd,GAAG,EAAE,MAAM,CAAA;IACX,aAAa,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAA;IACzC,SAAS,EAAE,MAAM,GAAG,SAAS,CAAA;IAC7B,MAAM,EAAE,gBAAgB,CAAA;IACxB,KAAK,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;IAC5B,kBAAkB,EAAE,OAAO,CAAA;IAC3B,IAAI,EAAE,MAAM,CAAA;CACb;AAWD,wBAAsB,gBAAgB,CACpC,OAAO,EAAE,iBAAiB,EAC1B,OAAO,GAAE,iBAAkC,GAC1C,OAAO,CAAC,IAAI,CAAC,CAsBf;AAED,QAAA,MAAM,IAAI,EAAE,IAAI,CAAC,IA6ChB,CAAA;eAEc,IAAI"}

package/dist/hooks/init.js

@@ -1,5 +1,7 @@
 import { writeFileSync } from "node:fs";
-import { commandSkillFilename, ensureFinalNewline, hasSkillsFlag, readCommandSkill, } from "../skills.js";
+import { join } from "node:path";
+import { commandSkillFilename, ensureFinalNewline, hasSkillsFlag, readCommandSkill, resolveSkillsFlagConfig, skillsFlagConfigKey, } from "../skills.js";
+const SKILLS_FLAG_PLUGIN_NAME = "@sanity-labs/oclif-plugin-skills-flag";
 const processRuntime = {
     exit(code) {
         process.exit(code);
@@ -9,30 +11,56 @@ const processRuntime = {
     },
 };
 export async function handleSkillsFlag(options, runtime = processRuntime) {
-    if (!hasSkillsFlag(options.argv))
+    if (!hasSkillsFlag(options.argv, options.config))
         return;
     if (!options.commandId || !options.commandExists(options.commandId))
         return;
     const skillCommandId = options.isSingleCommandCLI ? "" : options.commandId;
     const filename = commandSkillFilename(skillCommandId);
-    const skill = await readCommandSkill(skillCommandId, options.root);
+    const skill = await readCommandSkill(skillCommandId, options.root, options.config.directory);
     if (skill === undefined) {
         const commandName = skillCommandId.replaceAll(":", " ") || options.bin;
-        options.error(`No agent guidance is available for \`${commandName}\`.\nAdd it at skills/${filename}.`);
+        options.error(`No agent guidance is available for \`${commandName}\`.\nAdd it at ${join(options.config.directory, filename)}.`);
         return;
     }
     runtime.write(ensureFinalNewline(skill));
     runtime.exit(0);
 }
 const hook = async ({ argv, config, context, id }) => {
+    if (!id)
+        return;
+    // oclif runs transitive init hooks across the assembled CLI, so find the command's actual owner.
+    const command = config.findCommand(id);
+    const commandPlugin = command?.pluginName
+        ? config.plugins.get(command.pluginName)
+        : undefined;
+    // A child CLI's dependency on this plugin must not opt the parent CLI's commands in.
+    if (!commandPlugin?.pjson.oclif.plugins?.includes(SKILLS_FLAG_PLUGIN_NAME)) {
+        return;
+    }
+    // Command shape and skill files belong to the owner, not necessarily the outer host CLI.
+    const commandDiscovery = commandPlugin.pjson.oclif.commands;
+    const isSingleCommandCLI = typeof commandDiscovery !== "string" &&
+        commandDiscovery?.strategy === "single" &&
+        Boolean(commandDiscovery.target);
+    let skillsFlagConfig;
+    try {
+        skillsFlagConfig = resolveSkillsFlagConfig(commandPlugin.pjson[skillsFlagConfigKey]);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        context.error(`Invalid skills flag configuration in ${commandPlugin.name}: ${message}`, { code: "E_SKILLS_FLAG_CONFIG" });
+        return;
+    }
     await handleSkillsFlag({
         argv,
         bin: config.bin,
         commandExists: (commandId) => config.findCommand(commandId) !== undefined,
         commandId: id,
+        config: skillsFlagConfig,
         error: (message) => context.error(message, { code: "E_SKILL_NOT_FOUND" }),
-        isSingleCommandCLI: config.isSingleCommandCLI,
-        root: config.root,
+        isSingleCommandCLI,
+        root: commandPlugin.root,
     });
 };
 export default hook;

package/dist/hooks/init.js.map

@@ -1 +1 @@
-{"version":3,"file":"init.js","sourceRoot":"","sources":["../../src/hooks/init.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,SAAS,CAAA;AAEvC,OAAO,EACL,oBAAoB,EACpB,kBAAkB,EAClB,aAAa,EACb,gBAAgB,GACjB,MAAM,cAAc,CAAA;AAiBrB,MAAM,cAAc,GAAsB;IACxC,IAAI,CAAC,IAAI;QACP,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;IACpB,CAAC;IACD,KAAK,CAAC,MAAM;QACV,aAAa,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,EAAE,MAAM,CAAC,CAAA;IAC1C,CAAC;CACF,CAAA;AAED,MAAM,CAAC,KAAK,UAAU,gBAAgB,CACpC,OAA0B,EAC1B,OAAO,GAAsB,cAAc;IAE3C,IAAI,CAAC,aAAa,CAAC,OAAO,CAAC,IAAI,CAAC;QAAE,OAAM;IACxC,IAAI,CAAC,OAAO,CAAC,SAAS,IAAI,CAAC,OAAO,CAAC,aAAa,CAAC,OAAO,CAAC,SAAS,CAAC;QAAE,OAAM;IAE3E,MAAM,cAAc,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,SAAS,CAAA;IAC1E,MAAM,QAAQ,GAAG,oBAAoB,CAAC,cAAc,CAAC,CAAA;IACrD,MAAM,KAAK,GAAG,MAAM,gBAAgB,CAAC,cAAc,EAAE,OAAO,CAAC,IAAI,CAAC,CAAA;IAElE,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;QACxB,MAAM,WAAW,GAAG,cAAc,CAAC,UAAU,CAAC,GAAG,EAAE,GAAG,CAAC,IAAI,OAAO,CAAC,GAAG,CAAA;QACtE,OAAO,CAAC,KAAK,CACX,wCAAwC,WAAW,yBAAyB,QAAQ,GAAG,CACxF,CAAA;QACD,OAAM;IACR,CAAC;IAED,OAAO,CAAC,KAAK,CAAC,kBAAkB,CAAC,KAAK,CAAC,CAAC,CAAA;IACxC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAA;AACjB,CAAC;AAED,MAAM,IAAI,GAAc,KAAK,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,EAAE,EAAE,EAAE,EAAE;IAC9D,MAAM,gBAAgB,CAAC;QACrB,IAAI;QACJ,GAAG,EAAE,MAAM,CAAC,GAAG;QACf,aAAa,EAAE,CAAC,SAAS,EAAE,EAAE,CAAC,MAAM,CAAC,WAAW,CAAC,SAAS,CAAC,KAAK,SAAS;QACzE,SAAS,EAAE,EAAE;QACb,KAAK,EAAE,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC,OAAO,EAAE,EAAE,IAAI,EAAE,mBAAmB,EAAE,CAAC;QACzE,kBAAkB,EAAE,MAAM,CAAC,kBAAkB;QAC7C,IAAI,EAAE,MAAM,CAAC,IAAI;KAClB,CAAC,CAAA;AACJ,CAAC,CAAA;AAED,eAAe,IAAI,CAAA"}
+{"version":3,"file":"init.js","sourceRoot":"","sources":["../../src/hooks/init.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -1,2 +1,2 @@
-export { commandSkillFilename, ensureFinalNewline, hasSkillsFlag, llmsFlagConfig, readCommandSkill, } from "./skills.ts";
+export { commandSkillFilename, createSkillsFlagDefinition, ensureFinalNewline, hasSkillsFlag, llmsFlagConfig, readCommandSkill, resolveSkillsFlagConfig, type SkillsFlagConfig, type SkillsFlagConfigInput, type SkillsFlagDefinition, type SkillsFlagDefinitionOptions, skillsFlagConfigKey, } from "./skills.ts";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,oBAAoB,EACpB,kBAAkB,EAClB,aAAa,EACb,cAAc,EACd,gBAAgB,GACjB,MAAM,aAAa,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,oBAAoB,EACpB,0BAA0B,EAC1B,kBAAkB,EAClB,aAAa,EACb,cAAc,EACd,gBAAgB,EAChB,uBAAuB,EACvB,KAAK,gBAAgB,EACrB,KAAK,qBAAqB,EAC1B,KAAK,oBAAoB,EACzB,KAAK,2BAA2B,EAChC,mBAAmB,GACpB,MAAM,aAAa,CAAA"}

package/dist/index.js

@@ -1,2 +1,2 @@
-export { commandSkillFilename, ensureFinalNewline, hasSkillsFlag, llmsFlagConfig, readCommandSkill, } from "./skills.js";
+export { commandSkillFilename, createSkillsFlagDefinition, ensureFinalNewline, hasSkillsFlag, llmsFlagConfig, readCommandSkill, resolveSkillsFlagConfig, skillsFlagConfigKey, } from "./skills.js";
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,oBAAoB,EACpB,kBAAkB,EAClB,aAAa,EACb,cAAc,EACd,gBAAgB,GACjB,MAAM,aAAa,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,oBAAoB,EACpB,0BAA0B,EAC1B,kBAAkB,EAClB,aAAa,EACb,cAAc,EACd,gBAAgB,EAChB,uBAAuB,EAKvB,mBAAmB,GACpB,MAAM,aAAa,CAAA"}

package/dist/skills.d.ts

@@ -1,9 +1,35 @@
+export declare const skillsFlagConfigKey = "oclif-plugin-skills-flag";
+export interface SkillsFlagConfig {
+    aliases: string[];
+    directory: string;
+    flag: string;
+}
+export interface SkillsFlagConfigInput {
+    aliases?: readonly string[];
+    directory?: string;
+    flag?: string;
+}
+export interface SkillsFlagDefinition {
+    definition: {
+        aliases: string[];
+        description: string;
+        hidden: boolean;
+    };
+    name: string;
+}
+export interface SkillsFlagDefinitionOptions {
+    description?: string;
+    hidden?: boolean;
+}
+export declare function resolveSkillsFlagConfig(input?: unknown): SkillsFlagConfig;
+export declare function createSkillsFlagDefinition(config?: SkillsFlagConfigInput, options?: SkillsFlagDefinitionOptions): SkillsFlagDefinition;
 export declare const llmsFlagConfig: {
-    readonly aliases: readonly ["skill"];
-    readonly description: "Show agent-oriented guidance for this command";
+    aliases: string[];
+    description: string;
+    hidden: boolean;
 };
 export declare function commandSkillFilename(commandId: string): string;
 export declare function ensureFinalNewline(input: string): string;
-export declare function hasSkillsFlag(argv: string[]): boolean;
-export declare function readCommandSkill(commandId: string, root: string): Promise<string | undefined>;
+export declare function hasSkillsFlag(argv: string[], config?: Pick<SkillsFlagConfig, "aliases" | "flag">): boolean;
+export declare function readCommandSkill(commandId: string, root: string, directory?: string): Promise<string | undefined>;
 //# sourceMappingURL=skills.d.ts.map

package/dist/skills.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"skills.d.ts","sourceRoot":"","sources":["../src/skills.ts"],"names":[],"mappings":"AAMA,eAAO,MAAM,cAAc;aACzB,OAAO,YAAG,OAAO;aACjB,WAAW,EAAE,+CAA+C;CACpD,CAAA;AAEV,wBAAgB,oBAAoB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAc9D;AAED,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAExD;AAED,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAOrD;AAED,wBAAsB,gBAAgB,CACpC,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAS7B"}
+{"version":3,"file":"skills.d.ts","sourceRoot":"","sources":["../src/skills.ts"],"names":[],"mappings":"AAWA,eAAO,MAAM,mBAAmB,6BAA6B,CAAA;AAE7D,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,MAAM,EAAE,CAAA;IACjB,SAAS,EAAE,MAAM,CAAA;IACjB,IAAI,EAAE,MAAM,CAAA;CACb;AAED,MAAM,WAAW,qBAAqB;IACpC,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;IAC3B,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,IAAI,CAAC,EAAE,MAAM,CAAA;CACd;AAED,MAAM,WAAW,oBAAoB;IACnC,UAAU,EAAE;QACV,OAAO,EAAE,MAAM,EAAE,CAAA;QACjB,WAAW,EAAE,MAAM,CAAA;QACnB,MAAM,EAAE,OAAO,CAAA;KAChB,CAAA;IACD,IAAI,EAAE,MAAM,CAAA;CACb;AAED,MAAM,WAAW,2BAA2B;IAC1C,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,MAAM,CAAC,EAAE,OAAO,CAAA;CACjB;AAkCD,wBAAgB,uBAAuB,CACrC,KAAK,GAAE,OAAmB,GACzB,gBAAgB,CAuClB;AAED,wBAAgB,0BAA0B,CACxC,MAAM,GAAE,qBAA0B,EAClC,OAAO,GAAE,2BAAgC,GACxC,oBAAoB,CAoBtB;AAED,eAAO,MAAM,cAAc;aAhHd,MAAM,EAAE;iBACJ,MAAM;YACX,OAAO;CA8GkD,CAAA;AAErE,wBAAgB,oBAAoB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAc9D;AAED,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAExD;AAED,wBAAgB,aAAa,CAC3B,IAAI,EAAE,MAAM,EAAE,EACd,MAAM,GAAE,IAAI,CACV,gBAAgB,EAChB,SAAS,GAAG,MAAM,CACU,GAC7B,OAAO,CAcT;AAED,wBAAsB,gBAAgB,CACpC,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,MAAM,EACZ,SAAS,SAAuC,GAC/C,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAa7B"}

package/dist/skills.js

@@ -1,11 +1,82 @@
 import { readFile } from "node:fs/promises";
-import { join } from "node:path";
-const SKILLS_DIRECTORY = "skills";
-const SKILLS_FLAGS = new Set(["--llms", "--skill"]);
-export const llmsFlagConfig = {
+import { join, posix, win32 } from "node:path";
+const DEFAULT_DESCRIPTION = "Show agent-oriented guidance for this command";
+const DEFAULT_SKILLS_FLAG_CONFIG = {
     aliases: ["skill"],
-    description: "Show agent-oriented guidance for this command",
+    directory: "skills",
+    flag: "llms",
 };
+const SKILLS_FLAG_CONFIG_OPTIONS = new Set(["aliases", "directory", "flag"]);
+export const skillsFlagConfigKey = "oclif-plugin-skills-flag";
+function validateFlagName(value, kind) {
+    if (typeof value !== "string" ||
+        value.length === 0 ||
+        value.startsWith("-") ||
+        /[\s=\0]/u.test(value)) {
+        throw new TypeError(`Invalid flag ${kind}: expected a name without leading dashes, whitespace, or "="`);
+    }
+    return value;
+}
+function validateSkillsDirectory(value) {
+    if (typeof value !== "string" ||
+        value.length === 0 ||
+        value.includes("\0") ||
+        posix.isAbsolute(value) ||
+        win32.isAbsolute(value) ||
+        value.split(/[\\/]/u).includes("..")) {
+        throw new TypeError("Invalid skills directory: expected a relative path without parent traversal");
+    }
+    return value;
+}
+export function resolveSkillsFlagConfig(input = undefined) {
+    if (input !== undefined &&
+        (typeof input !== "object" || input === null || Array.isArray(input))) {
+        throw new TypeError("Skills flag configuration must be an object");
+    }
+    const options = (input ?? {});
+    for (const option of Object.keys(options)) {
+        if (!SKILLS_FLAG_CONFIG_OPTIONS.has(option)) {
+            throw new TypeError(`Unknown configuration option: ${option}`);
+        }
+    }
+    const flag = validateFlagName(options.flag ?? DEFAULT_SKILLS_FLAG_CONFIG.flag, "name");
+    const aliasesInput = options.aliases ?? [
+        ...DEFAULT_SKILLS_FLAG_CONFIG.aliases,
+    ];
+    if (!Array.isArray(aliasesInput)) {
+        throw new TypeError("Skills flag aliases must be an array");
+    }
+    const aliases = aliasesInput.map((alias) => validateFlagName(alias, "alias"));
+    const names = [flag, ...aliases];
+    if (new Set(names).size !== names.length) {
+        throw new TypeError("Duplicate flag name in flag or aliases");
+    }
+    return {
+        aliases,
+        directory: validateSkillsDirectory(options.directory ?? DEFAULT_SKILLS_FLAG_CONFIG.directory),
+        flag,
+    };
+}
+export function createSkillsFlagDefinition(config = {}, options = {}) {
+    const resolved = resolveSkillsFlagConfig(config);
+    const description = options.description ?? DEFAULT_DESCRIPTION;
+    const hidden = options.hidden ?? true;
+    if (typeof description !== "string") {
+        throw new TypeError("Flag description must be a string");
+    }
+    if (typeof hidden !== "boolean") {
+        throw new TypeError("Flag visibility must be a boolean");
+    }
+    return {
+        definition: {
+            aliases: resolved.aliases,
+            description,
+            hidden,
+        },
+        name: resolved.flag,
+    };
+}
+export const llmsFlagConfig = createSkillsFlagDefinition().definition;
 export function commandSkillFilename(commandId) {
     const filename = commandId.replaceAll(":", "-") || "index";
     if (filename === "." ||
@@ -20,17 +91,21 @@ export function commandSkillFilename(commandId) {
 export function ensureFinalNewline(input) {
     return input.endsWith("\n") ? input : `${input}\n`;
 }
-export function hasSkillsFlag(argv) {
+export function hasSkillsFlag(argv, config = DEFAULT_SKILLS_FLAG_CONFIG) {
+    const flags = new Set([
+        `--${config.flag}`,
+        ...config.aliases.map((alias) => alias.length === 1 ? `-${alias}` : `--${alias}`),
+    ]);
     for (const argument of argv) {
         if (argument === "--")
             return false;
-        if (SKILLS_FLAGS.has(argument))
+        if (flags.has(argument))
             return true;
     }
     return false;
 }
-export async function readCommandSkill(commandId, root) {
-    const path = join(root, SKILLS_DIRECTORY, commandSkillFilename(commandId));
+export async function readCommandSkill(commandId, root, directory = DEFAULT_SKILLS_FLAG_CONFIG.directory) {
+    const path = join(root, validateSkillsDirectory(directory), commandSkillFilename(commandId));
     try {
         return await readFile(path, "utf8");
     }

package/dist/skills.js.map

@@ -1 +1 @@
-{"version":3,"file":"skills.js","sourceRoot":"","sources":["../src/skills.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAA;AAC3C,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAA;AAEhC,MAAM,gBAAgB,GAAG,QAAQ,CAAA;AACjC,MAAM,YAAY,GAAG,IAAI,GAAG,CAAC,CAAC,QAAQ,EAAE,SAAS,CAAC,CAAC,CAAA;AAEnD,MAAM,CAAC,MAAM,cAAc,GAAG;IAC5B,OAAO,EAAE,CAAC,OAAO,CAAC;IAClB,WAAW,EAAE,+CAA+C;CACpD,CAAA;AAEV,MAAM,UAAU,oBAAoB,CAAC,SAAiB;IACpD,MAAM,QAAQ,GAAG,SAAS,CAAC,UAAU,CAAC,GAAG,EAAE,GAAG,CAAC,IAAI,OAAO,CAAA;IAE1D,IACE,QAAQ,KAAK,GAAG;QAChB,QAAQ,KAAK,IAAI;QACjB,QAAQ,CAAC,QAAQ,CAAC,GAAG,CAAC;QACtB,QAAQ,CAAC,QAAQ,CAAC,IAAI,CAAC;QACvB,QAAQ,CAAC,QAAQ,CAAC,IAAI,CAAC,EACvB,CAAC;QACD,MAAM,IAAI,SAAS,CAAC,6BAA6B,SAAS,EAAE,CAAC,CAAA;IAC/D,CAAC;IAED,OAAO,GAAG,QAAQ,KAAK,CAAA;AACzB,CAAC;AAED,MAAM,UAAU,kBAAkB,CAAC,KAAa;IAC9C,OAAO,KAAK,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,GAAG,KAAK,IAAI,CAAA;AACpD,CAAC;AAED,MAAM,UAAU,aAAa,CAAC,IAAc;IAC1C,KAAK,MAAM,QAAQ,IAAI,IAAI,EAAE,CAAC;QAC5B,IAAI,QAAQ,KAAK,IAAI;YAAE,OAAO,KAAK,CAAA;QACnC,IAAI,YAAY,CAAC,GAAG,CAAC,QAAQ,CAAC;YAAE,OAAO,IAAI,CAAA;IAC7C,CAAC;IAED,OAAO,KAAK,CAAA;AACd,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,gBAAgB,CACpC,SAAiB,EACjB,IAAY;IAEZ,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,EAAE,gBAAgB,EAAE,oBAAoB,CAAC,SAAS,CAAC,CAAC,CAAA;IAE1E,IAAI,CAAC;QACH,OAAO,MAAM,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,CAAA;IACrC,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAK,KAA+B,CAAC,IAAI,KAAK,QAAQ;YAAE,OAAM;QAC9D,MAAM,KAAK,CAAA;IACb,CAAC;AACH,CAAC"}
+{"version":3,"file":"skills.js","sourceRoot":"","sources":["../src/skills.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sanity-labs/oclif-plugin-skills-flag",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "description": "Expose per-command Markdown to coding agents through an oclif flag",
   "author": "Sanity",
   "license": "MIT",