Agentskill

Turn any codebase into an AGENTS.md playbook AI coding agents can actually follow.

• For Agents
• Installation
• Usage
• Choosing a Command
• What It Does
• How It Works
• Supported Languages
• Generation Modes
• AGENTS.md Output
• Development Checks
• Maintainer Context
• Repository Layout
• Where Code Goes
• Developer Workflow
• File Ecosystem
• Examples
• API Reference
• Contributing
• Security
• Releases
• Support
• License

Copy this prompt into your coding agent to install and use Agentskill in the current repository:

Install and use Agentskill for this repository.

1. Check whether `agentskill` or `agsk` is available. If neither is installed,
   install it with:

   cargo install --git https://github.com/airscripts/agentskill agentskill

   If this is the Agentskill source checkout, use this local install instead:

   cargo install --path agentskill --locked --force

2. Discover guidance boundaries and collect evidence:

   agentskill scopes "$PWD" --pretty
   agentskill evidence "$PWD" --pretty

3. Read the Agentskill skill instructions, inspect the relevant repository
   files, and use the evidence to create or update the appropriate AGENTS.md
   files. Preserve existing maintainer instructions and keep guidance concise
   and repository-specific.

4. Validate the result:

   agentskill validate "$PWD" --signature auto
   agentskill drift "$PWD" --signature auto

Summarize the evidence used, files changed, validation result, and any
remaining uncertainty. The Agentskill CLI is deterministic and read-only; the
coding agent authors the semantic Markdown.

Download a release archive from GitHub Releases, extract it, and put either agentskill or agsk on your PATH. Verify downloads with the release's SHA256SUMS file.

For a source checkout, install the binaries with Cargo:

cargo install --git https://github.com/airscripts/agentskill agentskill

For local development, reinstall the binaries from the checkout after making changes:

cargo install --path agentskill --locked --force

Both binary names are built from the workspace. agsk is an equivalent short name for agentskill.

Start with the help banner:

agentskill --help

Run all analyzers and emit normalized evidence:

agentskill analyze <repo> --pretty
agentskill evidence <repo> --pretty

Other common commands:

agentskill scopes <repo> --pretty
agentskill scan <repo> --pretty
agentskill measure <repo> --lang rust --pretty
agentskill validate <repo> --signature auto
agentskill drift <repo> --signature auto
agentskill version

Use agsk in place of agentskill for every command. --pretty formats JSON, and --out FILE writes JSON to a relative output file. The CLI never writes semantic Markdown.

Use analyze for all analyzers, evidence for compact LLM-ready facts, and an individual analyzer such as scan, measure, or tests when you need a focused signal. Use scopes to discover nested guidance boundaries.

After the LLM skill writes AGENTS.md, run validate for strict checks and drift for advisory freshness and evidence reporting. See the agentskill-docs/cli.md reference for the complete command surface.

agentskill is not a linter or a generic style-guide generator. It is a forensic extraction tool. It walks a repository, measures source conventions, reads formatter and linter configuration, inspects Git history, and analyzes imports, symbols, and tests. It then emits structured evidence for an LLM.

The LLM skill uses that evidence to author compact, repository-specific AGENTS.md guidance.

Seven analyzers run independently and their results are combined in a stable JSON shape:

The evidence contract and LLM output rules are documented in agentskill-skill/SYSTEM.md. The seven analyzers are implemented in Rust and run in parallel where the workspace can safely do so.

Read the technical background: Turning Repository Knowledge Into Usable Agent Context.

The analyzer matrix and the example fixtures cover 60 language families:

• Python
• TypeScript
• JavaScript
• Go
• Rust
• Java
• Kotlin
• C#
• C
• C++
• Ruby
• PHP
• Swift
• Objective-C
• Shell / Bash
• Dart
• Scala
• Elixir
• Erlang
• Lua
• R
• Julia
• Haskell
• Clojure
• F#
• Groovy
• PowerShell
• Visual Basic .NET
• Zig
• D
• Nim
• Crystal
• OCaml
• Perl
• MATLAB
• Fortran
• Ada
• GDScript
• Solidity
• HTML
• Vue
• Svelte
• Astro
• CSS
• Sass / SCSS
• Less
• SQL
• GraphQL
• Protocol Buffers
• HCL / Terraform
• Nix
• Dockerfile
• Make
• CMake
• Starlark

YAML, JSON, TOML, XML, and Markdown are detected as auxiliary formats. They appear under the analyzer auxiliary object and are excluded from dominant language summaries and generated language guidance.

The .m extension is ambiguous between MATLAB and Objective-C. Content and repository markers are used when available; otherwise static detection favors Objective-C. Use --lang matlab when analyzing marker-free MATLAB files.

These are target languages. agentskill itself is implemented and shipped entirely in Rust. The fixtures under agentskill-skill/examples/ provide compact single-language, mixed-language, and monorepo shapes for regression coverage.

The repository also contains a complete skill package in agentskill-skill/. An agent harness can install that directory as a skill, run the evidence command, read SYSTEM.md, and author the final AGENTS.md itself. Semantic Markdown generation happens through the LLM skill rather than the Rust CLI.

The skill supports init, enrich, scope, update, and audit workflows. operational output is the compact root document; reference output is deeper context loaded only when needed.

Install Rust through rustup and Lefthook with cargo install lefthook, then enable the repository hooks:

lefthook install

The minimum supported Rust version is 1.89. The canonical verification command is:

make verify

After changing the CLI, reinstall the development binaries from this checkout with:

cargo install --path agentskill --locked --force

This runs locked linting and compilation, the complete workspace test suite, and workflow/script validation. Individual targets are available when iterating:

make build       # release binaries
make check       # cargo check --workspace --locked
make fmt         # cargo fmt --all
make lint        # clippy with -D warnings
make test        # cargo test --workspace --locked
make coverage    # llvm-cov with the 80% line threshold
make security    # cargo-deny dependency policy checks
make workflows   # actionlint and shellcheck

Cargo.lock is committed so local and CI builds use reproducible dependency resolution. Optional staged-file checks are configured through lefthook.yml and agentskill-scripts/pre-commit.sh.

The skill writes two optional depth views from the same evidence:

• AGENTS.md is the compact operational contract. Keep it self-sufficient, imperative, and normally within 500–1,000 tokens; treat 1,500 as a hard ceiling.
• AGENTS.reference.md is unrestricted supporting context: architecture, rationale, evidence details, workflows, and examples that an agent can load selectively. The root file links to it when it exists.

The root document should prioritize repository mission and map, non-negotiable rules, conceptual don'ts, quick-start commands, change routing, architecture, testing, and only the most useful playbooks. It should state verified facts as rules, avoid raw analyzer dumps, and omit uncertain conventions. The reference document can preserve depth without spending every agent's context window.

When a reference document exists, it must include visible provenance and decision fields so drift checks can compare its evidence revision with the current repository.

The LLM skill is responsible for init, enrich, scope, update, audit, and explain. The CLI remains deterministic and read-only: evidence supplies facts, while validate and drift check the documents after the skill writes them.

Durable maintainer answers belong in the repository's normal review flow or in the reference document, not in a CLI feedback sidecar. During generation the skill should ask only high-impact questions that static evidence cannot answer, record the resulting decision in the appropriate document, and distinguish maintainer policy from repository observation.

README.md                 # user-facing overview and contributor workflow
AGENTS.md                 # conventions for this repository itself
Cargo.toml                # Rust workspace definition
Cargo.lock                # reproducible dependency resolution
agentskill-core/          # shared types, filesystem, language registry
agentskill-analyzers/     # seven analyzers and aggregate execution
agentskill-generation/    # validation and evidence/document drift checks
agentskill/               # Clap CLI and agentskill/agsk binaries
agentskill-skill/         # skill instructions, references, and examples
agentskill-scripts/       # release and archive verification helpers
agentskill-docs/          # CLI and architecture references
agentskill-assets/        # repository artwork
agentskill-tests/         # compatibility and guidance fixtures
.github/                  # CI, release workflows, and issue templates

• Put shared domain types, filesystem behavior, errors, and language detection in agentskill-core/.
• Put analyzer implementations and aggregate execution in agentskill-analyzers/.
• Put document validation and evidence/document drift checks in the agentskill-generation/ package (published as agentskill-validation).
• Keep agentskill/src/main.rs thin; route CLI behavior through the library crates and expose both binaries from agentskill/.
• Keep agentskill-scripts/ limited to release, archive, and operator helpers; do not put analyzer or validation logic there.
• Keep target-language fixtures under agentskill-skill/examples/ and Rust contract or guidance fixtures under agentskill-tests/.

Do not reintroduce Python runtime code, package setup, or Python CI workflows. Python fixtures remain supported because Python is one of the analyzed target languages.

For a normal change:

1. Read AGENTS.md, the owning crate, and the relevant contract tests.
2. Keep public behavior deterministic: stable section ordering, sorted paths, and reproducible JSON values.
3. Add unit or integration coverage in the owning crate.
4. Update user-facing docs and CHANGELOG.md when a public command, flag, output key, or generated-document behavior changes.
5. Run make fmt, then make verify before opening a pull request.

Public command names, flags, analyzer keys, error payloads, supported target languages, evidence fields, and document validation semantics are compatibility surfaces.

Read these files together before changing evidence or document behavior:

agentskill-skill/examples/README.md indexes compact fixtures for every supported target language and reference context examples for single-language, multi-language, and monorepo repositories. They are used by analyzer coverage and contract tests, and are useful when checking how language detection or test mapping behaves.

Try one locally:

agentskill analyze agentskill-skill/examples/python --pretty
agentskill scan agentskill-skill/examples/typescript --pretty
agentskill evidence agentskill-skill/examples/mixed --pretty

Contributor-oriented documentation lives under agentskill-docs/:

• cli.md describes commands, flags, and output.
• architecture.md describes crate responsibilities, evidence contracts, validation, and release flow.

The Rust crates are the implementation source of truth; the docs summarize their public boundaries without exposing every private helper.

Contributions are welcome, especially improvements to analyzer depth, evidence quality, supported-language fixtures, compatibility contracts, and skill ergonomics. Before opening a pull request, read CONTRIBUTING.md and CODE_OF_CONDUCT.md. Use the repository issue and pull request templates when reporting bugs or proposing changes.

See SECURITY.md for supported versions and vulnerability reporting guidance. Dependency policy is checked with cargo deny and the release workflow validates archives before publishing them.

Releases are tag-driven and automated through GitHub Actions. Stable tags use X.Y.Z; prereleases use X.Y.Z-rc.N. The workflow validates the tag against VERSION, extracts stable notes from the matching CHANGELOG.md section, runs locked verification and the full test matrix, builds six platform archives containing both binaries plus LICENSE, generates SHA256SUMS, and publishes the GitHub Release.

• GitHub Sponsors
• Ko-fi

Bug reports and feature requests belong in the repository's issue tracker. Starring, sharing, contributing fixes, and supporting the project all help.

MIT. See LICENSE.