Andy.Skills 2026.7.21-rc.17

Andy.Skills

⚠️ ALPHA — APIs may change without notice. Not for production use.

Agent Skills for .NET: discovery, parsing, and prompt composition for SKILL.md skill packages, following the Agent Skills convention with lazy disclosure — only skill names and descriptions go into the system prompt; a skill's full instructions are read from disk when the agent decides the skill is relevant.

Part of the Andy ecosystem (Andy Engine, Andy CLI) but usable independently.

What's in the box

• SkillParser — parses SKILL.md manifests (YAML frontmatter + markdown body). No YAML dependency. Handles the frontmatter shapes real skills use: quoted scalars, inline ([a, b]) and block (- item) lists — including block sequences at the same indent as their key — folded (>) / literal (|) scalars, unmarked multi-line plain scalars and multi-line quoted scalars (a wrapped description:), and a one-level metadata: map. Extension structures it doesn't model (embedded JSON flow-maps, nested lists/maps) are tolerated, not rejected. Only a manifest that can't yield a skill throws (no frontmatter, missing name/description, unclosed block); spec-limit lints (an over-long / non-conforming name or description) come back as non-fatal warnings via ParseWithWarnings. Validated against 80,000+ real skills from the skills.sh catalog (~2,400 repos): 98%+ parse.
• SkillDiscovery — scans skill roots (<root>/<skill-dir>/SKILL.md), with precedence (project skills override user skills) and non-fatal diagnostics for invalid manifests. Conventional roots: <workspace>/.andy/skills, then ~/.andy/skills.
• SkillPromptComposer — renders the lazy-disclosure summary block for a system prompt.
• Skill.GetBodyAsync() — loads a skill's full instructions on demand.

Skill layout

.andy/skills/
  pdf-forms/
    SKILL.md          # frontmatter: name, description, [license, allowed-tools, metadata]
    scripts/          # optional resources referenced by the body
    references/

Usage

using Andy.Skills;

var result = await SkillDiscovery.DiscoverAsync(SkillDiscovery.DefaultRoots(workspaceDir));

// Inject one-line summaries into the system prompt (lazy disclosure).
var promptBlock = SkillPromptComposer.Compose(result.Skills);

// Later, when the agent activates a skill:
var body = await result.Skills[0].GetBodyAsync();

Example

A runnable end-to-end demo (discover → compose → activate) lives under examples/Andy.Skills.Examples, with a sample skill tree at examples/Andy.Skills.Examples/skills/pdf-forms/:

dotnet run --project examples/Andy.Skills.Examples

Building

Requires the .NET 10 SDK (the library multi-targets net8.0 and net10.0).

dotnet build
dotnet test

Conformance

SkillParser is validated against the full skills.sh catalog (~80k manifests). The check is committed and re-runnable — run it after any parser change:

conformance/run.sh --limit 0 --max-error-rate 0.5   # full catalog, gate on regressions
conformance/run.sh --limit 300                       # quick sample, ~1 min

See conformance/README.md and docs/skills-sh-catalog-report.md.

Andy.Tools integration

The Andy.Skills.Tools package plugs skills into Andy.Tools / Andy.Engine as two tools: skill — the agent calls it to pull a skill's body on demand (lazy disclosure) — and skill_file, read-only access to a skill's own bundled resources (scripts/, references/, …) confined to that skill's directory. Register them after AddAndyTools:

using Andy.Skills;
using Andy.Skills.Tools;

services
    .AddAndyTools()
    .AddAndySkills(SkillDiscovery.DefaultRoots(workspaceDir).ToArray());

// Compose the one-line summaries into your system prompt so the model knows what's available:
var catalog = provider.GetRequiredService<ISkillCatalog>();
var promptBlock = SkillPromptComposer.Compose(await catalog.GetSkillsAsync());

AddAndySkills registers an ISkillCatalog (discovers + caches the skill list; bodies stay fresh) and the skill + skill_file tools. The core Andy.Skills package stays dependency-free — only Andy.Skills.Tools takes the Andy.Tools dependency.

Roadmap

• AGENTS.md instruction-file loading (hierarchical), sharing the discovery machinery.

See docs/design.md for the full design and integration plan.

License

Apache-2.0