Beautiful, AI-native markdown IDE and LLM wiki
TypeScript 2nd-brainagent-skillsclaudecodexcompany-braindocsknowledge-knowledge-baseknowledge-managementllmllm-wikillm-wiki-karpathymarkdownmarkdown-editormdmdxnotespkmsecond-brainskills
import { type Dirent, existsSync, lstatSync, readdirSync, readFileSync, statSync } from 'node:fs';
import { basename, dirname, isAbsolute, join, normalize, relative, sep } from 'node:path';
import {
applyPatchToFm,
containsXmlTag,
detectFmRegion,
type FmEditError,
SKILL_NAME_REGEX,
type SkillAuthoringWarningCode,
type SkillFrontmatter,
skillFilePathSegments,
} from '@inkeep/open-knowledge-core';
import { ATOMIC_TEMP_INFIX, atomicTempPath } from '@inkeep/open-knowledge-core/server';
import { stringify as stringifyYaml } from 'yaml';
import { isSkillBundlePathWithheld } from '../content-filter.ts';
import { resolveExistingNativeAncestor, resolveNativePath } from '../directory-root.ts';
/*
* STOP: every disk write in this module goes through `fs-traced.ts` so it
* carries an `fs.*` span. A bare `node:fs` call here drops the span.
*/
import {
tracedMkdirSync,
tracedRenameSync,
tracedRmdirSync,
tracedRmSync,
tracedUnlinkSync,
tracedWriteFileSync,
} from '../fs-traced.ts';
import { errnoCode } from '../http/handler-utils.ts';
import { symlinkReachesPrivateState } from '../incoming-symlink-guard.ts';
import { isWithinDir } from '../path-utils.ts';
const NAME_MAX = 64;
const DESCRIPTION_MAX = 1024;
const DISCOURAGED_NAME_WORDS = ['anthropic', 'claude'];
const BODY_SOFT_MAX_LINES = 500;
const SKILL_FILE = 'SKILL.md';
type SkillWriteResult =
| {
ok: true;
path: string;
created: boolean;
warnings: string[];
warningCodes: SkillAuthoringWarningCode[];
}
| { ok: false; error: { code: string; message: string; cause?: unknown } };
export type SkillContentResult =
| {
ok: true;
content: string;
warnings: string[];
warningCodes: SkillAuthoringWarningCode[];
}
| { ok: false; error: { code: string; message: string } };
type SkillDeleteResult =
| { ok: true; path: string; existed: boolean }
| { ok: false; error: { code: string; message: string } };
type SkillMoveResult =
| { ok: true; fromPath: string; toPath: string; committed: boolean }
| { ok: false; error: { code: string; message: string } };
interface WriteSkillInput {
boundary: string;
skillsRoot: string;
name: string;
body: string;
frontmatter: SkillFrontmatter;
}
interface DeleteSkillInput {
skillsRoot: string;
name: string;
}
interface MoveSkillInput {
skillsRoot: string;
fromName: string;
toName: string;
relocate: (fromAbs: string, toAbs: string) => Promise<boolean>;
}
export function composeSkillContent(input: {
name: string;
body: string;
frontmatter: SkillFrontmatter;
}): SkillContentResult {
const nameCheck = validateName(input.name);
if (!nameCheck.ok) return { ok: false, error: nameCheck.error };
const fmCheck = validateFrontmatter(input.frontmatter, input.name);
if (!fmCheck.ok) return { ok: false, error: fmCheck.error };
const fmYaml = serializeFrontmatter(input.frontmatter);
const content = `---\n${fmYaml}---\n${input.body}`;
const warnings: string[] = [];
const warningCodes: SkillAuthoringWarningCode[] = [];
const discouraged = DISCOURAGED_NAME_WORDS.filter((w) => input.name.includes(w));
if (discouraged.length > 0) {
warnings.push(
`Skill name contains ${discouraged.map((w) => `"${w}"`).join(', ')} — Anthropic's authoring guidance discourages vendor words in skill names.`,
);
warningCodes.push('skill-name-vendor-word');
}
const lineCount = input.body.split('\n').length;
if (lineCount > BODY_SOFT_MAX_LINES) {
warnings.push(
`SKILL.md body is ${lineCount} lines — keep it under ${BODY_SOFT_MAX_LINES} for performance (every line is a recurring token cost). Move detail into one-level-deep references/.`,
);
warningCodes.push('skill-body-too-long');
}
return { ok: true, content, warnings, warningCodes };
}
function sweepStaleTmpSiblings(targetPath: string): void {
const dir = dirname(targetPath);
const prefix = `${basename(targetPath)}${ATOMIC_TEMP_INFIX}`;
try {
for (const entry of readdirSync(dir)) {
if (entry.startsWith(prefix)) tracedUnlinkSync(join(dir, entry));
}
} catch {}
}
export function applySkillWrite(input: WriteSkillInput): SkillWriteResult {
const base = validateBase(input.skillsRoot);
if (!base.ok) return { ok: false, error: base.error };
const composed = composeSkillContent({
name: input.name,
body: input.body,
frontmatter: input.frontmatter,
});
if (!composed.ok) return { ok: false, error: composed.error };
const { content, warnings, warningCodes } = composed;
const { skillDir, filePath } = skillPaths(input.skillsRoot, input.name);
const pathCheck = validateSkillMutationPath(input.boundary, skillDir, filePath);
if (!pathCheck.ok) return pathCheck;
try {
tracedMkdirSync(skillDir, { recursive: true });
} catch (err) {
return {
ok: false,
error: {
code: 'WRITE_ERROR',
message: `Failed to create skill directory at ${relPathOf(input.skillsRoot, skillDir)}: ${(err as Error).message}`,
},
};
}
const created = !existsSync(filePath);
sweepStaleTmpSiblings(filePath);
const tmpPath = atomicTempPath(filePath);
try {
tracedWriteFileSync(tmpPath, content, { encoding: 'utf-8', flag: 'wx' });
tracedRenameSync(tmpPath, filePath);
} catch (err) {
try {
tracedUnlinkSync(tmpPath);
} catch {}
return {
ok: false,
error: {
code: 'WRITE_ERROR',
message: `Failed to write skill at ${relPathOf(input.skillsRoot, filePath)}: ${(err as Error).message}`,
},
};
}
return {
ok: true,
path: relPathOf(input.skillsRoot, filePath),
created,
warnings,
warningCodes,
};
}
export type SkillDirNameSyncResult =
| { ok: true }
| { ok: false; stage: 'read'; cause: unknown }
| { ok: false; stage: 'patch'; error: FmEditError }
| { ok: false; stage: 'write'; cause: unknown };
export function applySkillDirNameSync(input: {
skillDir: string;
toName: string;
skillMd?: string;
}): SkillDirNameSyncResult {
const filePath = join(input.skillDir, SKILL_FILE);
let raw: string;
if (input.skillMd !== undefined) {
raw = input.skillMd;
} else {
try {
raw = readFileSync(filePath, 'utf-8');
} catch (cause) {
return { ok: false, stage: 'read', cause };
}
}
const { fenced, body } = detectFmRegion(raw);
// presence-exempt: no CRDT write, no agent identity
const renamed = applyPatchToFm(fenced, { name: input.toName });
if (!renamed.ok) return { ok: false, stage: 'patch', error: renamed.error };
sweepStaleTmpSiblings(filePath);
const tmpPath = atomicTempPath(filePath);
try {
tracedWriteFileSync(tmpPath, `${renamed.nextFenced}${body}`, 'utf-8');
tracedRenameSync(tmpPath, filePath);
} catch (cause) {
try {
tracedUnlinkSync(tmpPath);
} catch {}
return { ok: false, stage: 'write', cause };
}
return { ok: true };
}
export const BUNDLE_FILE_MAX_BYTES = 256 * 1024;
export const BUNDLE_MAX_FILES = 50;
export interface BundleFileWriteLimits {
readonly maxFileBytes: number;
readonly maxFiles: number;
}
interface BundleFileInput {
boundary: string;
skillsRoot: string;
name: string;
relPath: string;
}
type BundleFileWriteResult =
| { ok: true; path: string; created: boolean }
| { ok: false; error: { code: string; message: string } };
type BundleFileDeleteResult =
| { ok: true; path: string; existed: boolean }
| { ok: false; error: { code: string; message: string } };
export function skillMutationErrorStatus(code: string): 400 | 500 {
return code === 'SKILL_PATH_CHECK_FAILED' ? 500 : 400;
}
export function validateSkillMutationPath(
boundary: string,
skillDir: string,
abs: string,
): { ok: true } | { ok: false; error: { code: string; message: string; cause?: unknown } } {
if (!isAbsolute(boundary) || !isWithinDir(skillDir, boundary) || !isWithinDir(abs, skillDir)) {
return {
ok: false,
error: {
code: 'SKILL_PATH_OUTSIDE_HOME',
message: `Skill ${relative(boundary, skillDir)} must stay inside its project or home directory.`,
},
};
}
let component = skillDir;
let operation = 'resolve the project or home directory';
try {
const realBoundary = resolveNativePath(boundary);
operation = `resolve skill directory ${relative(boundary, skillDir)}`;
const { ancestor, missingSegments } = resolveExistingNativeAncestor(skillDir);
const realSkillDir = join(ancestor, ...missingSegments);
const privateState = symlinkReachesPrivateState(
relative(boundary, skillDir).split(sep).join('/'),
relative(realBoundary, realSkillDir).split(sep).join('/'),
);
if (!isWithinDir(realSkillDir, realBoundary) || privateState) {
return {
ok: false,
error: {
code: privateState ? 'SKILL_PATH_PRIVATE_STATE' : 'SKILL_PATH_OUTSIDE_HOME',
message: `Skill ${relative(boundary, skillDir)} resolves ${privateState ? 'into private repository state' : 'outside its project or home directory'}; replace the link with an authorized skill directory.`,
},
};
}
for (const segment of relative(skillDir, abs).split(sep)) {
component = join(component, segment);
operation = `inspect skill path ${relative(skillDir, component)}`;
const stat = lstatSync(component, { throwIfNoEntry: false });
if (stat === undefined) break;
if (stat.isSymbolicLink()) {
return {
ok: false,
error: {
code: 'SKILL_SYMLINK_REFUSED',
message: `Skill path ${relative(skillDir, component)} is a symlink; replace it with a real file or directory before changing it.`,
},
};
}
}
} catch (cause) {
return {
ok: false,
error: {
code: 'SKILL_PATH_CHECK_FAILED',
message: `Could not ${operation} (${errnoCode(cause) ?? 'unknown error'}).`,
cause,
},
};
}
return { ok: true };
}
function resolveBundleFileAbs(
skillDir: string,
relPath: string,
): { ok: true; abs: string } | { ok: false; error: { code: string; message: string } } {
if (typeof relPath !== 'string' || relPath.length === 0 || relPath.includes('\x00')) {
return { ok: false, error: { code: 'BAD_FILE_PATH', message: 'Invalid skill file path.' } };
}
const segments = skillFilePathSegments(relPath);
if (segments.length === 0 || segments.some((s) => s === '..')) {
return {
ok: false,
error: { code: 'BAD_FILE_PATH', message: `Invalid skill file path: ${relPath}` },
};
}
if (segments.length === 1 && segments[0] === SKILL_FILE) {
return {
ok: false,
error: {
code: 'BAD_FILE_PATH',
message: 'SKILL.md is written through the skill write path, not as a bundle file.',
},
};
}
const abs = join(skillDir, ...segments);
if (abs !== skillDir && !abs.startsWith(skillDir + sep)) {
return {
ok: false,
error: { code: 'BAD_FILE_PATH', message: `Skill file escapes the skill dir: ${relPath}` },
};
}
return { ok: true, abs };
}
export function countBundleFiles(skillDir: string): number {
let count = 0;
const walk = (dir: string, prefix: string): void => {
let entries: Dirent[];
try {
entries = readdirSync(dir, { withFileTypes: true });
} catch {
return;
}
for (const entry of entries) {
const rel = prefix === '' ? entry.name : `${prefix}/${entry.name}`;
if (isSkillBundlePathWithheld(rel)) continue;
if (entry.isDirectory()) walk(join(dir, entry.name), rel);
else if (entry.isFile() && !(dir === skillDir && entry.name === SKILL_FILE)) count++;
}
};
walk(skillDir, '');
return count;
}
export function applySkillBundleFileWrite(
input: BundleFileInput & {
content: string | null;
bytes?: Uint8Array;
limits?: BundleFileWriteLimits;
},
): BundleFileWriteResult {
const payload: string | Uint8Array = input.bytes ?? input.content ?? '';
const base = validateBase(input.skillsRoot);
if (!base.ok) return { ok: false, error: base.error };
const nameCheck = validateName(input.name);
if (!nameCheck.ok) return { ok: false, error: nameCheck.error };
const { skillDir, filePath: skillMd } = skillPaths(input.skillsRoot, input.name);
if (!existsSync(skillMd)) {
return {
ok: false,
error: {
code: 'SKILL_NOT_FOUND',
message: `No skill "${input.name}" — create it (write its SKILL.md) before adding bundle files.`,
},
};
}
const resolved = resolveBundleFileAbs(skillDir, input.relPath);
if (!resolved.ok) return { ok: false, error: resolved.error };
const { abs } = resolved;
const pathCheck = validateSkillMutationPath(input.boundary, skillDir, abs);
if (!pathCheck.ok) return pathCheck;
const byteLength =
typeof payload === 'string' ? Buffer.byteLength(payload, 'utf-8') : payload.length;
const maxFileBytes = input.limits?.maxFileBytes ?? BUNDLE_FILE_MAX_BYTES;
const maxFiles = input.limits?.maxFiles ?? BUNDLE_MAX_FILES;
if (byteLength > maxFileBytes) {
return {
ok: false,
error: {
code: 'FILE_TOO_LARGE',
message: `Skill file ${input.relPath} is ${byteLength} bytes — the per-file cap is ${maxFileBytes}.`,
},
};
}
const created = !existsSync(abs);
if (created && countBundleFiles(skillDir) >= maxFiles) {
return {
ok: false,
error: {
code: 'TOO_MANY_FILES',
message: `Skill "${input.name}" already holds ${maxFiles} bundle files (the cap) — delete one before adding another.`,
},
};
}
try {
tracedMkdirSync(join(abs, '..'), { recursive: true });
} catch (err) {
return {
ok: false,
error: {
code: 'WRITE_ERROR',
message: `Failed to create directory for ${input.relPath}: ${(err as Error).message}`,
},
};
}
sweepStaleTmpSiblings(abs);
const tmpPath = atomicTempPath(abs);
try {
tracedWriteFileSync(tmpPath, payload, { encoding: 'utf-8', flag: 'wx' });
tracedRenameSync(tmpPath, abs);
} catch (err) {
try {
tracedUnlinkSync(tmpPath);
} catch {}
return {
ok: false,
error: {
code: 'WRITE_ERROR',
message: `Failed to write skill file ${input.relPath}: ${(err as Error).message}`,
},
};
}
return {
ok: true,
path: relPathOf(input.skillsRoot, abs),
created,
};
}
export type BundleFileRenameResult =
| { ok: true }
| { ok: false; error: { code: string; message: string } };
export function applySkillBundleFileRename(
input: BundleFileInput & { toRelPath: string },
): BundleFileRenameResult {
const base = validateBase(input.skillsRoot);
if (!base.ok) return { ok: false, error: base.error };
const nameCheck = validateName(input.name);
if (!nameCheck.ok) return { ok: false, error: nameCheck.error };
const { skillDir } = skillPaths(input.skillsRoot, input.name);
const from = resolveBundleFileAbs(skillDir, input.relPath);
if (!from.ok) return { ok: false, error: from.error };
const to = resolveBundleFileAbs(skillDir, input.toRelPath);
if (!to.ok) return { ok: false, error: to.error };
for (const abs of [from.abs, to.abs]) {
const pathCheck = validateSkillMutationPath(input.boundary, skillDir, abs);
if (!pathCheck.ok) return pathCheck;
}
if (!existsSync(from.abs)) {
return {
ok: false,
error: { code: 'FILE_NOT_FOUND', message: `No bundle file at ${input.relPath}.` },
};
}
if (existsSync(to.abs)) {
return {
ok: false,
error: {
code: 'DEST_EXISTS',
message: `A bundle file already exists at ${input.toRelPath} — renames never overwrite.`,
},
};
}
try {
tracedMkdirSync(join(to.abs, '..'), { recursive: true });
tracedRenameSync(from.abs, to.abs);
} catch (err) {
return {
ok: false,
error: {
code: 'RENAME_FAILED',
message: `Failed to rename ${input.relPath} -> ${input.toRelPath}: ${(err as Error).message}`,
},
};
}
const parent = join(from.abs, '..');
if (parent !== skillDir && isEmpty(parent)) {
try {
tracedRmdirSync(parent);
} catch {}
}
return { ok: true };
}
export function applySkillBundleFileDelete(input: BundleFileInput): BundleFileDeleteResult {
const base = validateBase(input.skillsRoot);
if (!base.ok) return { ok: false, error: base.error };
const nameCheck = validateName(input.name);
if (!nameCheck.ok) return { ok: false, error: nameCheck.error };
const { skillDir } = skillPaths(input.skillsRoot, input.name);
const resolved = resolveBundleFileAbs(skillDir, input.relPath);
if (!resolved.ok) return { ok: false, error: resolved.error };
const { abs } = resolved;
const pathCheck = validateSkillMutationPath(input.boundary, skillDir, abs);
if (!pathCheck.ok) return pathCheck;
const existed = existsSync(abs);
if (existed) {
try {
if (statSync(abs).isDirectory()) tracedRmSync(abs, { recursive: true, force: true });
else tracedUnlinkSync(abs);
} catch (err) {
return {
ok: false,
error: {
code: 'UNLINK_FAILED',
message: `Failed to delete skill file ${input.relPath}: ${(err as Error).message}`,
},
};
}
const parent = join(abs, '..');
if (parent !== skillDir && isEmpty(parent)) {
try {
tracedRmdirSync(parent);
} catch {}
}
}
return { ok: true, path: relPathOf(input.skillsRoot, abs), existed };
}
export function applySkillDelete(input: DeleteSkillInput): SkillDeleteResult {
const base = validateBase(input.skillsRoot);
if (!base.ok) return { ok: false, error: base.error };
const nameCheck = validateName(input.name);
if (!nameCheck.ok) return { ok: false, error: nameCheck.error };
const { skillsRoot } = base;
const { skillDir } = skillPaths(input.skillsRoot, input.name);
const existed = existsSync(skillDir);
if (existed) {
try {
tracedRmSync(skillDir, { recursive: true, force: true });
} catch (err) {
return {
ok: false,
error: {
code: 'UNLINK_FAILED',
message: `Failed to delete skill at ${relPathOf(input.skillsRoot, skillDir)}: ${(err as Error).message}`,
},
};
}
}
cleanEmptyDirs(skillsRoot);
return { ok: true, path: relPathOf(input.skillsRoot, skillDir), existed };
}
export async function applySkillMove(input: MoveSkillInput): Promise<SkillMoveResult> {
const base = validateBase(input.skillsRoot);
if (!base.ok) return { ok: false, error: base.error };
const fromCheck = validateName(input.fromName);
if (!fromCheck.ok) return { ok: false, error: fromCheck.error };
const toCheck = validateName(input.toName);
if (!toCheck.ok) return { ok: false, error: toCheck.error };
const from = skillPaths(input.skillsRoot, input.fromName);
const to = skillPaths(input.skillsRoot, input.toName);
if (from.skillDir === to.skillDir) {
return {
ok: false,
error: { code: 'NOOP', message: 'Source and destination are the same skill.' },
};
}
if (!existsSync(from.skillDir)) {
return {
ok: false,
error: {
code: 'SKILL_NOT_FOUND',
message: `No skill at ${relPathOf(input.skillsRoot, from.skillDir)}.`,
},
};
}
if (existsSync(to.skillDir)) {
return {
ok: false,
error: {
code: 'SKILL_EXISTS',
message: `A skill already exists at ${relPathOf(input.skillsRoot, to.skillDir)}.`,
},
};
}
let committed: boolean;
try {
committed = await input.relocate(from.skillDir, to.skillDir);
} catch (err) {
return {
ok: false,
error: { code: 'MOVE_FAILED', message: `Failed to move skill: ${(err as Error).message}` },
};
}
return {
ok: true,
fromPath: relPathOf(input.skillsRoot, from.skillDir),
toPath: relPathOf(input.skillsRoot, to.skillDir),
committed,
};
}
function validateBase(
skillsRoot: string,
): { ok: true; skillsRoot: string } | { ok: false; error: { code: string; message: string } } {
if (!isAbsolute(skillsRoot)) {
return {
ok: false,
error: { code: 'BAD_SKILLS_ROOT', message: 'skillsRoot must be absolute' },
};
}
return { ok: true, skillsRoot };
}
function validateName(
name: string,
): { ok: true } | { ok: false; error: { code: string; message: string } } {
if (typeof name !== 'string' || name.length === 0) {
return { ok: false, error: { code: 'BAD_NAME', message: 'Skill name is required.' } };
}
if (name.length > NAME_MAX) {
return {
ok: false,
error: { code: 'BAD_NAME', message: `Skill name must be ≤${NAME_MAX} characters.` },
};
}
if (!SKILL_NAME_REGEX.test(name)) {
return {
ok: false,
error: {
code: 'BAD_NAME',
message: `Skill name must match /^[a-z0-9-]+$/ (got: ${JSON.stringify(name)}). Lowercase letters, digits, hyphens — no slashes, dots, spaces, or uppercase.`,
},
};
}
return { ok: true };
}
function validateFrontmatter(
fm: SkillFrontmatter,
dirName: string,
): { ok: true } | { ok: false; error: { code: string; message: string } } {
if (!fm || typeof fm !== 'object') {
return {
ok: false,
error: {
code: 'BAD_FRONTMATTER',
message: 'Skill frontmatter (name, description) is required.',
},
};
}
if (typeof fm.name !== 'string' || fm.name.length === 0) {
return {
ok: false,
error: { code: 'SKILL_NAME_REQUIRED', message: 'Skill frontmatter.name is required.' },
};
}
if (fm.name !== dirName) {
return {
ok: false,
error: {
code: 'NAME_DIR_MISMATCH',
message: `Skill frontmatter.name (${JSON.stringify(fm.name)}) must equal the skill directory name (${JSON.stringify(dirName)}).`,
},
};
}
if (containsXmlTag(fm.name)) {
return {
ok: false,
error: {
code: 'XML_TAG_IN_NAME',
message: 'Skill frontmatter.name may not contain XML tags (`<...>`).',
},
};
}
if (typeof fm.description !== 'string') {
return {
ok: false,
error: {
code: 'SKILL_DESCRIPTION_REQUIRED',
message:
'Skill frontmatter.description must be a string — it is the primary triggering surface (when to use the skill).',
},
};
}
if (fm.description.length > DESCRIPTION_MAX) {
return {
ok: false,
error: {
code: 'DESCRIPTION_TOO_LONG',
message: `Skill frontmatter.description must be ≤${DESCRIPTION_MAX} characters (got ${fm.description.length}).`,
},
};
}
if (containsXmlTag(fm.description)) {
return {
ok: false,
error: {
code: 'XML_TAG_IN_DESCRIPTION',
message:
'Skill frontmatter.description may not contain XML tags (`<...>`) — they break the Cowork parser and skill loader.',
},
};
}
return { ok: true };
}
function skillPaths(skillsRoot: string, name: string): { skillDir: string; filePath: string } {
const skillDir = join(skillsRoot, name);
const filePath = join(skillDir, SKILL_FILE);
return { skillDir, filePath };
}
function cleanEmptyDirs(skillsRoot: string): void {
if (existsSync(skillsRoot) && isEmpty(skillsRoot)) {
try {
tracedRmdirSync(skillsRoot);
} catch {}
}
const okDir = normalize(join(skillsRoot, '..'));
if (okDir.endsWith(`${sep}.ok`) && existsSync(okDir) && isEmpty(okDir)) {
try {
tracedRmdirSync(okDir);
} catch {}
}
}
function relPathOf(base: string, abs: string): string {
const rel = abs.startsWith(base + sep) ? abs.slice(base.length + 1) : abs;
return normalize(rel).split(sep).join('/');
}
function serializeFrontmatter(fm: SkillFrontmatter): string {
return stringifyYaml({
name: fm.name,
description: fm.description,
...(fm.metadata !== undefined ? { metadata: fm.metadata } : {}),
});
}
function isEmpty(absDir: string): boolean {
try {
return readdirSync(absDir).length === 0;
} catch {
return false;
}
}