@skill-tools/core 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,278 @@
+/**
+ * Severity levels for diagnostic messages.
+ * Follows the same hierarchy as LSP diagnostics.
+ */
+type DiagnosticSeverity = 'error' | 'warning' | 'info';
+/**
+ * A diagnostic message produced by validation or linting.
+ * Contains the location, severity, and suggested fix for an issue.
+ */
+interface Diagnostic {
+    /** Unique rule identifier, e.g. "frontmatter-required" or "description-specificity" */
+    readonly ruleId: string;
+    /** Severity of the diagnostic */
+    readonly severity: DiagnosticSeverity;
+    /** Human-readable message describing the issue */
+    readonly message: string;
+    /** Optional file path where the issue was found */
+    readonly file?: string;
+    /** Optional 1-based line number in the file */
+    readonly line?: number;
+    /** Optional 1-based column number in the file */
+    readonly column?: number;
+    /** Optional suggestion for how to fix the issue */
+    readonly fix?: string;
+}
+/**
+ * YAML frontmatter metadata for a SKILL.md file.
+ *
+ * Based on the Agent Skills specification:
+ * - Claude Code: https://code.claude.com/docs/en/skills
+ * - Codex: https://developers.openai.com/codex/skills/
+ *
+ * Both `name` and `description` are strongly recommended.
+ * All other fields are optional platform-specific extensions.
+ */
+interface SkillMetadata {
+    /**
+     * Skill name identifier. Becomes the /slash-command.
+     * Lowercase letters, numbers, and hyphens only (max 64 characters).
+     * If omitted, the directory name is used as fallback.
+     */
+    readonly name?: string;
+    /**
+     * Description used for agent discovery and routing.
+     * Should explain what the skill does AND when to use it.
+     * If omitted, the first paragraph of markdown content may be used.
+     */
+    readonly description?: string;
+    /** Semantic version of the skill */
+    readonly version?: string;
+    /**
+     * Hint shown during autocomplete for expected arguments.
+     * Example: "[issue-number]" or "[filename] [format]"
+     */
+    readonly 'argument-hint'?: string;
+    /**
+     * Set to true to prevent the agent from automatically loading this skill.
+     * Use for workflows you want to trigger manually with /name.
+     */
+    readonly 'disable-model-invocation'?: boolean;
+    /**
+     * Set to false to hide from the / menu.
+     * Use for background knowledge users shouldn't invoke directly.
+     */
+    readonly 'user-invocable'?: boolean;
+    /**
+     * Tools the agent can use without permission when this skill is active.
+     * Comma-separated tool names, e.g. "Read, Grep, Glob"
+     */
+    readonly 'allowed-tools'?: string;
+    /**
+     * Model to use when this skill is active.
+     */
+    readonly model?: string;
+    /**
+     * Set to "fork" to run in a forked subagent context.
+     */
+    readonly context?: 'fork' | string;
+    /**
+     * Which subagent type to use when context: fork is set.
+     * Options: "Explore", "Plan", "general-purpose", or a custom agent name.
+     */
+    readonly agent?: string;
+    /**
+     * Hooks scoped to this skill's lifecycle.
+     */
+    readonly hooks?: Record<string, unknown>;
+    /** Arbitrary additional metadata key-value pairs */
+    readonly [key: string]: unknown;
+}
+/**
+ * A parsed section of a SKILL.md file's markdown body.
+ * Represents a heading and its content.
+ */
+interface SkillSection {
+    /** Heading text (without the # prefix) */
+    readonly heading: string;
+    /** Heading depth (1-6) */
+    readonly depth: number;
+    /** Raw markdown content under this heading */
+    readonly content: string;
+    /** 1-based line number where this section starts */
+    readonly line: number;
+}
+/**
+ * A file referenced from within the skill directory.
+ * Used for tracking file reference integrity.
+ */
+interface SkillFileReference {
+    /** The path as written in the SKILL.md (relative) */
+    readonly path: string;
+    /** 1-based line number where this reference appears */
+    readonly line: number;
+    /** Whether the referenced file actually exists on disk */
+    readonly exists: boolean;
+}
+/**
+ * Complete parsed representation of a SKILL.md file.
+ * This is the primary data structure that all tools operate on.
+ */
+interface Skill {
+    /** Parsed YAML frontmatter metadata */
+    readonly metadata: SkillMetadata;
+    /** Raw markdown body (everything after frontmatter) */
+    readonly body: string;
+    /** Parsed sections from the markdown body */
+    readonly sections: readonly SkillSection[];
+    /** File references found in the markdown body */
+    readonly fileReferences: readonly SkillFileReference[];
+    /** Absolute path to the SKILL.md file */
+    readonly filePath: string;
+    /** Absolute path to the skill directory (parent of SKILL.md) */
+    readonly dirPath: string;
+    /** Token count of the full SKILL.md content */
+    readonly tokenCount: number;
+    /** Line count of the SKILL.md body (excluding frontmatter) */
+    readonly lineCount: number;
+    /** Raw content of the entire SKILL.md file */
+    readonly rawContent: string;
+}
+/**
+ * Result of parsing a SKILL.md file.
+ * Either succeeds with a Skill object or fails with diagnostics.
+ */
+type ParseResult = {
+    readonly ok: true;
+    readonly skill: Skill;
+    readonly diagnostics: readonly Diagnostic[];
+} | {
+    readonly ok: false;
+    readonly skill: null;
+    readonly diagnostics: readonly Diagnostic[];
+};
+/**
+ * Quality score for a single dimension.
+ */
+interface DimensionScore {
+    /** Points earned in this dimension */
+    readonly score: number;
+    /** Maximum points possible for this dimension */
+    readonly max: number;
+    /** Human-readable label for this dimension */
+    readonly label: string;
+    /** Details about what contributed to the score */
+    readonly details?: string;
+}
+/**
+ * Complete quality score breakdown.
+ */
+interface QualityScore {
+    /** Overall score (0-100) */
+    readonly score: number;
+    /** Per-dimension breakdowns */
+    readonly dimensions: Record<string, DimensionScore>;
+    /** Actionable suggestions for improvement */
+    readonly suggestions: readonly ScoreSuggestion[];
+}
+/**
+ * A suggestion for improving a quality score.
+ */
+interface ScoreSuggestion {
+    /** Human-readable suggestion */
+    readonly message: string;
+    /** Estimated point improvement if implemented */
+    readonly pointsGain: number;
+    /** Which dimension this suggestion applies to */
+    readonly dimension: string;
+}
+
+/**
+ * Parse a SKILL.md file from a file path.
+ *
+ * Reads the file, parses frontmatter and markdown body, extracts sections,
+ * resolves file references, and counts tokens. Returns either a successful
+ * parse result with the Skill object, or a failed result with diagnostics
+ * explaining what went wrong.
+ *
+ * @param filePath - Absolute or relative path to a SKILL.md file
+ * @returns ParseResult with either a Skill object or error diagnostics
+ *
+ * @example
+ * ```ts
+ * const result = await parseSkill('./my-skill/SKILL.md');
+ * if (result.ok) {
+ *   console.log(result.skill.metadata.name);
+ * } else {
+ *   console.error(result.diagnostics);
+ * }
+ * ```
+ */
+declare function parseSkill(filePath: string): Promise<ParseResult>;
+/**
+ * Parse SKILL.md content from a raw string.
+ * Useful when you already have the content in memory.
+ *
+ * @param rawContent - The raw SKILL.md file content
+ * @param filePath - The file path (used for diagnostics and file reference resolution)
+ * @param dirPath - The skill directory path (used for file reference resolution)
+ * @returns ParseResult with either a Skill object or error diagnostics
+ */
+declare function parseSkillContent(rawContent: string, filePath: string, dirPath: string): ParseResult;
+
+/**
+ * Information about a discovered skill in the filesystem.
+ */
+interface SkillLocation {
+    /** Absolute path to the SKILL.md file */
+    readonly skillFile: string;
+    /** Absolute path to the skill directory */
+    readonly directory: string;
+    /** The directory name (used as a fallback identifier) */
+    readonly dirName: string;
+}
+/**
+ * Resolve all SKILL.md files in a directory tree.
+ *
+ * Searches for SKILL.md files in the given path. If the path itself
+ * contains a SKILL.md, returns just that one. If the path is a directory,
+ * searches one level deep for subdirectories containing SKILL.md files.
+ *
+ * @param searchPath - Absolute or relative path to search
+ * @returns Array of discovered skill locations
+ *
+ * @example
+ * ```ts
+ * // Single skill directory
+ * const skills = await resolveSkillFiles('./my-skill/');
+ * // => [{ skillFile: '/abs/path/my-skill/SKILL.md', ... }]
+ *
+ * // Directory of skills
+ * const skills = await resolveSkillFiles('./skills/');
+ * // => [
+ * //   { skillFile: '/abs/path/skills/deploy/SKILL.md', ... },
+ * //   { skillFile: '/abs/path/skills/test-runner/SKILL.md', ... },
+ * // ]
+ * ```
+ */
+declare function resolveSkillFiles(searchPath: string): Promise<SkillLocation[]>;
+
+/**
+ * Count the number of tokens in a string.
+ *
+ * Uses the cl100k_base tokenizer (GPT-4o compatible), which provides
+ * a reasonable approximation for both OpenAI and Anthropic models.
+ * Actual token counts may vary slightly between providers.
+ *
+ * @param text - The text to count tokens for
+ * @returns The number of tokens
+ *
+ * @example
+ * ```ts
+ * const count = countTokens('Hello, world!');
+ * // => 4
+ * ```
+ */
+declare function countTokens(text: string): number;
+
+export { type Diagnostic, type DiagnosticSeverity, type DimensionScore, type ParseResult, type QualityScore, type ScoreSuggestion, type Skill, type SkillFileReference, type SkillLocation, type SkillMetadata, type SkillSection, countTokens, parseSkill, parseSkillContent, resolveSkillFiles };

package/dist/index.d.ts

@@ -0,0 +1,278 @@
+/**
+ * Severity levels for diagnostic messages.
+ * Follows the same hierarchy as LSP diagnostics.
+ */
+type DiagnosticSeverity = 'error' | 'warning' | 'info';
+/**
+ * A diagnostic message produced by validation or linting.
+ * Contains the location, severity, and suggested fix for an issue.
+ */
+interface Diagnostic {
+    /** Unique rule identifier, e.g. "frontmatter-required" or "description-specificity" */
+    readonly ruleId: string;
+    /** Severity of the diagnostic */
+    readonly severity: DiagnosticSeverity;
+    /** Human-readable message describing the issue */
+    readonly message: string;
+    /** Optional file path where the issue was found */
+    readonly file?: string;
+    /** Optional 1-based line number in the file */
+    readonly line?: number;
+    /** Optional 1-based column number in the file */
+    readonly column?: number;
+    /** Optional suggestion for how to fix the issue */
+    readonly fix?: string;
+}
+/**
+ * YAML frontmatter metadata for a SKILL.md file.
+ *
+ * Based on the Agent Skills specification:
+ * - Claude Code: https://code.claude.com/docs/en/skills
+ * - Codex: https://developers.openai.com/codex/skills/
+ *
+ * Both `name` and `description` are strongly recommended.
+ * All other fields are optional platform-specific extensions.
+ */
+interface SkillMetadata {
+    /**
+     * Skill name identifier. Becomes the /slash-command.
+     * Lowercase letters, numbers, and hyphens only (max 64 characters).
+     * If omitted, the directory name is used as fallback.
+     */
+    readonly name?: string;
+    /**
+     * Description used for agent discovery and routing.
+     * Should explain what the skill does AND when to use it.
+     * If omitted, the first paragraph of markdown content may be used.
+     */
+    readonly description?: string;
+    /** Semantic version of the skill */
+    readonly version?: string;
+    /**
+     * Hint shown during autocomplete for expected arguments.
+     * Example: "[issue-number]" or "[filename] [format]"
+     */
+    readonly 'argument-hint'?: string;
+    /**
+     * Set to true to prevent the agent from automatically loading this skill.
+     * Use for workflows you want to trigger manually with /name.
+     */
+    readonly 'disable-model-invocation'?: boolean;
+    /**
+     * Set to false to hide from the / menu.
+     * Use for background knowledge users shouldn't invoke directly.
+     */
+    readonly 'user-invocable'?: boolean;
+    /**
+     * Tools the agent can use without permission when this skill is active.
+     * Comma-separated tool names, e.g. "Read, Grep, Glob"
+     */
+    readonly 'allowed-tools'?: string;
+    /**
+     * Model to use when this skill is active.
+     */
+    readonly model?: string;
+    /**
+     * Set to "fork" to run in a forked subagent context.
+     */
+    readonly context?: 'fork' | string;
+    /**
+     * Which subagent type to use when context: fork is set.
+     * Options: "Explore", "Plan", "general-purpose", or a custom agent name.
+     */
+    readonly agent?: string;
+    /**
+     * Hooks scoped to this skill's lifecycle.
+     */
+    readonly hooks?: Record<string, unknown>;
+    /** Arbitrary additional metadata key-value pairs */
+    readonly [key: string]: unknown;
+}
+/**
+ * A parsed section of a SKILL.md file's markdown body.
+ * Represents a heading and its content.
+ */
+interface SkillSection {
+    /** Heading text (without the # prefix) */
+    readonly heading: string;
+    /** Heading depth (1-6) */
+    readonly depth: number;
+    /** Raw markdown content under this heading */
+    readonly content: string;
+    /** 1-based line number where this section starts */
+    readonly line: number;
+}
+/**
+ * A file referenced from within the skill directory.
+ * Used for tracking file reference integrity.
+ */
+interface SkillFileReference {
+    /** The path as written in the SKILL.md (relative) */
+    readonly path: string;
+    /** 1-based line number where this reference appears */
+    readonly line: number;
+    /** Whether the referenced file actually exists on disk */
+    readonly exists: boolean;
+}
+/**
+ * Complete parsed representation of a SKILL.md file.
+ * This is the primary data structure that all tools operate on.
+ */
+interface Skill {
+    /** Parsed YAML frontmatter metadata */
+    readonly metadata: SkillMetadata;
+    /** Raw markdown body (everything after frontmatter) */
+    readonly body: string;
+    /** Parsed sections from the markdown body */
+    readonly sections: readonly SkillSection[];
+    /** File references found in the markdown body */
+    readonly fileReferences: readonly SkillFileReference[];
+    /** Absolute path to the SKILL.md file */
+    readonly filePath: string;
+    /** Absolute path to the skill directory (parent of SKILL.md) */
+    readonly dirPath: string;
+    /** Token count of the full SKILL.md content */
+    readonly tokenCount: number;
+    /** Line count of the SKILL.md body (excluding frontmatter) */
+    readonly lineCount: number;
+    /** Raw content of the entire SKILL.md file */
+    readonly rawContent: string;
+}
+/**
+ * Result of parsing a SKILL.md file.
+ * Either succeeds with a Skill object or fails with diagnostics.
+ */
+type ParseResult = {
+    readonly ok: true;
+    readonly skill: Skill;
+    readonly diagnostics: readonly Diagnostic[];
+} | {
+    readonly ok: false;
+    readonly skill: null;
+    readonly diagnostics: readonly Diagnostic[];
+};
+/**
+ * Quality score for a single dimension.
+ */
+interface DimensionScore {
+    /** Points earned in this dimension */
+    readonly score: number;
+    /** Maximum points possible for this dimension */
+    readonly max: number;
+    /** Human-readable label for this dimension */
+    readonly label: string;
+    /** Details about what contributed to the score */
+    readonly details?: string;
+}
+/**
+ * Complete quality score breakdown.
+ */
+interface QualityScore {
+    /** Overall score (0-100) */
+    readonly score: number;
+    /** Per-dimension breakdowns */
+    readonly dimensions: Record<string, DimensionScore>;
+    /** Actionable suggestions for improvement */
+    readonly suggestions: readonly ScoreSuggestion[];
+}
+/**
+ * A suggestion for improving a quality score.
+ */
+interface ScoreSuggestion {
+    /** Human-readable suggestion */
+    readonly message: string;
+    /** Estimated point improvement if implemented */
+    readonly pointsGain: number;
+    /** Which dimension this suggestion applies to */
+    readonly dimension: string;
+}
+
+/**
+ * Parse a SKILL.md file from a file path.
+ *
+ * Reads the file, parses frontmatter and markdown body, extracts sections,
+ * resolves file references, and counts tokens. Returns either a successful
+ * parse result with the Skill object, or a failed result with diagnostics
+ * explaining what went wrong.
+ *
+ * @param filePath - Absolute or relative path to a SKILL.md file
+ * @returns ParseResult with either a Skill object or error diagnostics
+ *
+ * @example
+ * ```ts
+ * const result = await parseSkill('./my-skill/SKILL.md');
+ * if (result.ok) {
+ *   console.log(result.skill.metadata.name);
+ * } else {
+ *   console.error(result.diagnostics);
+ * }
+ * ```
+ */
+declare function parseSkill(filePath: string): Promise<ParseResult>;
+/**
+ * Parse SKILL.md content from a raw string.
+ * Useful when you already have the content in memory.
+ *
+ * @param rawContent - The raw SKILL.md file content
+ * @param filePath - The file path (used for diagnostics and file reference resolution)
+ * @param dirPath - The skill directory path (used for file reference resolution)
+ * @returns ParseResult with either a Skill object or error diagnostics
+ */
+declare function parseSkillContent(rawContent: string, filePath: string, dirPath: string): ParseResult;
+
+/**
+ * Information about a discovered skill in the filesystem.
+ */
+interface SkillLocation {
+    /** Absolute path to the SKILL.md file */
+    readonly skillFile: string;
+    /** Absolute path to the skill directory */
+    readonly directory: string;
+    /** The directory name (used as a fallback identifier) */
+    readonly dirName: string;
+}
+/**
+ * Resolve all SKILL.md files in a directory tree.
+ *
+ * Searches for SKILL.md files in the given path. If the path itself
+ * contains a SKILL.md, returns just that one. If the path is a directory,
+ * searches one level deep for subdirectories containing SKILL.md files.
+ *
+ * @param searchPath - Absolute or relative path to search
+ * @returns Array of discovered skill locations
+ *
+ * @example
+ * ```ts
+ * // Single skill directory
+ * const skills = await resolveSkillFiles('./my-skill/');
+ * // => [{ skillFile: '/abs/path/my-skill/SKILL.md', ... }]
+ *
+ * // Directory of skills
+ * const skills = await resolveSkillFiles('./skills/');
+ * // => [
+ * //   { skillFile: '/abs/path/skills/deploy/SKILL.md', ... },
+ * //   { skillFile: '/abs/path/skills/test-runner/SKILL.md', ... },
+ * // ]
+ * ```
+ */
+declare function resolveSkillFiles(searchPath: string): Promise<SkillLocation[]>;
+
+/**
+ * Count the number of tokens in a string.
+ *
+ * Uses the cl100k_base tokenizer (GPT-4o compatible), which provides
+ * a reasonable approximation for both OpenAI and Anthropic models.
+ * Actual token counts may vary slightly between providers.
+ *
+ * @param text - The text to count tokens for
+ * @returns The number of tokens
+ *
+ * @example
+ * ```ts
+ * const count = countTokens('Hello, world!');
+ * // => 4
+ * ```
+ */
+declare function countTokens(text: string): number;
+
+export { type Diagnostic, type DiagnosticSeverity, type DimensionScore, type ParseResult, type QualityScore, type ScoreSuggestion, type Skill, type SkillFileReference, type SkillLocation, type SkillMetadata, type SkillSection, countTokens, parseSkill, parseSkillContent, resolveSkillFiles };