AgentSkills CI
damanisme/agentskills-ci
CI/CD para skills de IA com validação, testes e scoring automático
Ver no GitHubFerramenta CLI e GitHub Action para validar, testar, pontuar e empacotar skills de IA/Claude com a mesma disciplina de qualidade usada em software real. Detecta padrões perigosos em shell, valida estrutura SKILL.md, verifica referências de arquivos e gera relatórios em múltiplos formatos.
Instalação
npx convez-ai damanisme/agentskills-ci1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Validar qualidade de skills Claude antes de deploy
- Detectar padrões perigosos (rm -rf, curl | bash) em instruções
- Integrar verificação de skills em workflows GitHub Actions
- Gerar badges de score e relatórios de qualidade
Veredito

Ferramenta madura e bem-estruturada que trata skills de IA como artefatos de software legítimos. Preenche um gap real de QA/CI para o ecossistema Claude, com validação robusta de segurança e estrutura.
README
A tradução para o português deste README ainda está na fila.
agentskills-ci
Test, lint, score, and package Claude/Hermes/AI-agent skills like real software.
Claude Skills and agent workflows are becoming reusable software artifacts, but most teams still ship them as loose prompt files. No CI. No tests. No linked-file checks. No safety scan. No quality score.
agentskills-ci gives AI-agent skills the same quality discipline teams expect from code.
Demo
Score a whole skills directory in one command — pass on the good, fail on the dangerous:
$ agentskills-ci score ./skills
⚠️ 3 skills checked
✅ 2 passed
⚠️ 1 need fixes
Overall score: 68/100
Top issues:
- bad-skill: Risky command pattern found: rm -rf
- bad-skill: Side-effect instruction lacks an approval gate
- bad-skill: Referenced path does not exist: scripts/missing.sh
$ agentskills-ci badge ./skills --repo https://github.com/you/your-repo
[](https://github.com/you/your-repo)
What it does
- Validates
SKILL.mdfrontmatter and body structure - Checks for missing linked files in
references/,templates/,scripts/, andassets/ - Flags risky shell patterns such as
rm -rf,curl | bash, and broad permission changes - Flags external side-effect instructions without approval gates
- Scores each skill from
0–100 - Emits text, Markdown, or JSON reports
- Provides a composite GitHub Action via
action.yml - Includes a workflow generator:
agentskills-ci init-github-action
Quick start
pipx install agentskills-ci
agentskills-ci check ./skills
agentskills-ci score ./skills --format markdown
agentskills-ci init-github-action --path skills
Local development from this repo:
python -m venv .venv
source .venv/bin/activate
pip install -e '.[dev]'
pytest -q
agentskills-ci check examples/skills/good-skill
Example output
✅ 1 skills checked
✅ 1 passed
⚠️ 0 need fixes
Overall score: 100/100
Bad-skill example:
⚠️ 1 skills checked
✅ 0 passed
⚠️ 1 need fixes
Overall score: 8/100
Top issues:
- bad-skill: Missing required frontmatter field: description
- bad-skill: Missing recommended section: ## Overview
- bad-skill: Referenced path does not exist: scripts/missing.sh
- bad-skill: Risky command pattern found: rm -rf
- bad-skill: Side-effect instruction lacks an approval gate
GitHub Action usage
Use the published action from a workflow in another repository:
name: Agent Skills CI
on:
pull_request:
push:
branches: [main]
jobs:
validate-skills:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: damanisme/agentskills-ci@main
with:
path: skills
min-score: "80"
format: text
Or generate a workflow locally:
agentskills-ci init-github-action --repo . --path skills
A sample workflow is included at examples/github-workflows/ci.yml.
CLI
agentskills-ci check PATH [--format text|markdown|json] [--min-score 80] [-o FILE]
agentskills-ci score PATH [--format text|markdown|json] [-o FILE]
agentskills-ci init-github-action [--repo .] [--path skills]
agentskills-ci badge PATH [--format markdown|url|endpoint] [--label "skill score"] [--repo URL]
Quality badge
Show your skill score in any README. Generate a static badge:
agentskills-ci badge ./skills --repo https://github.com/you/your-repo
# [](https://github.com/you/your-repo)
Or wire a live, self-updating badge via a shields.io endpoint. Publish the JSON
from agentskills-ci badge ./skills --format endpoint to a URL, then point
shields.io at it:

Badge color tracks the score: >=90 brightgreen, >=80 green, >=60 yellow,
>=40 orange, else red.
PATH can be either a single SKILL.md file or a directory containing nested skill folders. Symlinked skill directories are followed (with cycle protection), so an aggregated skills/ folder that links skills in from elsewhere is fully scanned.
What gets checked
Required structure
- YAML frontmatter starts at the top of
SKILL.md - Required fields:
name,description - Description length <= 1024 characters
- Skill name is lowercase and URL-safe
Recommended sections
## Overview## When to Use## Common Pitfalls## Verification Checklist
Linked files
References to these folders are validated:
references/templates/scripts/assets/
Example:
See `references/api.md` and `scripts/check.sh`.
If either file is missing, CI fails.
Safety scan
Current MVP rules flag:
rm -rfcurl | bashchmod 777- suspicious secret literals
- destructive
sudocommands - side-effect actions such as posting, deploying, sending email, or merging without an approval gate
Why this matters
Agent skills are operational runbooks. A bad skill can:
- trigger at the wrong time
- reference missing support files
- tell an agent to run dangerous commands
- perform external side effects without approval
- silently drift out of date
agentskills-ci makes these problems visible in pull requests.
Roadmap
See ROADMAP.md for the full list. Highlights:
- SARIF output for GitHub code scanning
- ✅ Badge endpoint / static badge generation (
agentskills-ci badge) - Skill registry quality cards
- LLM-assisted skill critique mode
- Overlap detection between related skills
- Policy packs for enterprise teams
- Test fixtures for tool-call simulations
- Package publishing to PyPI
Repository structure
agentskills-ci/
├── action.yml
├── examples/
│ ├── github-workflows/
│ └── skills/
├── src/agentskills_ci/
├── templates/
├── tests/
└── pyproject.toml
License
MIT