zidane/skills

Define an inline skill configuration.

Strict-validates at author-time — throws if the config would be rejected by writeSkillToDisk or the spec. Source defaults to 'inline'.

Discover skills from sourced filesystem paths. Each path is scanned for subdirectories containing SKILL.md. Earlier paths have higher priority (first-found wins on name collision).

signal is checked between each parseSkillFile so a rapid cwd switch in the host (TUI / GUI) can stop a long scan without leaking I/O. Aborts reject with the signal's reason (or a default AbortError) — same shape AbortSignal.throwIfAborted() produces in modern runtimes.

Register tool:gate / mcp:tool:gate handlers that enforce the union of allowedTools across active skills.

No-op when no active skill declares an allow-list (permissive default — matches the spec's "experimental" note for allowed-tools).

Returns an uninstall fn. The agent calls this at run end to detach the handlers and prevent cross-run hook leaks.

Install a skill (or one skill out of a multi-skill source).

Engine selection: targeted installs (an explicit skill selector) go through the skills.sh CLI when present on PATH (unless preferSkillsCli: false) — keeping their cross-agent layout and lockfile — else the native fetch pipeline. Selector-less installs are ALWAYS native: only native enumeration can tell single- from multi-skill sources, and the host's "import all?" prompt rides on the multiple-candidates error — delegating them to skills add … -y would let the CLI's own multi-skill behavior silently decide instead. all: true batches are native for the same reason (skip-existing + per-skill provenance are our semantics).

Interpolate shell commands in skill instructions.

Runs each !command through the execution context and replaces the placeholder with the command's stdout. If a command fails, the placeholder is replaced with an error message (and options.onFailure is notified when provided).

List installable skills inside a fetched tree.

A skill is ANY directory containing a SKILL.md — found by a bounded recursive walk (depth CANDIDATE_WALK_MAX_DEPTH), skipping dot-dirs and node_modules, and never descending INTO a skill (its references/ / scripts/ subtree ships with it, it doesn't nest further candidates). A root-level SKILL.md means "repo IS the skill" and short-circuits, named from the fallback.

Candidates carry their root-relative path (rel) so same-named skills in different categories stay individually addressable. Sorted by rel.

Check whether a tool call (identified by its wire/displayName and argument input) matches a skill's allow-list entry.

Matching rules (Zidane's interpretation of the spec's unspecified syntax):

• Exact match: displayName === pattern (no parens).
• Prefix match: for Tool(arg:*), displayName === 'Tool' AND any string value in the input object starts with arg. This is intentionally permissive: it doesn't depend on a convention about which property carries the "command" (schemas vary across tools), and for the common shell({ command: 'git …' }) shape it behaves identically to a "primary string" rule.
• For tools whose inputs carry no string values, the arg-match returns false.

Parse a single allowed-tools entry into its tool name + optional argument pattern.

Examples:

• Read → { tool: 'Read' }
• Bash(git:*) → { tool: 'Bash', argPrefix: 'git' }

Parse a SKILL.md file into frontmatter + body.

Uses a simple regex-based YAML extractor that handles:

• Flat key: value pairs
• Quoted values
• One-level nested maps (for metadata:)
• One-level nested block lists, key: followed by indented - item lines (for allowed-tools and any future array fields). Items are unquoted with the same rules as scalar values.
• Flow-style scalars are preserved verbatim — interpretation (e.g. [a, b] as a list) is left to per-field consumers via takeStringOrArray.
• Unquoted values that contain colons (e.g. description: Use when: the user asks …): the line splits on the first colon only, so the rest stays in the value.
• Block scalars (| literal, > folded, with chomping and indentation indicators) as top-level or nested map values.

Parse a SKILL.md file into a SkillConfig (lenient).

Returns null only when the skill is fundamentally unusable:

• The file is missing
• The description is absent (required by spec for disclosure)

All other issues are surfaced as SkillConfig.diagnostics with severity warning. Deprecated top-level fields (paths, model, thinking, effort) are auto-migrated into metadata['zidane.*']. source defaults to 'project'.

Resolve all skills from a SkillsConfig:

1. Materialize config.write entries to a temp directory, tagged as inline
2. Combine with default + user-provided scan paths (project-first, user-next)
3. Run lenient disk discovery
4. Merge with any host-provided config.catalog. Catalog entries seed the resolution map FIRST, so they shadow disk-discovered skills with the same name (shadow diagnostic attached to the winner — same shape as the disk-vs-disk collision case).
5. Apply filters: optional project-skill trust gate, exclude, enabled allowlist

Returns { skills, cleanup } — call cleanup() on agent destroy to remove the temp directory created for inline config.write skills. The agent factory wires this automatically; standalone callers must invoke it themselves to avoid leaking OS temp.

Validate that relPath stays inside baseDir when resolved.

Rejects:

• Absolute paths (/etc/passwd, C:\…)
• Parent traversal (.. segments that escape baseDir)
• Null-byte tricks
• Empty paths and paths that resolve to baseDir itself

Returns { valid: true, absolutePath } on success or { valid: false, error } with a human-readable reason.

Symlink-hardened variant of validateResourcePath: after the lexical check passes, resolve both the target and baseDir through realpath and re-confirm the target still lives under the skill directory. A symlink placed inside the skill dir pointing at e.g. /etc/passwd passes the lexical check but fails here.

Falls back to the lexical verdict when realpath fails (target or baseDir not present on the LOCAL filesystem) — the common causes are a remote execution context (docker/sandbox, where the local realpath is meaningless and the remote side resolves the path itself) or a not-yet-existing file. The returned absolutePath is always the lexical one: it's what the execution context resolves; realpath here is verification only.

Validate a skill name per the spec:

• 1–64 characters
• Lowercase alphanumeric + hyphens only
• Must not start or end with a hyphen
• Must not contain consecutive hyphens

The parent-directory match is validated separately (it requires knowing the skill's location, which this function does not).

Write a SkillConfig to disk as a proper skill directory with SKILL.md. Returns the path to the written SKILL.md file.

Throws if the skill fails validateSkillForWrite — the authoring path is strict on purpose. For loading third-party skills, use parseSkillFile directly (lenient).

Types for the Agent Skills system.

Follows the Agent Skills open standard (agentskills.io/specification). Zidane-specific metadata conventionally uses the zidane. key prefix (e.g. metadata['zidane.paths']) to stay spec-compliant.

Reason a skill was deactivated. Surfaced in skills:deactivate hook ctx.

• 'run-end' — the implicit deactivate-all pass at each run() boundary.
• 'explicit' — the host called agent.deactivateSkill(name).
• 'reset' — agent.reset() cleared the activation state along with everything else.
• 'model' — the model called skills_use({ mode: 'deactivate', name }) to release a skill's allow-list mid-run. Session-resume rehydration honors the most recent mode per skill, so a model-driven deactivate sticks across the next turn (no surprise re-activation).

Why a listing failed.

• invalid-source: the text is not a source.
• not-found: no such repository, folder or package, or no access to it.
• rate-limited: GitHub refused more calls without a token, and the download failed too.
• fetch-failed: the network or the download failed.