aigent 0.3.0

Installation
Quick Start
Library Usage
SKILL.md Format
Builder Modes
Compliance
CLI Reference
API Reference
Claude Code Plugin
Development
CI/CD and Release Workflows
References
About and Licence

Installation

Prerequisites

Rust (stable toolchain)
cargo (included with Rust)

From crates.io

cargo install aigent

From source

git clone https://github.com/wkusnierczyk/aigent.git
cd aigent
cargo install --path .

Pre-built binaries

Download a pre-built binary from the latest release (Linux x86_64/aarch64, macOS x86_64/aarch64, Windows x86_64).

Install script (Linux and macOS)

curl -fsSL https://raw.githubusercontent.com/wkusnierczyk/aigent/main/install.sh | bash

Quick Start

# Initialize a new skill
aigent init my-skill/

# Create a skill from a description
aigent new "Process PDF files and extract text" --no-llm

# Validate a skill directory (spec conformance)
aigent validate my-skill/ --structure

# Run validate + semantic quality checks
aigent check my-skill/

# Score a skill against best practices (0–100)
aigent score my-skill/

# Format a SKILL.md (canonical key order, clean whitespace)
aigent fmt my-skill/

# Probe skill activation against a query
aigent probe my-skill/ "process PDF files"

# Run fixture-based test suite
aigent test my-skill/

# Check for upgrade opportunities
aigent upgrade my-skill/

# Assemble skills into a Claude Code plugin
aigent build my-skill/ other-skill/ --output ./dist

# Generate a skill catalog
aigent doc skills/ --recursive

# Read skill properties as JSON
aigent read-properties my-skill/

# Generate XML prompt for LLM injection
aigent prompt my-skill/ other-skill/

To enable LLM-enhanced generation, set an API key in your environment (for example, export ANTHROPIC_API_KEY=sk-...). Without an API key, the builder uses deterministic mode, which requires no configuration. See Builder Modes for details.

Library Usage

use std::path::Path;

// Validate a skill directory
let errors = aigent::validate(Path::new("my-skill"));

// Read skill properties
let props = aigent::read_properties(Path::new("my-skill")).unwrap();

// Generate prompt XML
let xml = aigent::to_prompt(&[Path::new("skill-a"), Path::new("skill-b")]);

// Format a SKILL.md
let result = aigent::format_skill(Path::new("my-skill")).unwrap();

// Assemble skills into a plugin
let opts = aigent::AssembleOptions {
    output_dir: std::path::PathBuf::from("./dist"),
    name: None,
    validate: true,
};
let result = aigent::assemble_plugin(
    &[Path::new("skill-a"), Path::new("skill-b")], &opts,
).unwrap();

// Build a skill
let spec = aigent::SkillSpec {
    purpose: "Process PDF files".to_string(),
    no_llm: true,
    ..Default::default()
};
let result = aigent::build_skill(&spec).unwrap();

SKILL.md Format

Skills are defined in SKILL.md files with YAML frontmatter and a Markdown body:

---
name: extract-csv-data
description: >-
  Extract and transform data from CSV files. Use when the user needs
  to parse, filter, or aggregate CSV data.
license: MIT
compatibility: claude
allowed-tools: Read, Write, Bash
---

# Extract CSV Data

Parse and transform CSV files into structured data.

## When to Use

Use this skill when:
- The user asks to extract data from CSV files
- The task involves filtering or aggregating tabular data

## Instructions

1. Read the CSV file using the Read tool
2. Parse the header row to identify columns
3. Apply any requested filters or transformations

Frontmatter fields

Field	Required	Description
`name`	yes	Kebab-case identifier (e.g., `extract-csv-data`)
`description`	yes	What the skill does and when to use it
`license`	no	Licence identifier (e.g., `MIT`)
`compatibility`	no	Compatible agent platforms
`allowed-tools`	no	Tools the skill may use

Validation rules

name and description are required and non-empty
name: lowercase letters, digits, and hyphens only; maximum 64 characters
name: must not contain reserved words (anthropic, claude)
name: no XML tags; must match directory name
name: Unicode NFKC normalization applied before validation
description: maximum 1024 characters; no XML/HTML tags
compatibility: maximum 500 characters (if present)
Body: warning if longer than 500 lines

Builder Modes

The skill builder operates in two modes:

Deterministic — Always available, zero configuration. Uses heuristic rules to derive skill names (gerund form, kebab-case), descriptions, and Markdown bodies. Output is formulaic but valid.

LLM-enhanced — Auto-detected via environment variables. Produces richer, more natural output. Each generation step (name, description, body) independently falls back to deterministic on LLM failure.

Provider detection order

Priority	Environment Variable	Provider
1	`ANTHROPIC_API_KEY`	Anthropic Claude
2	`OPENAI_API_KEY`	OpenAI
3	`GOOGLE_API_KEY`	Google Gemini
4	`OLLAMA_HOST`	Ollama (local)

Available models (as of 2026-02-20)

Provider	Environment Variable	Default Model	Override Variable
Anthropic	`ANTHROPIC_API_KEY`	`claude-sonnet-4-20250514`	`ANTHROPIC_MODEL`
OpenAI	`OPENAI_API_KEY`	`gpt-4o`	`OPENAI_MODEL`
Google	`GOOGLE_API_KEY`	`gemini-2.0-flash`	`GOOGLE_MODEL`
Ollama	`OLLAMA_HOST`	`llama3.2`	`OLLAMA_MODEL`

OpenAI-compatible endpoints (vLLM, LM Studio, etc.) are supported via OPENAI_API_BASE or OPENAI_BASE_URL.

Use --no-llm to force deterministic mode regardless of available providers.

Compliance

Specification Coverage

Three-way comparison of the Anthropic agent skill specification, aigent, and the Python reference implementation.

Table shows key validation rules from the Anthropic specification. Additional checks (frontmatter structure, metadata keys, YAML syntax) are implemented but not listed as they are standard parser behaviour.

Rule	aigent	Specification	Python Reference
Name ≤ 64 characters	✅	✅	✅
Name: lowercase + hyphens	✅	✅	✅
Name: no XML tags	✅	✅	❌
Name: no reserved words	✅	✅	❌
Name: Unicode NFKC	✅	—	❌
Description: non-empty	✅	✅	✅
Description ≤ 1024 characters	✅	✅	✅
Description: no XML tags	✅	✅	❌
Frontmatter `---` delimiters	✅	✅	✅
Compatibility ≤ 500 characters	✅	✅	❌
Body ≤ 500 lines warning	✅	✅	❌
Prompt XML format	✅	✅	✅
Path canonicalization	✅	—	✅
Post-build validation	✅	—	❌

aigent implements all rules from the specification, plus additional checks (Unicode NFKC normalization, path canonicalization, post-build validation) that go beyond both the specification and the reference implementation.

aigent vs. plugin-dev

Anthropic's plugin-dev plugin (bundled with Claude Code) and aigent are complementary tools for skill development:

	aigent	plugin-dev
What	Rust CLI + library	Claude Code plugin (LLM-guided)
Scope	Deep: SKILL.md toolchain	Broad: entire plugin ecosystem
Validation	Deterministic — typed diagnostics, error codes, JSON output	Heuristic — agent-based review
Scoring	Weighted 0–100 with CI gating	Not available
Formatting	`aigent fmt` — idempotent, `--check` for CI	Not available
Testing	Fixture-based (`tests.yml`) + single-query probe	General guidance only
Assembly	`aigent build` — reproducible, scriptable	`/create-plugin` — guided, interactive
Ecosystem	Skills only	Skills + commands + agents + hooks + MCP + settings

aigent handles the depth of SKILL.md quality enforcement (validation, scoring, formatting, testing, assembly). plugin-dev covers the breadth of the Claude Code plugin ecosystem (7 component types, ~21,000 words of guidance). Use plugin-dev to learn patterns; use aigent to enforce them.

For the full analysis, see dev/plugin-dev.md.

Extras

Features in aigent that go beyond the specification and reference implementation:

Feature	Description
Semantic linting	Quality checks: third-person descriptions, trigger phrases, gerund names, generic names
Quality scoring	Weighted 0–100 score with distinct pass/fail labels per check
Auto-fix	Automatic correction of fixable issues (e.g., name casing)
Skill builder	Generate skills from natural language (deterministic + multi-provider LLM)
Interactive build	Step-by-step confirmation mode for skill generation
Skill tester (probe)	Simulate skill activation with weighted scoring formula (0.5×description + 0.3×trigger + 0.2×name)
Fixture-based testing	Run test suites from `tests.yml` with expected match/no-match and minimum score thresholds
SKILL.md formatter	Canonical YAML key ordering, consistent whitespace, idempotent formatting
Skill-to-plugin assembly	Package skill directories into a Claude Code plugin with `plugin.json` manifest
Skill upgrade	Detect and apply best-practice upgrades with `--full` mode (validate + lint + fix + upgrade)
Unified check command	`check` = validate + semantic lint; `--no-validate` for lint-only
Directory structure validation	Check for missing references, script permissions, nesting depth
Cross-skill conflict detection	Name collisions, description similarity, token budget analysis
Documentation generation	Markdown skill catalog with diff-aware output
Watch mode	Continuous validation on filesystem changes (optional `notify` feature)
Multi-format prompt output	XML, JSON, YAML, Markdown prompt generation
Multi-format validation output	Text and JSON diagnostic output
Token budget estimation	Per-skill and total token usage reporting
Claude Code plugin	Hybrid skills that work with or without the CLI installed

CLI Reference

Run aigent --help for a list of commands, or aigent <command> --help for details on a specific command (flags, arguments, examples). Full API documentation is available at docs.rs/aigent.

Commands

Quality spectrum: validate (spec conformance) → check (+ semantic quality) → score (quantitative 0–100).

Backward compatibility: The old command names lint, to-prompt, and create are available as hidden aliases and continue to work. The old test <dir> <query> single-query syntax has been renamed to probe; test now runs fixture-based test suites.

Validate Flags

Note: Semantic lint checks have moved to check. Use aigent check for combined validation + linting, or aigent check --no-validate for lint-only.

Check Flags

New Flags

Fmt Flags

Build (Assembly) Flags

Test Flags

Upgrade Flags

Command Examples

`validate` — Check skill directories for spec conformance

Validates one or more skill directories against the Anthropic specification. Exit code 0 means valid; non-zero means errors or warnings were found. For combined validation + semantic quality checks, use check instead.

$ aigent validate my-skill/
(no output — skill is valid)

With --structure for directory layout checks:

$ aigent validate skills/aigent-validator --structure
warning: unexpected metadata field: 'argument-hint'

Multiple directories trigger cross-skill conflict detection automatically:

$ aigent validate skills/aigent-validator skills/aigent-builder skills/aigent-scorer
skills/aigent-validator:
  warning: unexpected metadata field: 'argument-hint'
skills/aigent-builder:
  warning: unexpected metadata field: 'argument-hint'
  warning: unexpected metadata field: 'context'
skills/aigent-scorer:
  warning: unexpected metadata field: 'argument-hint'

3 skills: 0 ok, 0 errors, 3 warnings only

JSON output for CI integration:

$ aigent validate skills/aigent-validator --format json
[
  {
    "diagnostics": [
      {
        "code": "W001",
        "field": "metadata",
        "message": "unexpected metadata field: 'argument-hint'",
        "severity": "warning"
      }
    ],
    "path": "skills/aigent-validator"
  }
]

`check` — Validate + semantic quality checks

Runs spec conformance (like validate) plus semantic quality checks: third-person descriptions, trigger phrases, gerund name forms, generic names, and description detail. Use --no-validate to skip spec checks and run semantic lint only.

$ aigent check skills/aigent-validator
warning: unexpected metadata field: 'argument-hint'
info: name does not use gerund form

Semantic lint only (equivalent to the old lint command):

$ aigent check --no-validate skills/aigent-validator
info: name does not use gerund form

`score` — Rate a skill 0–100

Rates a skill from 0 to 100 against the Anthropic best-practices checklist. The score has two weighted categories:

Structural (60 points) — Checks that the SKILL.md parses correctly, the name matches the directory, required fields are present, no unknown fields exist, and the body is within size limits. All six checks must pass to earn the 60 points; any failure zeros the structural score.
Quality (40 points) — Five semantic lint checks worth 8 points each: third-person description, trigger phrase ("Use when..."), gerund name form (converting-pdfs not pdf-converter), specific (non-generic) name, and description length (≥ 20 words).

The exit code is 0 for a perfect score and 1 otherwise, making it suitable for CI gating.

Example — a skill that passes all checks:

$ aigent score converting-pdfs/
Score: 100/100

Structural (60/60):
  [PASS] SKILL.md exists and is parseable
  [PASS] Name format valid
  [PASS] Description valid
  [PASS] Required fields present
  [PASS] No unknown fields
  [PASS] Body within size limits

Quality (40/40):
  [PASS] Third-person description
  [PASS] Trigger phrase present
  [PASS] Gerund name form
  [PASS] Specific name
  [PASS] Detailed description

Example — a skill with issues. Each check shows a distinct label for its pass/fail state (e.g., "No unknown fields" when passing, "Unknown fields found" when failing):

$ aigent score aigent-validator/
Score: 32/100

Structural (0/60):
  [PASS] SKILL.md exists and is parseable
  [PASS] Name format valid
  [PASS] Description valid
  [PASS] Required fields present
  [FAIL] Unknown fields found
         unexpected metadata field: 'argument-hint'
  [PASS] Body within size limits

Quality (32/40):
  [PASS] Third-person description
  [PASS] Trigger phrase present
  [FAIL] Non-gerund name form
         name does not use gerund form
  [PASS] Specific name
  [PASS] Detailed description

`probe` — Simulate skill activation

Probes whether a skill's description would activate for a given user query. This is a dry-run of skill discovery — "if a user said this, would Claude pick up that skill?"

Uses a weighted formula to compute a match score (0.0–1.0):

0.5 × description overlap — fraction of query tokens in description
0.3 × trigger score — match against trigger phrases ("Use when...")
0.2 × name score — query-to-name token overlap

Categories based on weighted score:

Strong (≥ 0.4) — skill would reliably activate
Weak (≥ 0.15) — might activate, but description could be improved
None (< 0.15) — skill would not activate for this query

Also reports estimated token cost and any validation issues.

$ aigent probe skills/aigent-validator "validate a skill"
Skill: aigent-validator
Query: "validate a skill"
Description: Validates AI agent skill definitions (SKILL.md files) against
the Anthropic agent skill specification. ...

Activation: STRONG ✓ — description aligns well with query (score: 0.65)
Token footprint: ~76 tokens

Validation warnings (1):
  warning: unexpected metadata field: 'argument-hint'

$ aigent probe skills/aigent-validator "deploy kubernetes"
...
Activation: NONE ✗ — description does not match the test query (score: 0.00)
Token footprint: ~76 tokens

`upgrade` — Detect and apply best-practice improvements

Checks for recommended-but-optional fields and patterns. Use --apply to write missing fields into the SKILL.md. The --full flag first runs validate + lint and optionally fixes errors before analysing upgrades.

$ aigent upgrade skills/aigent-validator
Missing 'compatibility' field — recommended for multi-platform skills.
Missing 'metadata.version' — recommended for tracking skill versions.
Missing 'metadata.author' — recommended for attribution.

Run with --apply to apply 3 suggestion(s).

$ aigent upgrade --apply skills/aigent-validator
(applies missing fields in-place, prints confirmation to stderr)

Full mode runs validate + lint first, and with --apply fixes errors before performing upgrades:

$ aigent upgrade --full --apply skills/aigent-validator
[full] Applied 1 validation/lint fix(es)
Missing 'compatibility' field — recommended for multi-platform skills.

`doc` — Generate a skill catalog

Produces a markdown catalog of skills. Use --recursive to discover skills in subdirectories, and --output to write to a file (diff-aware — only writes if content changed).

$ aigent doc skills --recursive
# Skill Catalog

## aigent-builder
> Generates AI agent skill definitions (SKILL.md files) from natural
> language descriptions. ...
**Location**: `skills/aigent-builder/SKILL.md`

---

## aigent-scorer
> Scores AI agent skill definitions (SKILL.md files) against the Anthropic
> best-practices checklist. ...
**Location**: `skills/aigent-scorer/SKILL.md`

---

## aigent-validator
> Validates AI agent skill definitions (SKILL.md files) against the
> Anthropic agent skill specification. ...
**Location**: `skills/aigent-validator/SKILL.md`

---

$ aigent doc skills --recursive --output catalog.md
(writes catalog.md; re-running skips write if content unchanged)

`read-properties` — Output skill metadata as JSON

Parses the SKILL.md frontmatter and outputs structured JSON. Useful for scripting and integration with other tools.

$ aigent read-properties skills/aigent-validator
{
  "name": "aigent-validator",
  "description": "Validates AI agent skill definitions ...",
  "allowed-tools": "Bash(aigent validate *), Bash(command -v *), Read, Glob",
  "metadata": {
    "argument-hint": "[skill-directory-or-file]"
  }
}

`prompt` — Generate XML prompt block

Generates the <available_skills> XML block that gets injected into Claude's system prompt. Accepts multiple skill directories.

$ aigent prompt skills/aigent-validator
<available_skills>
  <skill>
    <name>aigent-validator</name>
    <description>Validates AI agent skill definitions ...</description>
    <location>skills/aigent-validator/SKILL.md</location>
  </skill>
</available_skills>

`new` — Create a skill from natural language

Creates a complete skill directory with SKILL.md from a purpose description. Uses LLM when an API key is available, or --no-llm for deterministic mode.

$ aigent new "Extract text from PDF files" --no-llm
Created skill 'extracting-text-pdf-files' at extracting-text-pdf-files

The generated SKILL.md includes derived name, description, and a starter body:

---
name: extracting-text-pdf-files
description: Extract text from PDF files. Use when working with files.
---
# Extracting Text Pdf Files

## Quick start
Extract text from PDF files

## Usage
Use this skill to Extract text from PDF files.

`fmt` — Format SKILL.md files

Normalizes SKILL.md files with canonical YAML key ordering, consistent whitespace, and clean formatting. The operation is idempotent — running it twice produces no further changes.

$ aigent fmt my-skill/
Formatted my-skill/

Check mode reports which files would change without modifying them:

$ aigent fmt --check my-skill/
Would reformat: my-skill/

`build` — Assemble skills into a plugin

Packages one or more skill directories into a Claude Code plugin directory with a plugin.json manifest, skills/ subdirectory, and scaffolded agents/ and hooks/ directories.

$ aigent build skills/aigent-validator skills/aigent-scorer --output ./dist
Assembled 2 skill(s) into ./dist

The output structure:

dist/
├── plugin.json
├── skills/
│   ├── aigent-validator/
│   │   └── SKILL.md
│   └── aigent-scorer/
│       └── SKILL.md
├── agents/
└── hooks/

`test` — Run fixture-based test suites

Runs test suites defined in tests.yml files alongside skills. Each test case specifies an input query, whether it should match, and an optional minimum score threshold.

Generate a starter tests.yml:

$ aigent test --generate my-skill/
Generated my-skill/tests.yml

Run the test suite:

$ aigent test my-skill/
[PASS] "process pdf files" (score: 0.65)
[PASS] "something completely unrelated to this skill" (score: 0.00)

2 passed, 0 failed, 2 total

`init` — Create a template SKILL.md

Scaffolds a skill directory with a template SKILL.md ready for editing.

$ aigent init my-skill
Created my-skill/SKILL.md

$ cat my-skill/SKILL.md
---
name: my-skill
description: Describe what this skill does and when to use it
---

# My Skill

## Quick start
[Add quick start instructions here]

## Usage
[Add detailed usage instructions here]

Watch mode

The --watch flag on validate monitors skill directories for filesystem changes and re-validates automatically on each edit — a live feedback loop while developing skills.

Watch mode is behind a Cargo feature gate because it pulls in platform-specific filesystem notification libraries (notify, fsevent-sys on macOS, inotify on Linux). Without the feature, the binary is smaller and has fewer dependencies.

Building with watch mode:

# Build with watch support
cargo build --release --features watch

# Run with watch support (--features must be passed every time)
cargo run --release --features watch -- validate --watch skills/

# Or install with watch support
cargo install aigent --features watch

Note: Cargo feature flags are per-invocation — they are not remembered between builds. You must pass --features watch on every cargo build or cargo run invocation. Building debug with --features watch does not enable it for release builds, and vice versa.

Without the watch feature, using --watch prints a helpful error:

$ aigent validate --watch my-skill/
Watch mode requires the 'watch' feature. Rebuild with: cargo build --features watch

Global Flags

API Reference

Full Rust API documentation with examples is published at docs.rs/aigent.

Types

Type	Module	Description
`SkillProperties`	`models`	Parsed skill metadata (name, description, licence, compatibility, allowed-tools)
`SkillSpec`	`builder`	Input specification for skill generation (purpose, optional overrides)
`BuildResult`	`builder`	Build output (properties, files written, output directory)
`ClarityAssessment`	`builder`	Purpose clarity evaluation result (clear flag, follow-up questions)
`Diagnostic`	`diagnostics`	Structured diagnostic with severity, code, message, field, suggestion
`ScoreResult`	`scorer`	Quality score result with structural and semantic categories
`TestResult`	`tester`	Skill activation probe result (query match, score, diagnostics, token cost)
`TestSuiteResult`	`test_runner`	Fixture-based test suite result (passed, failed, per-case results)
`FormatResult`	`formatter`	SKILL.md formatting result (changed flag, formatted content)
`AssembleOptions`	`assembler`	Options for skill-to-plugin assembly (output dir, name, validate)
`AssembleResult`	`assembler`	Assembly output (plugin directory, skill count)
`SkillEntry`	`prompt`	Collected skill entry for prompt generation (name, description, location)
`AigentError`	`errors`	Error enum: `Parse`, `Validation`, `Build`, `Io`, `Yaml`
`Result<T>`	`errors`	Convenience alias for `std::result::Result<T, AigentError>`

Functions

Function	Module	Description
`validate(&Path) -> Vec<Diagnostic>`	`validator`	Validate skill directory
`validate_with_target(&Path, ValidationTarget)`	`validator`	Validate with target profile
`read_properties(&Path) -> Result<SkillProperties>`	`parser`	Parse directory into `SkillProperties`
`find_skill_md(&Path) -> Option<PathBuf>`	`parser`	Find `SKILL.md` in directory (prefers uppercase)
`parse_frontmatter(&str) -> Result<(HashMap, String)>`	`parser`	Split YAML frontmatter and body
`to_prompt(&[&Path]) -> String`	`prompt`	Generate `<available_skills>` XML system prompt
`to_prompt_format(&[&Path], PromptFormat) -> String`	`prompt`	Generate prompt in specified format
`lint(&SkillProperties, &str) -> Vec<Diagnostic>`	`linter`	Run semantic quality checks
`score(&Path) -> ScoreResult`	`scorer`	Score skill against best-practices checklist
`test_skill(&Path, &str) -> Result<TestResult>`	`tester`	Probe skill activation against a query
`format_skill(&Path) -> Result<FormatResult>`	`formatter`	Format SKILL.md with canonical key order
`format_content(&str) -> Result<String>`	`formatter`	Format SKILL.md content string
`assemble_plugin(&[&Path], &AssembleOptions) -> Result<AssembleResult>`	`assembler`	Assemble skills into a plugin
`run_test_suite(&Path) -> Result<TestSuiteResult>`	`test_runner`	Run fixture-based test suite
`generate_fixture(&Path) -> Result<String>`	`test_runner`	Generate starter `tests.yml` from skill metadata
`validate_structure(&Path) -> Vec<Diagnostic>`	`structure`	Validate directory structure
`detect_conflicts(&[SkillEntry]) -> Vec<Diagnostic>`	`conflict`	Detect cross-skill conflicts
`apply_fixes(&Path, &[Diagnostic]) -> Result<usize>`	`fixer`	Apply automatic fixes
`build_skill(&SkillSpec) -> Result<BuildResult>`	`builder`	Full build pipeline with post-build validation
`derive_name(&str) -> String`	`builder`	Derive kebab-case name from purpose (deterministic)
`assess_clarity(&str) -> ClarityAssessment`	`builder`	Evaluate if purpose is clear enough for generation
`init_skill(&Path, SkillTemplate) -> Result<PathBuf>`	`builder`	Initialize skill directory with template SKILL.md

Traits

Trait	Module	Description
`LlmProvider`	`builder::llm`	Text generation provider interface (`generate(system, user) -> Result<String>`)

Claude Code Plugin

This repository is a Claude Code plugin. It provides three skills that Claude can use to build, validate, and score SKILL.md files interactively.

Skills

Skill	Description
`aigent-builder`	Generates skill definitions from natural language. Triggered by "create a skill", "build a skill", etc.
`aigent-validator`	Validates skills against the Anthropic specification. Triggered by "validate a skill", "check a skill", etc.
`aigent-scorer`	Scores skills against best-practices checklist. Triggered by "score a skill", "rate a skill", etc.

All skills operate in hybrid mode: they use the aigent CLI when it is installed, and fall back to Claude-based generation/validation when it is not. This means the plugin works out of the box — no installation required — but produces higher-quality results with aigent available.

Plugin installation

To use the plugin in Claude Code, add it to your project's .claude/settings.json:

{
  "permissions": {
    "allow": []
  },
  "plugins": [
    "wkusnierczyk/aigent"
  ]
}

Development

Prerequisites

Rust (stable toolchain)
cargo (included with Rust)

Setup

git clone https://github.com/wkusnierczyk/aigent.git
cd aigent
cargo build

Optional tooling

cargo install cargo-edit            # Adds `cargo set-version` for release versioning

Common tasks

cargo build                         # Build (debug)
cargo build --release               # Build (release)
cargo test                          # Run all tests
cargo clippy -- -D warnings         # Lint (warnings as errors)
cargo fmt                           # Format code
cargo fmt --check                   # Check formatting

Project structure

src/
├── lib.rs                          # Library root — re-exports public API
├── errors.rs                       # Error types (thiserror)
├── models.rs                       # SkillProperties (serde)
├── parser.rs                       # SKILL.md frontmatter parser (serde_yaml_ng)
├── validator.rs                    # Metadata and directory validator
├── linter.rs                       # Semantic lint checks
├── fixer.rs                        # Auto-fix for fixable diagnostics
├── diagnostics.rs                  # Structured diagnostics with error codes
├── prompt.rs                       # Multi-format prompt generation
├── scorer.rs                       # Quality scoring with pass/fail labels (0–100)
├── structure.rs                    # Directory structure validation
├── conflict.rs                     # Cross-skill conflict detection
├── tester.rs                       # Skill activation probe with weighted scoring
├── formatter.rs                    # SKILL.md formatting (canonical key order, whitespace)
├── assembler.rs                    # Skill-to-plugin assembly
├── test_runner.rs                  # Fixture-based testing (tests.yml)
├── main.rs                         # CLI entry point (clap)
└── builder/
    ├── mod.rs                      # Build pipeline orchestration
    ├── deterministic.rs            # Heuristic name/description/body generation
    ├── llm.rs                      # LLM provider trait and generation functions
    ├── template.rs                 # Template for init command
    ├── util.rs                     # Internal utilities
    └── providers/
        ├── mod.rs                  # Provider module declarations
        ├── anthropic.rs            # Anthropic Claude API
        ├── openai.rs               # OpenAI (and compatible) API
        ├── google.rs               # Google Gemini API
        └── ollama.rs               # Ollama local API

Versioning

Version is stored in Cargo.toml (single source of truth) and read at compile time via env!("CARGO_PKG_VERSION").

Milestones

Status: Implementation complete (M1–M13). In review.

Project tracked at github.com/users/wkusnierczyk/projects/39.

Milestone	Title	Status
M1	Project Scaffolding	✅
M2	Errors and Models	✅
M3	Parser	✅
M4	Validator	✅
M5	Prompt	✅
M6	CLI	✅
M7	Builder	✅
M8	Main Module and Documentation	✅
M9	Claude Code Plugin	✅
M10	Improvements and Extensions	✅
M11	Builder and Prompt Enhancements	✅
M12	Ecosystem and Workflow	✅
M13	Enhancements	✅
M14	SRE Review	🔲
M15	Plugin Ecosystem Validation	🔲

Roadmap

M14: SRE Review — security, reliability, and performance hardening prior to publication. Addresses symlink following, path traversal, uncapped file reads, silent error swallowing, TOCTOU races, and O(n²) conflict detection. 10 issues (#87–#96).

M15: Plugin Ecosystem Validation — extend aigent's deterministic validation from SKILL.md to the full Claude Code plugin ecosystem. Complements plugin-dev by mechanizing the rules it teaches through prose and LLM-driven agents:

Hook validation (hooks.json) — replaces plugin-dev's validate-hook-schema.sh
Agent file validation (.md frontmatter) — replaces plugin-dev's validate-agent.sh
Plugin manifest validation (plugin.json) — mechanizes plugin-validator agent checks
Command file validation (.md frontmatter) — first deterministic validator for commands
Cross-component consistency checks — unique to aigent, no plugin-dev equivalent

5 issues (#97–#101). See dev/plugin-dev.md for the full analysis.

CI/CD and Release Workflows

Continuous integration

Every push to main and every pull request runs the CI pipeline on a three-OS matrix (Ubuntu, macOS, Windows):

Formatting — cargo fmt --check
Linting — cargo clippy -- -D warnings
Testing — cargo test
Release build — cargo build --release

Release workflow

Pushing a version tag (e.g., v0.1.0) triggers the release workflow:

Test — full test suite on Ubuntu
Build — cross-compile for five targets:
- x86_64-unknown-linux-gnu
- aarch64-unknown-linux-gnu (via cross)
- x86_64-apple-darwin
- aarch64-apple-darwin
- x86_64-pc-windows-msvc
Release — create GitHub Release with changelog and binary assets
Publish — publish to crates.io

References

Reference	Description
Anthropic agent skill specification	Official specification for SKILL.md format and validation rules
Agent Skills organisation	Umbrella for agent skills tooling
agentskills/agentskills	Python reference implementation
anthropics/skills	Anthropic's skills repository
docs.rs/aigent	Rust API documentation
crates.io/crates/aigent	Package registry

About and Licence

aigent: Rust AI Agent Skills Tool
├─ version:    0.3.0
├─ author:     Wacław Kuśnierczyk
├─ developer:  mailto:waclaw.kusnierczyk@gmail.com
├─ source:     https://github.com/wkusnierczyk/aigent
└─ licence:    MIT https://opensource.org/licenses/MIT

MIT — see opensource.org/licenses/MIT.

Table of Contents

Installation

Prerequisites

From crates.io

From source

Pre-built binaries

Install script (Linux and macOS)

Quick Start

Library Usage

SKILL.md Format

Frontmatter fields

Validation rules

Builder Modes

Provider detection order

Available models (as of 2026-02-20)

Compliance

Specification Coverage

aigent vs. plugin-dev

Extras

CLI Reference

Commands

Validate Flags

Check Flags

New Flags

Fmt Flags

Build (Assembly) Flags

Test Flags

Upgrade Flags

Command Examples

validate — Check skill directories for spec conformance

check — Validate + semantic quality checks

score — Rate a skill 0–100

probe — Simulate skill activation

upgrade — Detect and apply best-practice improvements

doc — Generate a skill catalog

read-properties — Output skill metadata as JSON

prompt — Generate XML prompt block

new — Create a skill from natural language

fmt — Format SKILL.md files

build — Assemble skills into a plugin

test — Run fixture-based test suites

init — Create a template SKILL.md

Watch mode

Global Flags

API Reference

Types

Functions

Traits

Claude Code Plugin

Skills

Plugin installation

Development

Prerequisites

Setup

Optional tooling

Common tasks

Project structure

Versioning

Milestones

Roadmap

CI/CD and Release Workflows

Continuous integration

Release workflow

References

About and Licence

`validate` — Check skill directories for spec conformance

`check` — Validate + semantic quality checks

`score` — Rate a skill 0–100

`probe` — Simulate skill activation

`upgrade` — Detect and apply best-practice improvements

`doc` — Generate a skill catalog

`read-properties` — Output skill metadata as JSON

`prompt` — Generate XML prompt block

`new` — Create a skill from natural language

`fmt` — Format SKILL.md files

`build` — Assemble skills into a plugin

`test` — Run fixture-based test suites

`init` — Create a template SKILL.md