@gajae-code/coding-agent 0.16.4 → 0.16.6

package/src/extensibility/runtime-skill-discovery.ts

@@ -1,6 +1,11 @@
 import * as fs from "node:fs/promises";
 import * as path from "node:path";
-import { getTrustedHomeDir } from "@gajae-code/utils";
+import {
+	getAgentDir,
+	getAgentProfileAuthority,
+	getTrustedHomeDir,
+	normalizePathForComparison,
+} from "@gajae-code/utils";
 import { findRepoRoot } from "../capability/fs";
 import type { Skill as CapabilitySkill } from "../capability/skill";
 import type { SkillsSettings } from "../config/settings-schema";
@@ -8,8 +13,17 @@ import { resolveSkillScopeTrust } from "../config/skill-settings-defaults";
 import { scanClaudeProjectSkills, scanClaudeUserSkills } from "../discovery/claude";
 import { loadMarketplaceSkills } from "../discovery/claude-plugins";
 import { scanCodexProjectSkills, scanCodexUserSkills } from "../discovery/codex";
-import { compareSkillOrder, SOURCE_PATHS, scanSkillsFromDir } from "../discovery/helpers";
-import { CANONICAL_GJC_WORKFLOW_SKILLS } from "../skill-state/canonical-skills";
+import {
+	compareSkillOrder,
+	getAncestorDirs,
+	getUserSkillScanDirs,
+	SOURCE_PATHS,
+	scanSkillsFromDir,
+} from "../discovery/helpers";
+import {
+	getSkillFilesystemIdentity,
+	isCanonicalGjcWorkflowSkillFilesystemAlias,
+} from "../skill-state/canonical-skills";
 import { expandTilde } from "../tools/path-utils";
 import { loadSkills, type Skill } from "./skills";
 
@@ -41,6 +55,9 @@ export interface RuntimeSkillDiscoveryResult {
 export interface DiscoverRuntimeSkillsOptions {
 	cwd: string;
 	home?: string;
+	agentDir?: string;
+	/** Resolver-owned profile classification; unlike path comparison, this survives HOME refreshes. */
+	profileAuthority?: "default" | "custom";
 	query?: string;
 	limit?: number;
 	source?: RuntimeSkillDiscoverySource | "all";
@@ -54,8 +71,6 @@ function getRuntimeHome(): string {
 const DEFAULT_LIMIT = 20;
 const MAX_LIMIT = 50;
 const MAX_DIAGNOSTICS = 10;
-const BUILT_IN_SKILL_NAMES = new Set<string>(CANONICAL_GJC_WORKFLOW_SKILLS);
-
 function normalizeLimit(limit: number | undefined): number {
 	if (limit === undefined || !Number.isFinite(limit)) return DEFAULT_LIMIT;
 	return Math.max(1, Math.min(MAX_LIMIT, Math.trunc(limit)));
@@ -82,41 +97,19 @@ async function getProjectSkillDirs(
 ): Promise<{ scans: ProjectScanDir[]; repoRoot: string | null }> {
 	const scans: ProjectScanDir[] = [];
 	const repoRoot = await findRepoRoot(cwd);
-	const walkDirs = ancestorDirs(cwd, path.resolve(repoRoot ?? cwd), home);
-	for (const dir of walkDirs) {
+	const walkDirs = getAncestorDirs(cwd, path.resolve(repoRoot ?? cwd), home);
+	for (const { dir } of walkDirs) {
 		scans.push({ dir: path.join(dir, ".gjc", "skills"), label: "project .gjc/skills" });
 	}
 	return { scans, repoRoot };
 }
 
-/** Ancestor directories from `cwd` (inclusive) up to `stop` (inclusive), excluding `home`. */
-function ancestorDirs(cwd: string, stop: string, home: string): string[] {
-	const dirs: string[] = [];
-	let current = path.resolve(cwd);
-	const resolvedStop = path.resolve(stop);
-	const resolvedHome = path.resolve(home);
-	while (true) {
-		if (current !== resolvedHome) {
-			dirs.push(current);
-		}
-		if (current === resolvedStop) break;
-		const parent = path.dirname(current);
-		if (parent === current) break;
-		current = parent;
-	}
-	return dirs;
+function getUserSkillDirs(home: string, agentDir = getAgentDir(), profileAuthority?: "default" | "custom"): string[] {
+	return getUserSkillScanDirs(home, agentDir, profileAuthority);
 }
 
-function getUserSkillDirs(home: string): string[] {
-	const canonicalUserDir = SOURCE_PATHS.native.userAgent;
-	const configuredLegacyDir = SOURCE_PATHS.native.userBase;
-	return [
-		...new Set([
-			path.join(home, canonicalUserDir, "skills"),
-			path.join(home, configuredLegacyDir, "skills"),
-			path.join(home, ".gjc", "skills"),
-		]),
-	];
+function resolveRuntimeAgentDir(home: string, agentDir: string | undefined, homeWasInjected: boolean): string {
+	return agentDir ?? (homeWasInjected ? path.join(home, SOURCE_PATHS.native.userAgent) : getAgentDir());
 }
 
 /**
@@ -197,7 +190,7 @@ interface ScanJobResult {
 }
 
 function isAllowedByPolicy(skill: CapabilitySkill, policy: SkillsSettings | undefined, diagnostics: string[]): boolean {
-	if (BUILT_IN_SKILL_NAMES.has(skill.name)) {
+	if (isCanonicalGjcWorkflowSkillFilesystemAlias(skill.name)) {
 		pushDiagnostic(
 			diagnostics,
 			`skill "${skill.name}" is a bundled GJC workflow skill and always resolves to the bundled definition; the filesystem copy at ${skill.path} is shadowed`,
@@ -270,9 +263,11 @@ async function scanProjectOrUserDir(
 	label: string,
 	source: RuntimeSkillDiscoverySource,
 	providerPriority: number,
+	authorityRoot?: string,
 ): Promise<ScanJobResult> {
 	const result = await scanSkillsFromDir(ctx, {
 		dir,
+		authorityRoot,
 		providerId: "runtime",
 		level,
 		requireDescription: true,
@@ -287,6 +282,7 @@ async function scanProjectOrUserDir(
 interface ConventionImportScan {
 	host: "Claude Code" | "Codex";
 	dir: string;
+	scope: RuntimeSkillDiscoverySource;
 	skills: CapabilitySkill[];
 }
 
@@ -309,20 +305,20 @@ async function collectConventionImportCandidates(
 	if ((source === "all" || source === "project") && sourceEnabled("project", policy)) {
 		jobs.push(
 			scanClaudeProjectSkills(ctx).then(result => {
-				scans.push({ host: "Claude Code", dir: ".claude/skills", skills: result.items });
+				scans.push({ host: "Claude Code", dir: ".claude/skills", scope: "project", skills: result.items });
 			}),
 			scanCodexProjectSkills(ctx).then(result => {
-				scans.push({ host: "Codex", dir: ".codex/skills", skills: result.items });
+				scans.push({ host: "Codex", dir: ".codex/skills", scope: "project", skills: result.items });
 			}),
 		);
 	}
 	if ((source === "all" || source === "user") && sourceEnabled("user", policy)) {
 		jobs.push(
 			scanClaudeUserSkills(ctx).then(result => {
-				scans.push({ host: "Claude Code", dir: "~/.claude/skills", skills: result.items });
+				scans.push({ host: "Claude Code", dir: "~/.claude/skills", scope: "user", skills: result.items });
 			}),
 			scanCodexUserSkills(ctx).then(result => {
-				scans.push({ host: "Codex", dir: "~/.codex/skills", skills: result.items });
+				scans.push({ host: "Codex", dir: "~/.codex/skills", scope: "user", skills: result.items });
 			}),
 		);
 	}
@@ -336,9 +332,15 @@ function reportConventionImportCandidates(
 	seenNames: Set<string>,
 	diagnostics: string[],
 ): void {
-	for (const scan of scans.sort((a, b) => a.host.localeCompare(b.host) || a.dir.localeCompare(b.dir))) {
+	// Project scope is reported first: the bounded diagnostic budget must not be
+	// spent on a populated user-home convention directory (hundreds of skills is
+	// ordinary) before a project convention skill is ever named.
+	const scopeRank = (scan: ConventionImportScan) => (scan.scope === "project" ? 0 : 1);
+	for (const scan of scans.sort(
+		(a, b) => scopeRank(a) - scopeRank(b) || a.host.localeCompare(b.host) || a.dir.localeCompare(b.dir),
+	)) {
 		for (const skill of scan.skills) {
-			const normalizedName = skill.name.toLowerCase();
+			const normalizedName = getSkillFilesystemIdentity(skill.name);
 			if (seenNames.has(normalizedName)) continue;
 			seenNames.add(normalizedName);
 			pushDiagnostic(
@@ -380,10 +382,20 @@ export function describeDisabledSkillScopes(
 export async function discoverRuntimeSkills(
 	options: DiscoverRuntimeSkillsOptions,
 ): Promise<RuntimeSkillDiscoveryResult> {
+	const hasExplicitHome = options.home !== undefined;
 	const home = options.home ?? getRuntimeHome();
 	const source = options.source ?? "all";
 	const policy = options.policy;
 	const diagnostics: string[] = [];
+	const agentDir = resolveRuntimeAgentDir(home, options.agentDir, hasExplicitHome);
+	const profileAuthority =
+		options.profileAuthority ??
+		(!hasExplicitHome
+			? options.agentDir !== undefined &&
+				normalizePathForComparison(options.agentDir) !== normalizePathForComparison(getAgentDir())
+				? "custom"
+				: getAgentProfileAuthority()
+			: undefined);
 	const scanJobs: Array<Promise<ScanJobResult>> = [];
 	const projectDirs = await getProjectSkillDirs(options.cwd, home);
 	const projectContext = { cwd: options.cwd, home, repoRoot: projectDirs.repoRoot };
@@ -393,9 +405,17 @@ export async function discoverRuntimeSkills(
 		}
 	}
 	if ((source === "all" || source === "user") && sourceEnabled("user", policy)) {
-		for (const dir of getUserSkillDirs(home)) {
+		for (const dir of getUserSkillDirs(home, agentDir, profileAuthority)) {
 			scanJobs.push(
-				scanProjectOrUserDir({ cwd: options.cwd, home, repoRoot: home }, dir, "user", `user ${dir}`, "user", 100),
+				scanProjectOrUserDir(
+					{ cwd: options.cwd, home, repoRoot: home },
+					dir,
+					"user",
+					`user ${dir}`,
+					"user",
+					100,
+					path.resolve(dir) === path.resolve(agentDir, "skills") ? agentDir : undefined,
+				),
 			);
 		}
 	}
@@ -461,7 +481,7 @@ export async function discoverRuntimeSkills(
 	for (const item of orderedItems) {
 		if (!isAllowedByPolicy(item.skill, policy, diagnostics)) continue;
 		const realPath = await realPathOrSelf(item.skill.path);
-		const normalizedName = item.skill.name.toLowerCase();
+		const normalizedName = getSkillFilesystemIdentity(item.skill.name);
 		if (seenPaths.has(realPath) || seenNames.has(normalizedName)) {
 			pushDiagnostic(
 				diagnostics,
@@ -497,16 +517,29 @@ export async function findRuntimeSkillByName(
 	cwd: string,
 	name: string,
 	policy?: SkillsSettings,
-	home = getRuntimeHome(),
+	home?: string,
+	agentDir?: string,
+	profileAuthority?: "default" | "custom",
 ): Promise<Skill | undefined> {
 	const normalized = name.trim();
 	if (!normalized) return undefined;
-	if (BUILT_IN_SKILL_NAMES.has(normalized)) return undefined;
+	if (isCanonicalGjcWorkflowSkillFilesystemAlias(normalized)) return undefined;
+	const hasExplicitHome = home !== undefined;
+	const resolvedHome = home ?? getRuntimeHome();
+	const resolvedAgentDir = resolveRuntimeAgentDir(resolvedHome, agentDir, hasExplicitHome);
+	const resolvedProfileAuthority =
+		profileAuthority ??
+		(!hasExplicitHome
+			? agentDir !== undefined && normalizePathForComparison(agentDir) !== normalizePathForComparison(getAgentDir())
+				? "custom"
+				: getAgentProfileAuthority()
+			: undefined);
 	const loaded = await loadSkills({
 		...policy,
 		cwd,
-		home,
-		agentDir: path.join(home, SOURCE_PATHS.native.userAgent),
+		home: resolvedHome,
+		agentDir: resolvedAgentDir,
+		profileAuthority: resolvedProfileAuthority,
 	});
 	return loaded.skills.find(skill => skill.name === normalized);
 }

package/src/extensibility/skill-management.ts

@@ -12,16 +12,32 @@
  * writing a skill file into a scope, and per-skill enable/disable. The import
  * preview/apply transaction and the UI itself are owned by #4291.
  */
+import * as nodeFs from "node:fs";
 import * as fs from "node:fs/promises";
 import * as path from "node:path";
-import { getTrustedHomeDir, parseFrontmatter } from "@gajae-code/utils";
+import {
+	getAgentDir,
+	getAgentProfileAuthority,
+	getTrustedHomeDir,
+	normalizePathForComparison,
+	parseFrontmatter,
+} from "@gajae-code/utils";
 import { findRepoRoot } from "../capability/fs";
 import type { Skill as CapabilitySkill } from "../capability/skill";
 import { resolveSkillScopeTrust } from "../config/skill-settings-defaults";
 import { scanClaudeProjectSkills, scanClaudeUserSkills } from "../discovery/claude";
 import { scanCodexProjectSkills, scanCodexUserSkills } from "../discovery/codex";
-import { compareSkillOrder, SOURCE_PATHS, scanSkillsFromDir } from "../discovery/helpers";
-import { CANONICAL_GJC_WORKFLOW_SKILLS } from "../skill-state/canonical-skills";
+import {
+	compareSkillOrder,
+	getAncestorDirs,
+	getUserSkillScanDirs,
+	resolveUserAgentDir,
+	scanSkillsFromDir,
+} from "../discovery/helpers";
+import {
+	CANONICAL_GJC_WORKFLOW_SKILLS,
+	isCanonicalGjcWorkflowSkillFilesystemAlias,
+} from "../skill-state/canonical-skills";
 export type SkillScope = "project" | "user";
 export type ConventionSkillHost = "claude" | "codex";
 
@@ -61,6 +77,7 @@ export interface ConventionSkillImportSource {
 export interface WriteNativeSkillInput {
 	cwd: string;
 	home?: string;
+	agentDir?: string;
 	scope: SkillScope;
 	name: string;
 	content: string;
@@ -93,28 +110,127 @@ export class SkillFrontmatterError extends Error {
 	}
 }
 
-const BUILT_IN_SKILL_NAMES = new Set<string>(CANONICAL_GJC_WORKFLOW_SKILLS);
+function isProtectedSkillName(name: string): boolean {
+	return isCanonicalGjcWorkflowSkillFilesystemAlias(name);
+}
 
-function getRuntimeHome(): string {
-	return getTrustedHomeDir();
+function assertSafeSkillName(name: string): void {
+	if (
+		name === "." ||
+		name === ".." ||
+		/[. ]$/u.test(name) ||
+		name.includes("/") ||
+		name.includes("\\") ||
+		name.includes("\0") ||
+		path.basename(name) !== name
+	) {
+		throw new SkillFrontmatterError(`skill name must be a single path segment: ${name}`);
+	}
+}
+
+function isPathWithin(root: string, candidate: string): boolean {
+	const relative = path.relative(root, candidate);
+	return relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative));
+}
+
+async function ensureSafeDescendantDirectory(root: string, segments: readonly string[]): Promise<string> {
+	try {
+		const rootStat = await fs.lstat(root);
+		if (rootStat.isSymbolicLink() || !rootStat.isDirectory()) {
+			throw new SkillFrontmatterError(`skill authority root is not a safe directory: ${root}`);
+		}
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+		await fs.mkdir(root, { recursive: true });
+		const rootStat = await fs.lstat(root);
+		if (rootStat.isSymbolicLink() || !rootStat.isDirectory()) {
+			throw new SkillFrontmatterError(`skill authority root is not a safe directory: ${root}`);
+		}
+	}
+	const realRoot = await fs.realpath(root);
+	let current = root;
+	for (const segment of segments) {
+		current = path.join(current, segment);
+		try {
+			const stat = await fs.lstat(current);
+			if (stat.isSymbolicLink() || !stat.isDirectory()) {
+				throw new SkillFrontmatterError(`skill destination is not a safe directory: ${current}`);
+			}
+		} catch (error) {
+			if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+			try {
+				await fs.mkdir(current);
+			} catch (mkdirError) {
+				if ((mkdirError as NodeJS.ErrnoException).code !== "EEXIST") throw mkdirError;
+				const stat = await fs.lstat(current);
+				if (stat.isSymbolicLink() || !stat.isDirectory()) {
+					throw new SkillFrontmatterError(`skill destination is not a safe directory: ${current}`);
+				}
+			}
+		}
+		const realCurrent = await fs.realpath(current);
+		if (!isPathWithin(realRoot, realCurrent)) {
+			throw new SkillFrontmatterError(`skill destination escapes its scope root: ${current}`);
+		}
+	}
+	return current;
 }
 
-/** Ancestor directories from `cwd` (inclusive) up to `stop` (inclusive), excluding `home`. */
-function ancestorDirs(cwd: string, stop: string, home: string): string[] {
-	const dirs: string[] = [];
-	let current = path.resolve(cwd);
-	const resolvedStop = path.resolve(stop);
-	const resolvedHome = path.resolve(home);
-	while (true) {
-		if (current !== resolvedHome) {
-			dirs.push(current);
+async function writeSkillFileSafely(skillDir: string, scopeRoot: string, content: string): Promise<string> {
+	const [canonicalSkillDir, canonicalScopeRoot] = await Promise.all([fs.realpath(skillDir), fs.realpath(scopeRoot)]);
+	if (!isPathWithin(canonicalScopeRoot, canonicalSkillDir)) {
+		throw new SkillFrontmatterError(`skill destination escapes its scope root: ${skillDir}`);
+	}
+	const filePath = path.join(skillDir, "SKILL.md");
+	let destinationExists = false;
+	try {
+		const destination = await fs.lstat(filePath);
+		if (destination.isSymbolicLink() || !destination.isFile()) {
+			throw new SkillFrontmatterError(`skill destination is not a safe file: ${filePath}`);
 		}
-		if (current === resolvedStop) break;
-		const parent = path.dirname(current);
-		if (parent === current) break;
-		current = parent;
+		destinationExists = true;
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+	}
+	const noFollowFlags =
+		process.platform === "win32" ? 0 : (nodeFs.constants.O_NOFOLLOW ?? 0) | (nodeFs.constants.O_NONBLOCK ?? 0);
+	const flags = destinationExists
+		? nodeFs.constants.O_WRONLY | noFollowFlags
+		: nodeFs.constants.O_WRONLY | nodeFs.constants.O_CREAT | nodeFs.constants.O_EXCL | noFollowFlags;
+	let handle: fs.FileHandle;
+	try {
+		handle = await fs.open(filePath, flags, 0o600);
+	} catch (error) {
+		throw new SkillFrontmatterError(`skill destination is not a safe file: ${filePath} (${String(error)})`);
 	}
-	return dirs;
+	try {
+		const [opened, observed, currentSkillDir] = await Promise.all([
+			handle.stat({ bigint: true }),
+			fs.lstat(filePath, { bigint: true }),
+			fs.realpath(skillDir),
+		]);
+		if (
+			!opened.isFile() ||
+			opened.nlink !== 1n ||
+			observed.isSymbolicLink() ||
+			!observed.isFile() ||
+			opened.dev !== observed.dev ||
+			opened.ino !== observed.ino ||
+			normalizePathForComparison(currentSkillDir) !== normalizePathForComparison(canonicalSkillDir) ||
+			!isPathWithin(canonicalScopeRoot, currentSkillDir)
+		) {
+			throw new SkillFrontmatterError(`skill destination changed during write: ${filePath}`);
+		}
+		await handle.truncate(0);
+		await handle.writeFile(content);
+	} finally {
+		await handle.close();
+	}
+	return filePath;
+}
+
+function getRuntimeHome(): string {
+	return getTrustedHomeDir();
 }
 
 /**
@@ -126,34 +242,42 @@ export async function getProjectSkillDirs(
 	home: string,
 ): Promise<{ dirs: string[]; repoRoot: string | null }> {
 	const repoRoot = await findRepoRoot(cwd);
-	const walkDirs = ancestorDirs(cwd, path.resolve(repoRoot ?? cwd), home);
-	return { dirs: walkDirs.map(dir => path.join(dir, ".gjc", "skills")), repoRoot };
+	const walkDirs = getAncestorDirs(cwd, path.resolve(repoRoot ?? cwd), home);
+	return { dirs: walkDirs.map(({ dir }) => path.join(dir, ".gjc", "skills")), repoRoot };
 }
 
 /** Canonical user skill directories in precedence order (same resolution as runtime discovery). */
-export function getUserSkillDirs(home: string): string[] {
-	return [
-		...new Set([
-			path.join(home, SOURCE_PATHS.native.userAgent, "skills"),
-			path.join(home, SOURCE_PATHS.native.userBase, "skills"),
-			path.join(home, ".gjc", "skills"),
-		]),
-	];
+export function getUserSkillDirs(home: string, agentDir?: string, profileAuthority?: "default" | "custom"): string[] {
+	return getUserSkillScanDirs(home, agentDir, profileAuthority);
 }
 
 /**
  * The canonical directory a write targets for a scope: the repo root (or `cwd`)
- * `.gjc/skills` for project scope, the canonical `<config>/agent/skills` user
- * root for user scope (honoring `GJC_CONFIG_DIR` / `PI_CONFIG_DIR`).
+ * `.gjc/skills` for project scope, the agent directory's `skills` root for user
+ * scope — the same directory every reader scans first (`gjc config path` prints
+ * it; `--agent-dir` / `GJC_CODING_AGENT_DIR` / `setAgentDir()` move it).
  */
 export async function resolveNativeSkillScopeDir(
 	cwd: string,
 	scope: SkillScope,
-	home = getRuntimeHome(),
+	_home?: string,
+	agentDir?: string,
 ): Promise<string> {
-	if (scope === "user") return path.join(home, SOURCE_PATHS.native.userAgent, "skills");
+	const home = _home ?? getRuntimeHome();
+	if (scope === "user") {
+		const resolvedAgentDir = agentDir ?? (_home === undefined ? getAgentDir() : resolveUserAgentDir(home));
+		return path.join(path.resolve(resolvedAgentDir), "skills");
+	}
 	const repoRoot = await findRepoRoot(cwd);
-	return path.join(repoRoot ?? path.resolve(cwd), ".gjc", "skills");
+	const resolvedCwd = path.resolve(cwd);
+	const projectRoot = repoRoot ?? resolvedCwd;
+	if (normalizePathForComparison(projectRoot) === normalizePathForComparison(home)) {
+		if (normalizePathForComparison(resolvedCwd) === normalizePathForComparison(home)) {
+			throw new SkillFrontmatterError("project skill scope is unavailable at the user home boundary");
+		}
+		return path.join(resolvedCwd, ".gjc", "skills");
+	}
+	return path.join(projectRoot, ".gjc", "skills");
 }
 
 function matchesPattern(name: string, patterns: string[] | undefined): boolean {
@@ -174,14 +298,31 @@ function isDisabledByExtension(name: string, disabledExtensions: string[] | unde
 export async function listNativeSkillsForManagement(options: {
 	cwd: string;
 	home?: string;
+	agentDir?: string;
+	/** Resolver-owned profile classification; unlike path comparison, this survives HOME refreshes. */
+	profileAuthority?: "default" | "custom";
 	policy?: SkillManagementPolicy;
 }): Promise<ManagedSkillRecord[]> {
+	const homeWasInjected = options.home !== undefined;
 	const home = options.home ?? getRuntimeHome();
+	const agentDir = options.agentDir ?? (homeWasInjected ? resolveUserAgentDir(home) : getAgentDir());
+	const profileAuthority =
+		options.profileAuthority ??
+		(options.agentDir !== undefined
+			? normalizePathForComparison(options.agentDir) ===
+				normalizePathForComparison(homeWasInjected ? resolveUserAgentDir(home) : getAgentDir())
+				? homeWasInjected
+					? "default"
+					: getAgentProfileAuthority()
+				: "custom"
+			: !homeWasInjected
+				? getAgentProfileAuthority()
+				: undefined);
 	const policy = options.policy;
 	const projectTrusted = resolveSkillScopeTrust(policy ?? {}, "project");
 	const userTrusted = resolveSkillScopeTrust(policy ?? {}, "user");
 
-	const scanJobs: Array<Promise<{ dir: string; items: CapabilitySkill[] }>> = [];
+	const scanJobs: Array<Promise<{ dir: string; scope: SkillScope; items: CapabilitySkill[] }>> = [];
 	const projectDirs = await getProjectSkillDirs(options.cwd, home);
 	if (projectTrusted) {
 		for (const dir of projectDirs.dirs) {
@@ -189,17 +330,23 @@ export async function listNativeSkillsForManagement(options: {
 				scanSkillsFromDir(
 					{ cwd: options.cwd, home, repoRoot: projectDirs.repoRoot },
 					{ dir, providerId: "runtime", level: "project", requireDescription: true },
-				).then(result => ({ dir, items: result.items })),
+				).then(result => ({ dir, scope: "project" as const, items: result.items })),
 			);
 		}
 	}
 	if (userTrusted) {
-		for (const dir of getUserSkillDirs(home)) {
+		for (const dir of getUserSkillScanDirs(home, agentDir, profileAuthority)) {
 			scanJobs.push(
 				scanSkillsFromDir(
 					{ cwd: options.cwd, home, repoRoot: home },
-					{ dir, providerId: "runtime", level: "user", requireDescription: true },
-				).then(result => ({ dir, items: result.items })),
+					{
+						dir,
+						authorityRoot: path.resolve(dir) === path.resolve(agentDir, "skills") ? agentDir : undefined,
+						providerId: "runtime",
+						level: "user",
+						requireDescription: true,
+					},
+				).then(result => ({ dir, scope: "user" as const, items: result.items })),
 			);
 		}
 	}
@@ -208,8 +355,7 @@ export async function listNativeSkillsForManagement(options: {
 	const seenNames = new Set<string>();
 	const seenPaths = new Set<string>();
 
-	for (const { dir, items } of await Promise.all(scanJobs)) {
-		const scope: SkillScope = path.resolve(dir).startsWith(`${path.resolve(home)}${path.sep}`) ? "user" : "project";
+	for (const { dir, scope, items } of await Promise.all(scanJobs)) {
 		const source = scope === "project" ? "project .gjc/skills" : `user ${dir}`;
 		for (const skill of items) {
 			const realPath = await safeRealpath(skill.path);
@@ -217,7 +363,7 @@ export async function listNativeSkillsForManagement(options: {
 
 			let disabledReason: SkillDisabledReason | undefined;
 			let enabled = true;
-			if (BUILT_IN_SKILL_NAMES.has(skill.name)) {
+			if (isProtectedSkillName(skill.name)) {
 				enabled = false;
 				disabledReason = "protected";
 			} else if (!(scope === "project" ? projectTrusted : userTrusted)) {
@@ -272,19 +418,21 @@ export async function writeNativeSkill(input: WriteNativeSkillInput): Promise<Wr
 
 	const effectiveName =
 		typeof frontmatter.name === "string" && frontmatter.name.trim() ? frontmatter.name.trim() : name;
-	if (BUILT_IN_SKILL_NAMES.has(effectiveName)) throw new SkillNameProtectedError(effectiveName);
-
-	const directory = await resolveNativeSkillScopeDir(input.cwd, input.scope, input.home ?? getRuntimeHome());
-	const skillDir = path.join(directory, effectiveName);
-	await fs.mkdir(skillDir, { recursive: true });
-	const filePath = path.join(skillDir, "SKILL.md");
-	await Bun.write(filePath, `${input.content.trimEnd()}\n`);
+	if (isProtectedSkillName(effectiveName)) throw new SkillNameProtectedError(effectiveName);
+	assertSafeSkillName(effectiveName);
+
+	const directory = await resolveNativeSkillScopeDir(input.cwd, input.scope, input.home, input.agentDir);
+	const scopeRoot = input.scope === "user" ? path.dirname(directory) : path.dirname(path.dirname(directory));
+	const relativeDirectory = path.relative(scopeRoot, directory);
+	const directorySegments = relativeDirectory.split(path.sep).filter(Boolean);
+	const skillDir = await ensureSafeDescendantDirectory(scopeRoot, [...directorySegments, effectiveName]);
+	const filePath = await writeSkillFileSafely(skillDir, scopeRoot, `${input.content.trimEnd()}\n`);
 	return { name: effectiveName, scope: input.scope, directory, path: filePath };
 }
 
 /** Whether a skill is enabled under the current policy (disabledExtensions/ignored/scope trust). */
 export function isNativeSkillEnabled(name: string, policy: SkillManagementPolicy | undefined): boolean {
-	if (BUILT_IN_SKILL_NAMES.has(name)) return true;
+	if (isProtectedSkillName(name)) return true;
 	if (isDisabledByExtension(name, policy?.disabledExtensions)) return false;
 	if (matchesPattern(name, policy?.ignoredSkills)) return false;
 	if (policy?.includeSkills?.length && !matchesPattern(name, policy.includeSkills)) return false;
@@ -299,7 +447,7 @@ export function isNativeSkillEnabled(name: string, policy: SkillManagementPolicy
 export function setNativeSkillEnabled(name: string, enabled: boolean, disabledExtensions: string[]): string[] {
 	const id = `skill:${name}`;
 	const next = new Set(disabledExtensions);
-	if (BUILT_IN_SKILL_NAMES.has(name)) return [...next];
+	if (isProtectedSkillName(name)) return [...next];
 	if (enabled) {
 		next.delete(id);
 	} else {