convez.ai
MCP ServerAutomaçãoAvançado
jscraik

Agent Skills Kit

jscraik/Agent-Skills

Governo de skills para agentes de IA: autor uma vez, valida sempre, expõe via CLI

Ver no GitHub
BomPluginScore · de 0 a 100

Framework de governo para ensinar agentes de IA (como Codex) as capacidades de um workspace. Permite autorizar skills uma vez, validar qualidade, expor handles de comando e projetar capacidades em runtime sem inflacionar contexto. Inclui CLI `ask` para descoberta, explicação e validação de skills.

Instalação

$npx convez-ai jscraik/Agent-Skills

1 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

Estrelas
9
Forks
4
Acompanhando
0
Saúde
100%
Último commit
há 3 dias
Versão
—
Issues abertas
6
Contribuidores
7

Casos de uso

  • Criar e manter um catálogo de skills validadas para agentes de IA
  • Expor capacidades do workspace a Codex e outros agentes sem prompt engineering complexo
  • Validar qualidade e estado de prontidão de skills antes de usar em produção
  • Auditar e documentar skills de forma governada e sincronizada

Veredito

Ferramenta sofisticada de governance para times que trabalham com agentes de IA em escala. Resolve o problema real de manter skills confiáveis e descobríveis sem degradar experiência dos agentes—mas exige disciplina arquitetural e entendimento profundo do seu workspace.

README

A tradução para o português deste README ainda está na fila.

Agent Skills

Agent Skills Kit is the governed repository for teaching Codex and other AI coding agents how this workspace works.

Use it to author skills once, validate them, expose small $ command-surface handles, and project the right capabilities into runtime without turning every workflow into prompt context.

The short version:

  • Canonical skill source lives in Skills/** and Plugins/*/skills/**.
  • Generated runtime and command surfaces live in .agents/** and .skillsets/**.
  • ./bin/ask is the public repo command surface.
  • Runtime counts drift by design. Ask the CLI for current truth instead of trusting a README number.
  • Catalog parity marker: 79 canonical skills. Regenerate this marker with the repo skill sync when catalog membership changes.

For the product framing and proof contract, read Agent Capability Control Plane.

Contents

First five minutes

On a fresh checkout, prove the repo-local command surface before relying on ./bin/ask:

bash scripts/bootstrap-ask.sh --json
python3 bin/ask repo status --json

If the bootstrap wrapper is unavailable in your shell, use python3 bin/ask repo status --json as the fallback. After status passes, follow the next command reported by repo doctor.

For AI coding agents, use this sequence:

./bin/ask repo doctor --json --robot
./bin/ask skills improve "<goal>" --json --robot
./bin/ask skills explain <recommended_capability> --json --robot
./bin/ask skills prove <recommended_capability> --json --robot
./bin/ask repo closeout --changed --json --robot

That path answers:

  • can I work safely here;
  • which capability matches the job;
  • how should I use it;
  • what proof exists;
  • what must pass before I claim done.

Pick the right path

Reader jobStart hereWhy
Check repo health./bin/ask repo doctor --json --robotCombines repo status, catalog parity, runtime budget, command-surface metadata, and surface diagnostics.
Find a skill for a task./bin/ask skills improve "<goal>" --json --robotRoutes the goal to one capability and returns the next useful command.
Understand a skill./bin/ask skills explain <handle> --json --robotResolves the handle to source, usage, limits, and proof.
Prove a skill./bin/ask skills prove <handle> --json --robotReports reachability, quality, analytics, and outcome-proof state without merging those lanes.
Audit a skill source./bin/ask skills audit <path> --level strict --json --robotRuns the strict structural and policy check for one skill.
Close out current work./bin/ask repo closeout --changed --json --robotReports changed-scope validation and readiness blockers.

Use --robot when an agent is driving the CLI. The wrapper corrects clear syntax mistakes and returns structured errors when intent is ambiguous.

Everyday commands

Discover capabilities

./bin/ask skills list --json --robot
./bin/ask skills handles --json --no-handles --robot
./bin/ask skills resolve <handle> --json --robot
./bin/ask reviewers resolve <handle> --json --robot
./bin/ask graph find security --tier stable
./bin/ask graph related skill-builder --depth 2

Validate and prove

./bin/ask repo doctor --json --robot
./bin/ask runtime surface --json --robot
./bin/ask runtime budget --json --robot
./bin/ask repo validate --ephemeral
./bin/ask repo closeout --changed --json --robot

Manage skill lifecycle

./bin/ask skills install https://github.com/owner/repo --remediate
./bin/ask skills fold source-skill target-skill
./bin/ask skills init my-skill --category backend --description "Does X when Y"
./bin/ask plugins init my-plugin --with-marketplace

Runtime surfaces

This repo separates source, generated projections, and live runtime visibility.

SurfacePurposeEdit policy
Skills/<topic>/<skill>/SKILL.mdCanonical first-party skill sourceEdit here
Plugins/<plugin>/skills/**/SKILL.mdCanonical plugin-owned skill sourceEdit here
.skillsets/**Generated rooted manifests and command-surface projectionRegenerate only
.agents/skills/**Runtime projection consumed by Codex and agent runtimesRegenerate only
~/.agents/skills, ~/.codex/skillsUser runtime links to the active projectionRefresh with user sync

Command-surface metadata in .skillsets/command-surface.json makes handles such as $he-heartbeat mentionable and resolves them to canonical SKILL.md source. It is not a generated wrapper file and it is not the real workflow.

Resolve command-visible skill handles with:

./bin/ask skills resolve he-heartbeat --json --robot

Resolve reviewer or subagent handles with:

./bin/ask reviewers resolve skillinspector --json --robot

Before cleanup, projection changes, or runtime ownership decisions, inspect repo surface ownership:

./bin/ask repo surface --json --robot

Full ownership policy lives in Path Ownership Boundaries and Repo Surface Ownership.

Quality and readiness

Keep evidence lanes separate when reporting readiness:

  • Local commands prove local command behavior only.
  • Skill audits prove structural and policy conformance.
  • Evals prove dynamic behavior for the cases they run.
  • Plugin Eval, Tessl, and Snyk evidence are separate review lanes.
  • PR, CI, review-thread, tracker, and merge-readiness truth require current external checks before they can be claimed.

For one skill, use the quality ladder from Validation and Checks:

./bin/ask skills audit <skill-path> --level strict --json --robot
./bin/ask evals run <skill-path> --mode smoke --json --robot
./bin/plugin-eval analyze <skill-path> --format json
./bin/ask skills external-review <skill-path> --json --robot

Stop at the first failed gate unless you are deliberately collecting a full matrix. Report the exact command, status, blocker class, and next diagnostic.

Repository layout

agent-skills/
|-- bin/ask                   # Stable public wrapper entrypoint
|-- scripts/                  # Stable wrapper entrypoints
|-- Skills/                   # Canonical first-party skills
|-- Plugins/                  # Canonical plugin packages and plugin-owned skills
|-- Infrastructure/           # CLI implementation, validators, sync, governance
|-- Docs/                     # Agent guidance, architecture, specs, and product docs
|-- Wiki/                     # Skill Ops Wiki notes, playbooks, and learnings
|-- .agents/skills/           # Runtime projection; regenerate only
|-- .skillsets/               # Generated rooted manifests; regenerate only
`-- .workouts/                # Canonical skill workout fixtures

Root wrappers under bin/** and scripts/** forward into Infrastructure/**. Keep those wrappers as real files or directories.

Further reading

Privacy and Data Handling

This repository stores skill source, docs, and validation artifacts for local-first agent workflows. Do not commit credentials, tokens, private telemetry, or personal data.

Governance

  • License: Apache 2.0
  • Compatibility: Codex and compatible Agent Skills runtimes
  • Visible runtime surface: ./bin/ask skills list --json --robot
  • Command surface: ./bin/ask skills handles --json --no-handles --robot
  • System skills pin: Infrastructure/GOVERNANCE/skills-system-upstream.lock.json
  • Validation: ./bin/ask repo validate --ephemeral
Ver o original no GitHub

Bom para

Relacionados