@sanity-labs/oclif-plugin-skills-flag 0.1.0

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 Sanity
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

package/README.md

@@ -0,0 +1,79 @@
+# @sanity-labs/oclif-plugin-skills-flag
+
+Adds `--llms` and its `--skill` alias to every command in an oclif v4 CLI. The flag prints
+command-specific Markdown for coding agents, then exits without running the command.
+
+## Install
+
+Install the plugin in the CLI:
+
+```sh
+npm install @sanity-labs/oclif-plugin-skills-flag
+```
+
+Register it in the CLI's `package.json`:
+
+```json
+{
+  "oclif": {
+    "plugins": ["@sanity-labs/oclif-plugin-skills-flag"]
+  }
+}
+```
+
+Add a `skills` directory at the package root. Name each file after its oclif command ID, replacing
+colons with hyphens:
+
+```text
+skills/
+├── deploy.md
+└── functions-test.md
+```
+
+These commands then print the matching files:
+
+```sh
+my-cli deploy --llms
+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.
+
+## 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:
+
+```ts
+import {Command, Flags} from '@oclif/core'
+import {llmsFlagConfig} from '@sanity-labs/oclif-plugin-skills-flag'
+
+export abstract class BaseCommand extends Command {
+  static baseFlags = {
+    ...super.baseFlags,
+    llms: Flags.boolean(llmsFlagConfig),
+  }
+}
+```
+
+The plugin handles the flag, so command implementations do not need to read `flags.llms`.
+
+## Limitations
+
+- The plugin targets oclif v4.
+- `--llms` and `--skill` take precedence over same-named host flags.
+- The init hook writes the skill and exits immediately. Later oclif lifecycle hooks do not run.
+
+## Development
+
+mise selects Node 24, which runs the TypeScript tests directly:
+
+```sh
+npm install
+npm test
+```
+
+Run `npm run build` to create the publishable files in `dist/`. Use `npm run lint:fix` to apply
+Biome formatting and safe lint fixes.

package/dist/hooks/init.d.ts

@@ -0,0 +1,18 @@
+import type { Hook } from "@oclif/core";
+export interface SkillsFlagRuntime {
+    exit(code: number): never;
+    write(output: string): void;
+}
+export interface SkillsFlagOptions {
+    argv: string[];
+    bin: string;
+    commandExists(commandId: string): boolean;
+    commandId: string | undefined;
+    error(message: string): void;
+    isSingleCommandCLI: boolean;
+    root: string;
+}
+export declare function handleSkillsFlag(options: SkillsFlagOptions, runtime?: SkillsFlagRuntime): Promise<void>;
+declare const hook: Hook.Init;
+export default hook;
+//# sourceMappingURL=init.d.ts.map

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

@@ -0,0 +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"}

package/dist/hooks/init.js

@@ -0,0 +1,39 @@
+import { writeFileSync } from "node:fs";
+import { commandSkillFilename, ensureFinalNewline, hasSkillsFlag, readCommandSkill, } from "../skills.js";
+const processRuntime = {
+    exit(code) {
+        process.exit(code);
+    },
+    write(output) {
+        writeFileSync(process.stdout.fd, output);
+    },
+};
+export async function handleSkillsFlag(options, runtime = processRuntime) {
+    if (!hasSkillsFlag(options.argv))
+        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);
+    if (skill === undefined) {
+        const commandName = skillCommandId.replaceAll(":", " ") || options.bin;
+        options.error(`No agent guidance is available for \`${commandName}\`.\nAdd it at skills/${filename}.`);
+        return;
+    }
+    runtime.write(ensureFinalNewline(skill));
+    runtime.exit(0);
+}
+const hook = async ({ argv, config, context, id }) => {
+    await handleSkillsFlag({
+        argv,
+        bin: config.bin,
+        commandExists: (commandId) => config.findCommand(commandId) !== undefined,
+        commandId: id,
+        error: (message) => context.error(message, { code: "E_SKILL_NOT_FOUND" }),
+        isSingleCommandCLI: config.isSingleCommandCLI,
+        root: config.root,
+    });
+};
+export default hook;
+//# sourceMappingURL=init.js.map

package/dist/hooks/init.js.map

@@ -0,0 +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"}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { commandSkillFilename, ensureFinalNewline, hasSkillsFlag, llmsFlagConfig, readCommandSkill, } from "./skills.ts";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +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"}

package/dist/index.js

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

package/dist/index.js.map

@@ -0,0 +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"}

package/dist/skills.d.ts

@@ -0,0 +1,9 @@
+export declare const llmsFlagConfig: {
+    readonly aliases: readonly ["skill"];
+    readonly description: "Show agent-oriented guidance for this command";
+};
+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>;
+//# sourceMappingURL=skills.d.ts.map

package/dist/skills.d.ts.map

@@ -0,0 +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"}

package/dist/skills.js

@@ -0,0 +1,43 @@
+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 = {
+    aliases: ["skill"],
+    description: "Show agent-oriented guidance for this command",
+};
+export function commandSkillFilename(commandId) {
+    const filename = commandId.replaceAll(":", "-") || "index";
+    if (filename === "." ||
+        filename === ".." ||
+        filename.includes("/") ||
+        filename.includes("\\") ||
+        filename.includes("\0")) {
+        throw new TypeError(`Invalid oclif command ID: ${commandId}`);
+    }
+    return `${filename}.md`;
+}
+export function ensureFinalNewline(input) {
+    return input.endsWith("\n") ? input : `${input}\n`;
+}
+export function hasSkillsFlag(argv) {
+    for (const argument of argv) {
+        if (argument === "--")
+            return false;
+        if (SKILLS_FLAGS.has(argument))
+            return true;
+    }
+    return false;
+}
+export async function readCommandSkill(commandId, root) {
+    const path = join(root, SKILLS_DIRECTORY, commandSkillFilename(commandId));
+    try {
+        return await readFile(path, "utf8");
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return;
+        throw error;
+    }
+}
+//# sourceMappingURL=skills.js.map

package/dist/skills.js.map

@@ -0,0 +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"}

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "@sanity-labs/oclif-plugin-skills-flag",
+  "version": "0.1.0",
+  "description": "Expose per-command Markdown to coding agents through an oclif flag",
+  "author": "Sanity",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "LICENSE",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc --project tsconfig.build.json",
+    "lint": "biome ci .",
+    "lint:fix": "biome check --write .",
+    "prepack": "npm test && npm run build",
+    "test": "npm run typecheck && node --test test/*.test.ts && npm run lint",
+    "typecheck": "tsc --noEmit"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "peerDependencies": {
+    "@oclif/core": "^4.0.0"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "2.5.5",
+    "@oclif/core": "^4.11.14",
+    "@types/node": "^22.0.0",
+    "typescript": "^7.0.2"
+  },
+  "oclif": {
+    "hooks": {
+      "init": "./dist/hooks/init.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/sanity-labs/oclif-plugin-skills-flag.git"
+  },
+  "bugs": "https://github.com/sanity-labs/oclif-plugin-skills-flag/issues",
+  "homepage": "https://github.com/sanity-labs/oclif-plugin-skills-flag#readme",
+  "keywords": [
+    "agent",
+    "llm",
+    "oclif",
+    "oclif-plugin",
+    "skill"
+  ]
+}