aigent: toolchain for AI agent skills
AI Agent Skills: The New Packaging Layer
AI agents are getting good at following instructions. The bottleneck has shifted: it’s no longer about what the model can do, but about how well you package what it should do. That packaging layer is agent skills — structured documents that tell an agent what a capability does, when to activate it, and how to use it.
The Agent Skills Open Standard
The Agent Skills open standard, originally defined by Anthropic for Claude Code, codifies this idea into a simple, discoverable format:
SKILL.md
├── YAML front‑matter
│ - name
│ - description
│ - compatibility
│ - allowed tools
└── Markdown body
- detailed instructions- Metadata (YAML front‑matter) is indexed at session start for fast discovery.
- Body (Markdown) is loaded on demand, following a progressive‑disclosure pattern that keeps the context window lean.
Why It Matters
- Scalability: The format is trivial, but applying it consistently at scale can be challenging.
- Efficiency: Only the necessary parts of a skill are loaded, preserving token budget for actual reasoning.
- Interoperability: A common schema lets different agents and toolchains share skills without custom adapters.
In short, the real power of modern AI agents lies not just in the models themselves, but in how we describe and expose their capabilities through well‑structured, discoverable skill documents.
The Problem
When you have a handful of skills, you can eyeball them. When you have dozens—across teams, repositories, and CI pipelines—you need tooling.
- Names drift from conventions.
- Descriptions become vague.
- Activation patterns go untested.
- Formatting diverges.
Nobody catches the skill that fails to trigger because its description doesn’t match the query patterns users actually type.
The specification defines what a valid skill looks like. The Python reference implementation provides basic validation, but it’s a library—not a toolchain you can drop into CI, pre‑commit hooks, or a plugin‑build pipeline.
What aigent does
aigent is a Rust library, native CLI, and Claude Code plugin that implements the Agent Skills specification as a full‑featured toolchain—much like a formatter, linter, and test runner do for any mature language ecosystem.
It covers the entire skill lifecycle:
| Stage | Description |
|---|---|
| Create | Generate skills from natural language with aigent new. Deterministic by default, with optional LLM enhancement (Anthropic, OpenAI, Google, Ollama back‑ends). Produces a complete SKILL.md directory ready for validation and refinement. |
| Validate | Check skills against the specification with typed diagnostics, error codes, and JSON output. Run aigent validate in CI to catch problems before they reach production. Three severity levels (error, warning, info) and a --format json flag for machine consumption. |
| Format | Canonical YAML key ordering, consistent whitespace, idempotent output. aigent format --check returns a non‑zero exit code when files need formatting—perfect for a pre‑commit hook. |
| Score | Compute a weighted 0‑100 quality score against a best‑practices checklist. Structural checks (60 pts) verify specification conformance; quality checks (40 pts) evaluate description clarity, trigger phrases, naming conventions, and detail. Use it as a CI gate: `aigent score my-skill/ |
| Test | Fixture‑based testing from tests.yml. Define input queries, expected match/no‑match results, and minimum score thresholds. aigent test runs the suite and reports pass/fail. aigent probe performs single‑query dry‑runs: “if a user said this, would the agent pick up that skill?” |
| Build | Assemble skills into Claude Code plugins with aigent build. Validate entire plugin directories—manifest, hooks, agents, commands, skills, and cross‑component consistency—using aigent validate-plugin. |
Specification compliance
aigent implements every validation rule from the Anthropic specification, plus additional checks that go beyond both the specification and the Python reference implementation:
- Name constraints
- Length
- Casing
- Reserved words
- XML tags
- Unicode NFKC normalization
- Description constraints
- Length
- Non‑empty
- No XML/HTML
- Front‑matter
- Structure
- Delimiter matching
- Compatibility field limits
- Body‑length warnings
- Path handling
- Canonicalization
- Symlink safety
- Post‑build validation
When the specification and the reference implementation diverge, aigent reconciles the differences and documents the decision. See the compliance section in the README for a detailed three‑way comparison.
Beyond Individual Skills
Skills don’t exist in isolation. As your collection grows, new problems emerge:
- Name collisions – two skills with the same identifier.
- Overlapping descriptions – ambiguous wording that confuses activation.
- Token‑budget overruns – total token usage exceeds the model’s context limit.
aigent addresses these issues with:
| Feature | What it does |
|---|---|
| Cross‑skill conflict detection | Finds duplicate names and overlapping triggers. |
| Token‑budget estimation | Calculates the combined token cost of all active skills and warns when it exceeds limits. |
| Batch validation | Validates every skill in a directory tree in one run. |
Full‑Plugin Validation
A Claude Code plugin consists of more than just skills. The aigent validate‑plugin command checks the entire ecosystem:
plugin.jsonmanifesthooks.jsonconfiguration- Agent files (
*.agent.js/*.agent.ts) - Command files (
*.cmd.js/*.cmd.ts) - Skill subdirectories (each containing a
skill.json) - Cross‑component consistency (e.g., referenced hooks actually exist)
Typed Diagnostics
Errors are reported with deterministic codes, making it easy to automate fixes or filter messages.
| Category | Code Range | Area |
|---|---|---|
| Manifest | P001 – P010 | plugin.json validation |
| Hooks | H001 – H007 | hooks.json validation |
| Cross‑component | X001 – X008 | Consistency between manifest, hooks, agents, commands, and skills |
Example output
X003: Skill "summarize" references hook "onMessage" which is not defined in hooks.json.
P007: plugin.json missing required field "version".
H002: hooks.json contains duplicate hook name "onStart".These diagnostics give you a clear, programmatic way to enforce correctness across the whole plugin structure.
Where It Fits
The agentic AI ecosystem is moving fast. Tools like Anthropic’s plugin‑dev teach you the patterns, while aigent enforces them. Think of it as the difference between a language tutorial and a linter—you need both, but they serve different purposes.
Other tools in the space, such as AI Agent Skills, focus on distribution—installing pre‑built skills across multiple agents. In contrast, aigent focuses on authoring quality, ensuring that what you publish is correct, consistent, and maintainable.
Get started
# Install
cargo install aigent # official distribution at crates.io
brew install wkusnierczyk/aigent/aigent # Homebrew tap
# Create, validate, score
aigent new "process PDF files and extract text" --no-llm
aigent check extracting-text-pdf-files/
aigent score extracting-text-pdf-files/About
$ aigent --about
aigent: Rust AI Agent Skills Tool
├─ version: 0.6.3
├─ author: Wacław Kuśnierczyk
├─ developer: mailto:waclaw.kusnierczyk@gmail.com
├─ source: https://github.com/wkusnierczyk/aigent
└─ licence: Apache-2.0 https://www.apache.org/licenses/LICENSE-2.0License
This project is licensed under the Apache License 2.0.
You can view the full license text at the Apache website: https://www.apache.org/licenses/LICENSE-2.0.
Reference
- Sources: (add source links or descriptions here)
- Releases: (add release information or version numbers here)
- Crates: (add crate names or links here)
- Docs: (add documentation URLs or references here)