/**
 * Skill management -- discovery, installation, and syncing of SKILL.md bundles.
 *
 * Skills are knowledge packs stored in ~/.agents/skills/. Each skill directory
 * contains a SKILL.md (with frontmatter metadata) and optional supporting files
 * (rules/, examples/, etc.). This module handles parsing skill metadata,
 * installing skills into agent version homes, and tracking installation state.
 */
import type { AgentId, SkillMetadata, InstalledSkill } from '../types.js';
/** User-scoped skills dir (~/.agents/skills/). Used for installs. */
export declare function getSkillsDir(): string;
export declare function ensureCentralSkillsDir(): void;
export declare function getAgentSkillsDir(agentId: AgentId): string;
export declare function getProjectSkillsDir(agentId: AgentId, cwd?: string): string;
export interface ValidationResult {
    valid: boolean;
    errors: string[];
    warnings: string[];
}
export declare function validateSkillMetadata(metadata: SkillMetadata | null, skillName: string): ValidationResult;
export interface SkillParseError {
    name: string;
    path: string;
    error: string;
    scope: 'user' | 'project';
}
export interface SkillParseResult {
    metadata: SkillMetadata | null;
    error?: string;
}
/**
 * Parse skill metadata from SKILL.md, returning both result and any error.
 */
export declare function tryParseSkillMetadata(skillDir: string): SkillParseResult;
/**
 * Parse skill metadata from SKILL.md (backward-compatible, returns null on error).
 */
export declare function parseSkillMetadata(skillDir: string): SkillMetadata | null;
export declare function countSkillRules(skillDir: string): number;
/**
 * Count bundled resource files in a skill directory: every regular file
 * beyond SKILL.md itself (reference docs, scripts, assets, etc). Hidden
 * files and hidden directories are skipped.
 */
export declare function countSkillFiles(skillDir: string): number;
export interface DiscoveredSkill {
    name: string;
    path: string;
    metadata: SkillMetadata;
    ruleCount: number;
    validation: ValidationResult;
    parseError?: string;
    /**
     * Which repo the skill was discovered in. `undefined` means the primary
     * ~/.agents/ repo; otherwise the alias of an extra repo registered via
     * `agents repo add`. Primary wins on name collisions.
     */
    source?: string;
}
export declare function discoverSkillsFromRepo(repoPath: string): DiscoveredSkill[];
export declare function installSkill(sourcePath: string, skillName: string, agents: AgentId[], method?: 'symlink' | 'copy'): {
    success: boolean;
    error?: string;
    warnings?: string[];
};
/**
 * Check if a skill exists for an agent.
 */
export declare function skillExists(agentId: AgentId, skillName: string): boolean;
/**
 * Check if installed skill content matches source content.
 * Compares SKILL.md and all rules/*.md files.
 */
export declare function skillContentMatches(agentId: AgentId, skillName: string, sourcePath: string): boolean;
/**
 * List skill names from user (~/.agents/skills/) and system (~/.agents/.system/skills/) dirs.
 * User dir takes priority; deduplication preserves first occurrence.
 */
export declare function listCentralSkills(): string[];
/**
 * Resolve a skill name to its source directory. Searches user dir first,
 * then system dir, then extra repos, then plugin-bundled skills
 * (`plugins/<plugin>/skills/<name>` under any trusted base). Returns null if no
 * source has a SKILL.md.
 *
 * Crediting plugins here is load-bearing (PHNX-3185): a skill materialized from
 * `plugins/design/skills/design` has a real source, so it must resolve — else
 * `versionSkillMatches` finds no source and the skill reads as drifted, and
 * {@link diffVersionSkills} classes it an orphan `prune cleanup` would delete.
 */
export declare function resolveSkillSourcePath(skillName: string): string | null;
/**
 * Union of skill names available across the primary and all enabled extras.
 * Primary wins on name collision.
 */
export declare function listAllSkills(): string[];
/**
 * Path to the skills dir of a specific version home (not the active one).
 */
export declare function getVersionSkillsDir(agent: AgentId, version: string): string;
/**
 * List real skill names installed in a specific version home.
 *
 * Command-as-skill WRAPPERS (a `skills/<name>/SKILL.md` carrying the
 * `agents_command` marker — how command-runtime agents like Codex/Kimi install
 * commands) are excluded: they are commands, reconciled by the commands diff
 * against the command source, not skills. Counting them here made the skill
 * orphan/extra detectors flag every command wrapper (tickets, prune, swarm-plan,
 * …) as an unmanaged skill — a false positive that `prune cleanup` would delete.
 */
export declare function listSkillsInVersionHome(agent: AgentId, version: string): string[];
export interface VersionSkillDiff {
    agent: AgentId;
    version: string;
    toAdd: string[];
    toUpdate: string[];
    matched: string[];
    orphans: string[];
}
/**
 * Compare a version home's skills against central. Returns the reconciliation diff.
 */
export declare function diffVersionSkills(agent: AgentId, version: string): VersionSkillDiff;
/**
 * Install a single skill from central into a specific version home.
 *
 * Copy mode preserves any files that exist in the version home but NOT in
 * central — e.g. user-populated `.env` alongside the git-tracked `.env.example`.
 * Without this, re-running `sync` whenever central content changes would wipe
 * local secrets.
 */
export declare function installSkillToVersion(agent: AgentId, version: string, skillName: string, method?: 'symlink' | 'copy'): {
    success: boolean;
    error?: string;
};
/**
 * Remove a single skill from a specific version home.
 */
export declare function removeSkillFromVersion(agent: AgentId, version: string, skillName: string): {
    success: boolean;
    error?: string;
};
/**
 * Iterate all (agent, version) pairs that support skills and are installed,
 * optionally scoped to a single agent/version.
 */
export declare function iterSkillsCapableVersions(filter?: {
    agent?: AgentId;
    version?: string;
}): Array<{
    agent: AgentId;
    version: string;
}>;
export declare function uninstallSkill(skillName: string): {
    success: boolean;
    error?: string;
};
export declare function listInstalledSkills(): Map<string, DiscoveredSkill>;
export declare function listInstalledSkillsWithScope(agentId: AgentId, cwd?: string, options?: {
    home?: string;
    errors?: SkillParseError[];
}): InstalledSkill[];
export declare function getSkillInfo(skillName: string): DiscoveredSkill | null;
export declare function getSkillRules(skillName: string): string[];
/**
 * Install a skill to central ~/.agents/skills/ directory only.
 * Does not create per-agent symlinks (shims handle that for synced agents).
 */
export declare function installSkillCentrally(sourcePath: string, skillName: string): {
    success: boolean;
    error?: string;
    warnings?: string[];
};
