agentskill-kit

agentskill-kit is a command line toolkit for agent skills, the SKILL.md folders that coding agents such as
Claude Code, Cursor, Codex, Gemini CLI and Hermes load when a task matches. It checks a skill before you trust it,
generates new ones, and installs the same skill into every agent you use.

• Lint a skill: name, description, structure. Works offline.
• Scan it for prompt injection, hidden unicode, secrets and dangerous commands.
• Test it: run the tests that ship with the skill in an isolated folder.
• Forge a new skill from a task description with any model, including free and local ones.
• Mine your shell history for routines that should be skills.
• Export one skill to Claude Code, Cursor, Windsurf, Copilot, Codex and Gemini CLI.
• Share skills through a static registry with checksums and a searchable website.

No runtime dependencies. No paid service required. Python 3.9 or newer on Linux, macOS and Windows.

Install

pip install agentskill-toolkit

The PyPI package is named agentskill-toolkit (the shorter name was not available). It installs the askit command and the longer alias agentskill. The repository, the Python module (agentskill_kit) and the commands keep the agentskill-kit name.

Quick start

Check a skill without any API key:

askit lint skills/my-skill
askit scan skills/my-skill
askit test skills/my-skill
askit score skills/my-skill

Create one with a free model (a local Ollama model, or a Groq or Gemini key on the free tier):

askit forge --task "turn meeting notes into action items with owners and due dates"

Use it in your agents:

askit export skills/meeting-notes-to-actions --target claude
askit export skills/meeting-notes-to-actions --target cursor
askit export skills/meeting-notes-to-actions --target all

Install something from the community registry:

askit search docker
askit install dockerfile-linter

Try everything offline with the built-in demo model: askit forge --task "anything" --provider mock.

Why this exists

Skills are plain text that an agent obeys, so they deserve the same care as code you run: a review, a linter, a
test and a look at what they do. At the same time every agent wants a slightly different file layout, and writing
good skills by hand is slow. agentskill-kit covers both: quality gates for skills, and tools that do the tedious
parts.

Commands

Every command has --help. Add --lang tr for a Turkish interface.

Free first, paid optional

askit providers shows what is ready. Details in docs/providers.md.

forge does not rely on tool calling. The loop is controlled by code, so small local models work. The model only
writes files; lint, scan and tests decide whether they are good enough.

How forge decides

task or notes
      |
      v
  model drafts SKILL.md, scripts and tests/cases.json
      |
      v
  lint + scan + run tests in a clean folder  ->  score
      |                                           |
      |  below threshold: failures go back        |  at or above threshold,
      |  to the model (up to 3 rounds)            |  no high findings
      v                                           v
  best attempt kept                          written to skills/<name>/

The score is not the model's opinion. It comes from real checks.
Nothing is written when the best attempt misses the threshold, unless you pass --force.

Mine your history

$ askit mine --file examples/shell-history-sample.txt
-- read 20 commands
Found 1 repeated workflow(s)

#1  git-status-add-commit  (4x)
     git status
     git add -A
     git commit -m <str>
     git push origin main

$ askit mine --file examples/shell-history-sample.txt --draft 1

Secrets are masked before anything is shown. See docs/mining.md.

Export targets

Exports are repeatable: managed blocks are replaced, not duplicated. More in docs/export-targets.md.

Starter skills

The registry ships 16 skills that pass every check. Nine of them include scripts with tests, so you can read how a
tested skill is built.

Browse them on the registry website, or run askit search and askit install NAME.

Use it in CI

- uses: Lethe044/agentskill-kit@main
  with:
    path: skills
    strict: "true"
    scan-fail-on: medium

Also available as a pre-commit hook. See docs/github-action.md.

Use it from Python

from agentskill_kit.lint import lint_skill
from agentskill_kit.scan import scan_skill
from agentskill_kit.scoring import evaluate_skill

quality = evaluate_skill("skills/log-analyzer")
print(quality.score, quality.grade, quality.passes_gate)

for issue in lint_skill("skills/log-analyzer").issues:
    print(issue.code, issue.message)

print(scan_skill("skills/log-analyzer").verdict)

Security notes

• The scanner is a heuristic filter, not a guarantee. Read skills from sources you do not trust.
• askit test isolates the working directory and environment and limits time and memory, but it is not a sandbox.
  Use a container for untrusted skills.
• Registry downloads are verified against checksums, linted and scanned before installation.

Details in docs/security.md and SECURITY.md.

Hermes Agent

This project began as a Hermes Agent hackathon prototype. Hermes remains a first class target
(askit export --target hermes) and integrations/hermes/ holds the skill-forge playbook and an Atropos
training environment whose reward can use verified scores. See integrations/hermes.

Documentation

• Getting started
• Skill format, tests and scoring
• Providers
• Security model
• Export targets
• Registry and publishing
• Mining shell history
• GitHub Action and pre-commit

Roadmap

• More scanner rules and a community rule pack.
• Translated rule messages (the interface is already available in Turkish and English).
• askit eval with a judge model for open ended checks.
• Skill dependencies and version constraints in the registry.
• Export targets for more agents.

Ideas and pull requests are welcome. See CONTRIBUTING.md for how to add a skill in a few minutes.

License

MIT