/**
 * `SKILL.md` — the interchange format.
 *
 * A deployment's canonical storage is its own (a database row, a directory of
 * files), but the portable form is the de-facto `SKILL.md` bundle: a `---`
 * fenced YAML frontmatter block followed by a markdown body, as used by
 * Anthropic's skills and agentskills.io. It is how a skill authored in one
 * place is read in another, which makes both directions of this file a
 * compatibility surface rather than an internal convenience.
 *
 * **Import is deliberately lenient and export is deliberately strict.** The
 * input is a document a person wrote, often in another tool, and the two
 * outcomes are not symmetric: refusing a skill over a cosmetic frontmatter
 * mistake loses knowledge the author already wrote down, while accepting a
 * malformed one costs a warning. So parsing repairs what it can, warns about
 * what it repaired, and fails on exactly two things — frontmatter that is not
 * YAML at all, and a missing `description`, which is the one field with no
 * sensible default because it is the entire Tier-1 catalog line.
 *
 * **YAML arrives as a port.** The package takes peer dependencies only, and a
 * YAML implementation is neither a peer the harness can assume nor something
 * it should bundle. Every host that reads `SKILL.md` already has one — the
 * seam is two functions wide.
 */
/**
 * The host's YAML implementation. `js-yaml`'s `load`/`dump` and the `yaml`
 * package's `parse`/`stringify` both satisfy it directly.
 *
 * `parse` must **throw** on invalid YAML rather than returning a sentinel: the
 * repair pass below is driven by the throw, so a parser that returns
 * `undefined` instead would skip the repair and reject documents this module
 * is meant to accept.
 */
export interface SkillYamlCodec {
    parse: (text: string) => unknown;
    /** Must emit block-style YAML and must not wrap long lines. */
    stringify: (value: Record<string, unknown>) => string;
}
export interface ParsedSkillMd {
    /** `null` when frontmatter omits it — the caller supplies a fallback (usually the filename). */
    name: string | null;
    description: string;
    whenToUse: string | null;
    body: string;
    /** Unknown frontmatter keys, preserved for round-trip and read-only display. */
    metadata: Record<string, unknown> | null;
}
export type SkillMdParseResult = {
    ok: true;
    skill: ParsedSkillMd;
    warnings: string[];
} | {
    ok: false;
    error: string;
    warnings: string[];
};
/** Parse a raw `SKILL.md` (frontmatter + body) into importable fields. */
export declare function parseSkillMarkdown(raw: string, yaml: SkillYamlCodec): SkillMdParseResult;
/**
 * Serialize a stored skill back to canonical `SKILL.md` text.
 *
 * Preserved unknown keys are written first and the canonical keys last, so a
 * stray `name` / `description` / `when_to_use` that ended up inside `metadata`
 * — which an earlier lenient import makes possible — cannot clobber the real
 * value on the way out.
 */
export declare function serializeSkillMarkdown(skill: {
    name: string;
    description: string;
    whenToUse: string | null;
    body: string;
    metadata: Record<string, unknown> | null;
}, yaml: SkillYamlCodec): string;