Agent Skills Kit
jscraik/Agent-Skills
Governo de skills para agentes de IA: autor uma vez, valida sempre, expõe via CLI
Ver no GitHubFramework 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-Skills1 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
- 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/**andPlugins/*/skills/**. - Generated runtime and command surfaces live in
.agents/**and.skillsets/**. ./bin/askis 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
- Pick the right path
- Everyday commands
- Runtime surfaces
- Quality and readiness
- Repository layout
- Further reading
- Privacy and Data Handling
- Governance
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 job | Start here | Why |
|---|---|---|
| Check repo health | ./bin/ask repo doctor --json --robot | Combines repo status, catalog parity, runtime budget, command-surface metadata, and surface diagnostics. |
| Find a skill for a task | ./bin/ask skills improve "<goal>" --json --robot | Routes the goal to one capability and returns the next useful command. |
| Understand a skill | ./bin/ask skills explain <handle> --json --robot | Resolves the handle to source, usage, limits, and proof. |
| Prove a skill | ./bin/ask skills prove <handle> --json --robot | Reports reachability, quality, analytics, and outcome-proof state without merging those lanes. |
| Audit a skill source | ./bin/ask skills audit <path> --level strict --json --robot | Runs the strict structural and policy check for one skill. |
| Close out current work | ./bin/ask repo closeout --changed --json --robot | Reports 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.
| Surface | Purpose | Edit policy |
|---|---|---|
Skills/<topic>/<skill>/SKILL.md | Canonical first-party skill source | Edit here |
Plugins/<plugin>/skills/**/SKILL.md | Canonical plugin-owned skill source | Edit here |
.skillsets/** | Generated rooted manifests and command-surface projection | Regenerate only |
.agents/skills/** | Runtime projection consumed by Codex and agent runtimes | Regenerate only |
~/.agents/skills, ~/.codex/skills | User runtime links to the active projection | Refresh 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
- Agent Guide - repo workflow contract for AI agents.
- Agent Instruction Map - map of detailed policy docs.
- Agent Operating Contract -
askCLI behavior and robot mode. - Tooling and Command Policy - wrapper and package-command rules.
- Validation and Checks - repo and skill gates.
- Skill Management - install, audit, fold, and line-budget policy.
- Runtime Projection Modes - flat/rooted projection modes, command-surface metadata, and sync scope.
- CLI Specification - full command reference.
- Product Golden Path Command Contracts - namespace-first product command contracts.
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