Agent Skills

A governed Agent Skills Kit repository for Codex and AI coding agents. Author skills once, validate quality, expose SDK skill names, and sync routed skills and plugins into flat runtime projections through the ask CLI.

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 SDK skill names, and project the right capabilities into flat runtime without turning every workflow into prompt context.

The short version:

• Canonical skill source lives in Skills/** and Plugins/*/skills/**.
• Generated runtime surfaces live in .agents/**.
• ./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: 84 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 sdk start "<skill-or-goal>" --project-root /path/to/project --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 SDK lifecycle lane should run first;
• which capability matches the job;
• how should I use it;
• what proof exists;
• what must pass before I claim done.

Pick the right path

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-factory-router --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.

SDK-flat metadata is generated from canonical skill sources. Obsolete rooted manifests and command-surface files are not SDK inputs and should not be used as operator handles.

Resolve canonical skill handles with:

./bin/ask skills resolve improve-agent-native --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
`-- .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 - ask CLI 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 - SDK-flat projection, SDK skill names, 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