dryai 2.1.0 → 3.0.0

package/README.md

@@ -1,22 +1,24 @@
 # Share AI config CLI
 
-Installs command, rule, and skill sources from `~/.config/dryai` by default into Copilot and Cursor targets.
+Syncs command, rule, and skill sources from `~/.config/dryai` by default into supported agent targets.
 
-Pass `--config-root <path>` to read configs from a different root such as `./config`.
+Global CLI options:
 
-Pass `--output-root <path>` to write generated output somewhere other than your home directory.
+- `--config-root <path>` reads configs from a different root such as `./config`.
+- `--output-root <path>` writes generated output somewhere other than your home directory.
+- `--test` is a shortcut for `--output-root ./output-test`, and if both are provided, `--output-root` wins.
 
-`--test` is a shortcut for `--output-root ./output-test`, and if both are provided, `--output-root` wins.
+These are root-level options for the CLI. They modify command behavior for any given command.
 
-## Input
+## Config Layout
 
-Input config files live under the selected input root:
+Input config files live under the selected config root:
 
 - `commands`
 - `rules`
 - `skills`
 
-Live output is written to:
+The current built-in agent config writes live output to these default roots:
 
 - `~/.copilot/prompts`
 - `~/.copilot/instructions`
@@ -24,9 +26,7 @@ Live output is written to:
 - `~/.cursor/rules`
 - `~/.cursor/skills`
 
-## Example Configs
-
-One input root can contain all three source types:
+One config root can contain all three source types:
 
 ```text
 ~/.config/dryai/
@@ -39,25 +39,128 @@ One input root can contain all three source types:
         └── SKILL.md
 ```
 
+See VS Code editor setup note below.
+
+## Commands
+
+### `sync`
+
+- Purpose: Sync commands, rules, and skills from the selected config root into the configured agent target directories.
+- Input roots: Reads from `commands`, `rules`, and `skills` under the selected config root.
+- Output roots: Writes to the live output paths listed in Config Layout by default.
+- Pruning: Removes stale dryai-managed outputs that were written by earlier sync runs but are no longer present in the selected config root.
+- Safety: Only prunes outputs tracked in `sync-manifest.json`; unrelated user files in target roots are left alone.
+
+### `skills add`
+
+- Purpose: Import one or more managed skills from a remote repository.
+- Repository argument: `<repo>` may be a full git remote URL or a GitHub `owner/repo` shorthand such as `anthropics/skills`.
+- Storage: Imported skills are copied into `config/skills/<name>/` and tracked in `skills.lock.json`.
+- Config root: Local skill directories and `skills.lock.json` are read from and written to the selected config root.
+- Required: `--skill <name>` is required at least once.
+- Default resolution: Each requested skill resolves from `<repo root>/skills/<name>`.
+- `--path <repoPath>`: Resolves each requested skill from a different base directory.
+- `--path .`: Resolves each requested skill from the repository root itself.
+- `--as <name>`: Stores the imported skill under a different local managed name when importing exactly one skill.
+- `--ref <gitRef>`: Fetches a specific branch, tag, or commit instead of the remote default branch.
+- `--pin`: Stores the resolved commit instead of tracking a moving ref.
+- Examples:
+
+```sh
+# Resolves from <repo root>/skills/skill-creator
+dryai skills add anthropics/skills --skill skill-creator
+
+# Resolves from <repo root>/review-helper
+dryai skills add anthropics/skills --path . --skill review-helper
+
+# Resolves from <repo root>/tools/review-helper
+dryai skills add anthropics/skills --path tools --skill review-helper
+
+# Resolves from <repo root>/skills/pr-review and <repo root>/skills/commit
+dryai skills add vercel-labs/agent-skills --skill pr-review commit
+
+# Resolves from <repo root>/skills/pr-review and <repo root>/skills/commit
+dryai skills add https://github.com/vercel-labs/agent-skills.git --skill pr-review commit
+```
+
+By default, imports track the requested ref. With no `--ref`, that means the remote default branch `HEAD` is tracked.
+
+### `skills update`
+
+- Purpose: Re-fetch one managed skill from its tracked source and replace the local copied directory.
+- `--force`: Overwrites local edits instead of skipping the update.
+
+### `skills update-all`
+
+- Purpose: Re-fetch all managed skills from their tracked sources and replace the local copied directories.
+- `--force`: Overwrites local edits instead of skipping the update.
+
+### `skills rehash`
+
+- Purpose: Refresh the stored file hashes for one managed skill using its current local contents.
+
+### `skills rehash-all`
+
+- Purpose: Refresh the stored file hashes for every managed skill using their current local contents.
+- Behavior: Skips managed entries whose local directory is missing.
+
+### `skills remove`
+
+- Purpose: Delete a managed skill's local copied directory and remove its lockfile entry.
+
+### `skills list`
+
+- Purpose: Report local skill directories, annotate managed entries from the lockfile, and flag managed entries whose local directory is missing.
+
+### `skills` lockfile
+
+The lockfile records:
+
+- the local skill name
+- the source repository
+- the source path within that repository
+- the requested git ref, when one was provided
+- the resolved commit that was imported
+- the last installed content hash for each file in the managed skill directory
+
+Before replacing a managed skill, `dryai` compares the current local files against the hashes stored in `skills.lock.json`. If any file was added, removed, or edited locally, the update is skipped and a warning is printed so you do not lose your customizations by accident.
+
+For skills imported before hash tracking existed, use these commands to store hashes from the current local directory without fetching from the remote source:
+
+```sh
+dryai skills rehash review-helper
+dryai skills rehash-all
+```
+
+Use these commands to intentionally overwrite local edits:
+
+```sh
+dryai skills update review-helper --force
+dryai skills update-all --force
+```
+
+## Example Configs
+
 ### Example Rule
 
 Rules are markdown files under `rules/`. `dryai` recognizes these rule frontmatter fields:
 
 - `description`
-- `copilot.applyTo`
-- `cursor.alwaysApply`
-- `cursor.globs`
+- `agents.copilot.applyTo`
+- `agents.cursor.alwaysApply`
+- `agents.cursor.globs`
 
-`cursor.globs` should be provided as one comma-separated glob string.
+`agents.cursor.globs` should be provided as one comma-separated glob string.
 
 ```md
 ---
 description: Reply with "Yes, Captain!" before answering when the user says "Make it so" or "Engage".
-copilot:
-  applyTo: '**/*.tsx, **/*.ts, src/**/*.ts, src/**/*.tsx, src/**/*.js, src/**/*.jsx'
-cursor:
-  alwaysApply: false
-  globs: '**/*.tsx, **/*.ts, src/**/*.ts, src/**/*.tsx, src/**/*.js, src/**/*.jsx'
+agents:
+  copilot:
+    applyTo: '**/*.tsx, **/*.ts, src/**/*.ts, src/**/*.tsx, src/**/*.js, src/**/*.jsx'
+  cursor:
+    alwaysApply: false
+    globs: '**/*.tsx, **/*.ts, src/**/*.ts, src/**/*.tsx, src/**/*.js, src/**/*.jsx'
 ---
 
 # Say Yes Captain
@@ -71,14 +174,15 @@ Commands are markdown files under `commands/`. `dryai` recognizes these command
 
 - `name`
 - `description`
-- `cursor.disable-model-invocation`
+- `agents.cursor.disable-model-invocation`
 
 ```md
 ---
 name: gen-commit-msg
 description: Generate a conventional commit message from the current staged git diff.
-cursor:
-  disable-model-invocation: true
+agents:
+  cursor:
+    disable-model-invocation: true
 ---
 
 # Generate Commit Message
@@ -88,9 +192,9 @@ Read the staged diff and produce a conventional commit message with a concise su
 
 ### Example Skill
 
-Skills live in directories under `skills/`. The directory is copied as-is into the Copilot and Cursor skills targets.
+Skills live in directories under `skills/`. The directory is copied as-is into the configured agent skill targets.
 
-Unlike commands and rules, `dryai` does not define or validate a fixed skill frontmatter schema. Skill files are passed through unchanged, so the allowed frontmatter fields depend on the skill format expected by the target editor or agent.
+Unlike commands and rules, `dryai` does not define or validate a fixed skill frontmatter schema. Skill files are passed through unchanged, so the allowed frontmatter fields depend on the skill format expected by the target agent.
 
 ```text
 skills/
@@ -112,77 +216,9 @@ Focus on findings first.
 - Keep the overview brief unless the user asks for a deeper walkthrough.
 ```
 
-## Commands
-
-```sh
-dryai install
-dryai skills list                                 List local skills
-dryai skills add [options] <repo>                 Add managed skills from a remote repository
-dryai skills remove <name>                        Remove a managed skill
-dryai skills rehash <name>                        Refresh stored file hashes for one managed skill
-dryai skills rehash-all                           Refresh stored file hashes for all managed skills
-dryai skills update [options] <name>              Update a managed skill from its tracked source
-dryai skills update-all [options]                 Update all managed skills from their tracked sources
-```
-
-`<repo>` may be a full git remote URL or a GitHub `owner/repo` shorthand such as `anthropics/skills`.
-
-## Managed Skills
-
-Imported skills are copied into `config/skills/<name>/` and tracked in `skills.lock.json`.
-
-When you run `skills` commands, local skill directories and `skills.lock.json` are read from and written to the selected config root.
-
-`skills add` requires at least one `--skill <name>` value. Each requested skill is always resolved from `<repo root>/skills/<name>`.
-
-Use `--as <name>` to choose a different local managed skill name when importing exactly one skill.
-
-Examples:
-
-```sh
-dryai skills add anthropics/skills --skill skill-creator
-dryai skills add vercel-labs/agent-skills --skill pr-review commit
-dryai skills add https://github.com/vercel-labs/agent-skills.git --skill pr-review commit
-```
-
-By default, imports track the requested ref. With no `--ref`, that means the remote default branch `HEAD` is tracked. Use `--pin` to store the currently resolved commit instead, so later `skills update` operations stay pinned to that commit.
-
-The lockfile records:
-
-- the local skill name
-- the source repository
-- the source path within that repository
-- the requested git ref, when one was provided
-- the resolved commit that was imported
-- the last installed content hash for each file in the managed skill directory
-
-`skills update` and `skills update-all` re-fetch the tracked repository snapshot and replace the local copied skill directory.
-
-Before replacing a managed skill, `dryai` compares the current local files against the hashes stored in `skills.lock.json`. If any file was added, removed, or edited locally, the update is skipped and a warning is printed so you do not lose your customizations by accident.
-
-For skills imported before hash tracking existed, use `rehash` to store hashes from the current local directory without fetching from the remote source:
-
-```sh
-dryai skills rehash review-helper
-dryai skills rehash-all
-```
-
-Use `--force` to intentionally overwrite local edits:
-
-```sh
-dryai skills update review-helper --force
-dryai skills update-all --force
-```
-
-`skills remove` deletes the local copied skill directory and removes its lockfile entry.
-
-`skills list` reports local skill directories, annotating managed entries from the lockfile and flagging managed entries whose local directory is missing.
-
-`skills rehash` updates the stored file hashes for one managed skill using its current local contents. `skills rehash-all` does the same for every managed skill and skips any managed entry whose local directory is missing.
-
 ## Development
 
-For development, use `pnpm dev` to rebuild into `dest/` on change and `pnpm dev:dryai --test install` to run the built CLI.
+For development, use `pnpm dev` to rebuild into `dest/` on change and `pnpm dev:dryai <...>` to run the built CLI.
 
 Run `pnpm run setup:editor` after installing dependencies if you want the Effect language service workspace patch applied locally.
 
@@ -193,39 +229,21 @@ pnpm run dev
 pnpm run test
 pnpm run test:watch
 
-pnpm dev:dryai install
-pnpm dev:dryai --test install
-pnpm dev:dryai --output-root ./tmp/install-root install
-pnpm dev:dryai --config-root ./config install
+pnpm dev:dryai <...>
 ```
 
-## CI and Release
-
-- On pull request open or update
-  - Run CI validation with build, test, and `npm pack --dry-run`.
-- On changes landing on `main`
-  - Run the same CI validation with build, test, and `npm pack --dry-run`.
-
-- On `v*` tag pushed to `main`, the release workflow will:
-  - Verify the tag matches the checked-in `package.json` version.
-  - Verify the tagged commit is on `main`.
-  - Build and test the CLI.
-  - Create a tarball with `npm pack`.
-  - Create or update the matching GitHub Release.
-  - Upload the tarball as a release asset.
-- After the release workflow succeeds, the publish workflow will:
-  - Download the tarball artifact produced by the release workflow.
-  - Publish that exact tarball to npm using npm trusted publishing.
+---
 
-Example release flow:
+## VS Code Setup
 
-```sh
-git tag v0.1.0
-git push origin v0.1.0
-```
+One current editor-specific note: VS Code does not automatically discover prompt files from the Copilot prompt target at `~/.copilot/prompts`.
 
-Install from the release tarball with:
+Add this to your VS Code user settings if you want prompt files installed by `dryai` into that target to be picked up:
 
-```sh
-npm install -g https://github.com/willmruzek/share-ai-config/releases/download/v0.1.0/share-ai-config-0.1.0.tgz
+```json
+{
+  "chat.promptFilesLocations": {
+    "~/.copilot/prompts": true
+  }
+}
 ```

package/dest/cli.d.ts

@@ -0,0 +1,68 @@
+import { Command } from 'commander';
+import { z } from 'zod';
+import { type AgentsContext } from './lib/context.js';
+declare const rootOptionsSchema: z.ZodObject<{
+    test: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+    configRoot: z.ZodOptional<z.ZodString>;
+    outputRoot: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type RootOptions = z.output<typeof rootOptionsSchema>;
+/**
+ * Raw stdout/stderr write functions, without newline conventions. These are
+ * the CLI-layer primitive used by Commander for help and version output; they
+ * also back the higher-level {@link CLIRuntime}.
+ */
+export type StdioWriters = {
+    writeOut: (output: string) => void;
+    writeErr: (output: string) => void;
+};
+/**
+ * The line-oriented output interface available to every command action.
+ *
+ * Both methods append a trailing newline. The `log*` prefix is used to make
+ * call sites trivially greppable ("where do we emit CLI output?") without
+ * colliding with `console.log` / `console.warn` or arbitrary variables.
+ *
+ * Commands should not reach for the underlying {@link StdioWriters.writeOut}
+ * / {@link StdioWriters.writeErr} stream writes; that raw byte-level stream
+ * access is confined to the CLI layer (Commander help/version output).
+ */
+export type CLIRuntime = {
+    /** Writes an informational message to stdout, with an appended newline. */
+    logInfo: (message: string) => void;
+    /** Writes a warning message to stderr, with an appended newline. */
+    logWarn: (message: string) => void;
+};
+/**
+ * The shared environment passed into every command action: the
+ * resolved domain context plus the runtime used for CLI output.
+ */
+export type CommandEnv = {
+    context: AgentsContext;
+    runtime: CLIRuntime;
+};
+export type CLIOptions = {
+    executableName?: string;
+    version: string;
+    stdioWriters?: StdioWriters;
+};
+/**
+ * Builds an AgentsContext from the parsed root options, expanding ~ in paths and applying --test path defaults.
+ */
+export declare function resolveActiveContext(rootOptions: RootOptions): AgentsContext;
+/**
+ * Creates the production stdio writers backed by the real process streams.
+ */
+export declare function createProductionStdioWriters(): StdioWriters;
+/**
+ * Builds and returns the Commander program with all subcommands and global flags registered.
+ */
+export declare function createCLI(options: CLIOptions): Command;
+/**
+ * Parses argv and runs the matching command, returning the Commander program after completion.
+ */
+export declare function runCLI(input: {
+    argv: string[];
+} & CLIOptions): Promise<Command>;
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dest/cli.js

@@ -0,0 +1,147 @@
+import { Command } from 'commander';
+import { z } from 'zod';
+import { addSkillsCommand } from './commands/skills/index.js';
+import { runSyncCommand } from './commands/sync.js';
+import { describeSupportedAgents } from './lib/agents.js';
+import { nonEmptyOptionStringSchema, parseOptionValue, parseOptionsObject, } from './lib/command-options.js';
+import { createAgentsContext, resolveRequestedConfigRoot, resolveRequestedOutputRoot, } from './lib/context.js';
+const rootOptionsSchema = z.object({
+    test: z.boolean().optional().default(false),
+    configRoot: nonEmptyOptionStringSchema.optional(),
+    outputRoot: nonEmptyOptionStringSchema.optional(),
+});
+/**
+ * Parses the top-level CLI options into a validated shape.
+ */
+function getRootOptions(program) {
+    return parseOptionsObject({
+        schema: rootOptionsSchema,
+        options: program.opts(),
+        optionsLabel: 'root options',
+    });
+}
+/**
+ * Returns true if --test or --output-root was passed.
+ */
+function requestedOutputRootWasUsed(rootOptions) {
+    return rootOptions.test || rootOptions.outputRoot !== undefined;
+}
+/**
+ * Builds an AgentsContext from the parsed root options, expanding ~ in paths and applying --test path defaults.
+ */
+export function resolveActiveContext(rootOptions) {
+    const requestedConfigRoot = resolveRequestedConfigRoot({
+        ...(rootOptions.configRoot ? { configRoot: rootOptions.configRoot } : {}),
+    });
+    const requestedOutputRoot = resolveRequestedOutputRoot({
+        test: rootOptions.test,
+        ...(rootOptions.outputRoot ? { outputRoot: rootOptions.outputRoot } : {}),
+    });
+    return createAgentsContext({
+        ...(requestedConfigRoot ? { inputRoot: requestedConfigRoot } : {}),
+        ...(requestedOutputRoot ? { outputRoot: requestedOutputRoot } : {}),
+    });
+}
+/**
+ * Derives a {@link CLIRuntime} from a pair of raw stdio writers by wrapping
+ * each writer with the line-oriented newline convention.
+ */
+function wrapStdioWriters(stdioWriters) {
+    return {
+        logInfo(message) {
+            stdioWriters.writeOut(`${message}\n`);
+        },
+        logWarn(message) {
+            stdioWriters.writeErr(`${message}\n`);
+        },
+    };
+}
+/**
+ * Creates the production stdio writers backed by the real process streams.
+ */
+export function createProductionStdioWriters() {
+    return {
+        writeOut(output) {
+            process.stdout.write(output);
+        },
+        writeErr(output) {
+            process.stderr.write(output);
+        },
+    };
+}
+/**
+ * Merges the provided CLIOptions with production defaults, returning a fully resolved options object.
+ */
+function resolveCLIOptions(options) {
+    return {
+        executableName: options.executableName ?? 'dryai',
+        version: options.version,
+        stdioWriters: options.stdioWriters ?? createProductionStdioWriters(),
+    };
+}
+/**
+ * Builds and returns the Commander program with all subcommands and global flags registered.
+ */
+export function createCLI(options) {
+    const resolvedOptions = resolveCLIOptions(options);
+    const program = new Command();
+    const executableName = resolvedOptions.executableName;
+    const stdioWriters = resolvedOptions.stdioWriters;
+    const runtime = wrapStdioWriters(stdioWriters);
+    const resolveEnv = () => ({
+        context: resolveActiveContext(getRootOptions(program)),
+        runtime,
+    });
+    program.configureOutput({
+        writeOut: (output) => {
+            stdioWriters.writeOut(output);
+        },
+        writeErr: (output) => {
+            stdioWriters.writeErr(output);
+        },
+    });
+    program
+        .name(executableName)
+        .usage('[options] <command> [args]')
+        .helpOption('-h, --help', 'Display this message')
+        .version(resolvedOptions.version, '-v, --version', 'Display the current version')
+        .option('--test', 'Shortcut for writing generated output into ./output-test unless --output-root is also provided')
+        .option('--config-root <path>', 'Read configs from a different root instead of ~/.config/dryai', parseOptionValue({
+        schema: nonEmptyOptionStringSchema,
+        optionLabel: '--config-root',
+    }))
+        .option('--output-root <path>', 'Write generated output under a different root instead of the default home directory', parseOptionValue({
+        schema: nonEmptyOptionStringSchema,
+        optionLabel: '--output-root',
+    }))
+        .helpCommand(false)
+        .action(() => {
+        program.outputHelp();
+    });
+    program
+        .command('sync')
+        .description(`Sync generated output into ${describeSupportedAgents()} targets`)
+        .action(async () => {
+        const rootOptions = getRootOptions(program);
+        const env = resolveEnv();
+        await runSyncCommand(env);
+        if (requestedOutputRootWasUsed(rootOptions)) {
+            runtime.logInfo(`Generated output written to ${env.context.outputRoot}`);
+        }
+    });
+    addSkillsCommand({
+        program,
+        commandName: `${executableName} skills`,
+        resolveEnv,
+    });
+    return program;
+}
+/**
+ * Parses argv and runs the matching command, returning the Commander program after completion.
+ */
+export async function runCLI(input) {
+    const { argv, ...options } = input;
+    const program = createCLI(options);
+    await program.parseAsync(argv, { from: 'user' });
+    return program;
+}

package/dest/commands/skills/add.d.ts

@@ -1,9 +1,10 @@
-import type { AgentsContext } from '../../lib/context.js';
+import type { CommandEnv } from '../../cli.js';
 /**
- * Imports one or more managed skills from a remote repository `skills/` directory into the local skills directory.
+ * Imports one or more managed skills from a remote repository into the local skills directory.
  */
-export declare function runSkillsAddCommand(context: AgentsContext, input: {
+export declare function runSkillsAddCommand(env: CommandEnv, input: {
     repo: string;
+    repoPath: string | undefined;
     skillNames: string[];
     asName: string | undefined;
     pin: boolean;

package/dest/commands/skills/add.js

@@ -1,5 +1,5 @@
 import fs from 'fs-extra';
-import { cloneRemoteRepo, computeDirectoryHashes, createImportedSkillRecord, ensureSkillsLockfile, ensureSkillsRoot, findManagedSkill, formatManagedSkillSummary, getManagedSkillDirectory, loadSkillsLockfile, normalizeRemoteRepo, replaceManagedSkillDirectory, resolveManagedSkillImportPath, resolveSkillSourceDir, saveSkillsLockfile, timestampNow, upsertManagedSkill, } from '../../lib/skills.js';
+import { cleanupRemoteRepoCheckout, cloneRemoteRepo, computeDirectoryHashes, createImportedSkillRecord, deriveSkillName, ensureSkillsLockfile, ensureSkillsRoot, findManagedSkill, formatManagedSkillSummary, getManagedSkillDirectory, loadSkillsLockfile, normalizeImportedSkillPath, normalizeRemoteRepo, replaceManagedSkillDirectory, resolveManagedSkillImportPath, resolveManagedSkillImportPathFromBase, resolveSkillSourceDirByPath, saveSkillsLockfile, timestampNow, upsertManagedSkill, } from '../../lib/skills.js';
 /**
  * Normalizes and de-duplicates requested skill names while preserving their input order.
  */
@@ -20,10 +20,37 @@ function normalizeRequestedSkillNames(skillNames) {
     return uniqueSkillNames;
 }
 /**
- * Imports one or more managed skills from a remote repository `skills/` directory into the local skills directory.
+ * Returns the resolved repository-relative import path for a single requested skill.
+ *
+ * @example
+ * // No base path — defaults to the repository `skills/` directory
+ * resolveRequestedImportPath({ basePath: undefined, requestedSkillName: 'my-skill' });
+ * // → 'skills/my-skill'
+ *
+ * @example
+ * // With a base path — skill is resolved relative to that directory
+ * resolveRequestedImportPath({ basePath: 'tools', requestedSkillName: 'my-skill' });
+ * // → 'tools/my-skill'
+ *
+ * @example
+ * // Base path of '.' — skill is resolved from the repository root
+ * resolveRequestedImportPath({ basePath: '.', requestedSkillName: 'my-skill' });
+ * // → 'my-skill'
  */
-export async function runSkillsAddCommand(context, input) {
+function resolveRequestedImportPath(input) {
+    const importPath = resolveManagedSkillImportPathFromBase({
+        basePath: input.basePath,
+        skillName: input.requestedSkillName,
+    });
+    return normalizeImportedSkillPath(importPath) ?? importPath;
+}
+/**
+ * Imports one or more managed skills from a remote repository into the local skills directory.
+ */
+export async function runSkillsAddCommand(env, input) {
+    const { context, runtime } = env;
     const repo = normalizeRemoteRepo(input.repo);
+    const normalizedBasePath = normalizeImportedSkillPath(input.repoPath);
     if (input.skillNames.length === 0) {
         throw new Error('At least one skill name must be provided with --skill');
     }
@@ -45,9 +72,14 @@ export async function runSkillsAddCommand(context, input) {
     const importedSkillSummaries = [];
     try {
         for (const requestedSkillName of requestedSkillNames) {
-            const skillName = input.asName ?? requestedSkillName;
-            const importedSkillPath = resolveManagedSkillImportPath({
-                skillName: requestedSkillName,
+            const importedSkillPath = resolveRequestedImportPath({
+                basePath: normalizedBasePath,
+                requestedSkillName,
+            });
+            const skillName = deriveSkillName({
+                repo,
+                skillPath: importedSkillPath,
+                explicitName: input.asName,
             });
             const existingManagedSkill = findManagedSkill(lockfile, {
                 name: skillName,
@@ -60,10 +92,10 @@ export async function runSkillsAddCommand(context, input) {
             if (await fs.pathExists(targetDir)) {
                 throw new Error(`A local skill directory already exists: ${targetDir}`);
             }
-            const sourceDir = await resolveSkillSourceDir({
+            const sourceDir = await resolveSkillSourceDirByPath({
                 checkoutDir: checkout.checkoutDir,
                 repo,
-                skillName: requestedSkillName,
+                skillPath: importedSkillPath,
             });
             await replaceManagedSkillDirectory({
                 targetDir,
@@ -87,15 +119,15 @@ export async function runSkillsAddCommand(context, input) {
         }
     }
     finally {
-        await checkout.cleanup();
+        await cleanupRemoteRepoCheckout(checkout);
     }
     for (const importedSkillSummary of importedSkillSummaries) {
-        console.log(`Imported ${importedSkillSummary}`);
+        runtime.logInfo(`Imported ${importedSkillSummary}`);
     }
     if (skippedSkillNames.length > 0) {
-        console.warn(`Skipped already-imported skills: ${skippedSkillNames.join(', ')}`);
+        runtime.logWarn(`Skipped already-imported skills: ${skippedSkillNames.join(', ')}`);
     }
     if (importedSkillSummaries.length === 0) {
-        console.log('No skills were imported.');
+        runtime.logInfo('No skills were imported.');
     }
 }