AGENTS.md@toolkit/skillet · diff

git:20260810.ecbb027 to git:20260921.e8da9da

123 added, 0 removed. Audit A to A.

# ai-skillet contributor guidance

Keep the CLI synchronous and library-owned: `src/main.rs` parses process arguments and maps

errors to exit codes, while behavior belongs in `src/lib.rs` and focused modules.

The supported public surface is `map`, `doctor`, `doctor --dependencies-only`, and `--version`.

Preserve the documented exit codes and deterministic text, JSON, and DOT output contracts.

Use the nightly minimal Rust toolchain configured at the monorepo root. Before proposing a change,

run the narrowest relevant locked Cargo check. Keep macOS and Linux compatibility; do not add

runtime services, plugin systems, config files, shell hooks, or completion generation without an

explicit product decision.

From the monorepo root, `cargo test -p ai-skillet --locked` is the focused package gate and

`just rust-check` is the aggregate Rust gate. `just install-cli` installs every workspace binary

under `~/.local`; do not run it for ordinary verification.

+ ## CLI reference

+ `ai-skillet` inspects and maintains catalogs of agent skills.

+ ### Status

+ Version 1.0.0 provides synchronous, no-network `map` and `doctor` engines. JSON reports use the

+ clean Rust schema version 1. The schema preserves the Python tools' consumer contracts, but output

+ is not byte-compatible with the Python implementation.

+ ### Commands

+ ```text

+ ai-skillet map [OPTIONS]

+ ai-skillet doctor [OPTIONS]

+ ai-skillet --version

+ ```

+ `doctor --dependencies-only` limits diagnostics to skill-dependency declarations. Repeatable

+ `doctor --skill <NAME>` filters diagnostics and safe fixes by canonical skill directory name.

+ A catalog root that exposes `skills/` must provide a `README.md` with an exact `## Skills`

+ section and a Markdown table. The required first column is `Skill` and lists every active skill

+ name; additional columns are optional and ignored by the inventory validator. Conventional

+ installed roots named `.agents`, `.claude`, or `.codex` do not require a catalog README inventory.

+ Skills in ordinary source-catalog `skills/<name>` paths must provide `agents/openai.yaml`.

+ Conventional installed exposures beneath `.agents/skills`, `.claude/skills`, or `.codex/skills`

+ may omit that file. When an installed exposure provides it, doctor still validates the extended

+ `policy.allow_implicit_invocation` contract and can safely update a mismatch.

+ ### Doctor validation contract

+ `ai-skillet doctor --root <skill-or-catalog-root>` is the canonical deterministic, offline local

+ validator for the supported extended skill dialect. For an explicit targeted audit, pass a catalog

+ root with one or more filters:

+ ```sh

+ ai-skillet doctor --root '.agents/skills' --skill 'land-search'

+ ```

+ A direct `skills/<name>` root is shorthand for auditing only that directory while resolving bare

+ dependencies against sibling skills in the owning `skills` directory. This applies equally to

+ source catalogs and `.agents`, `.claude`, or `.codex` installed exposures, including directory

+ symlinks. A standalone skill outside a `skills/<name>` layout does not infer an owning catalog;

+ bare dependencies must still resolve from explicitly supplied roots. Targeted audits omit

+ catalog-wide README inventory diagnostics, and `--fix-safe` modifies only selected skills.

+ Doctor accepts this one top-level field union:

+ - Portable [Agent Skills](https://agentskills.io/specification): `name`, `description`, `license`,

+ `compatibility`, `metadata`, and `allowed-tools`.

+ - [Claude Code extensions](https://code.claude.com/docs/en/skills#frontmatter-reference):

+ `when_to_use`, `argument-hint`, `arguments`, `disable-model-invocation`, `user-invocable`,

+ `disallowed-tools`, `model`, `effort`, `context`, `agent`, `background`, `hooks`, `paths`, and

+ `shell`.

+ - Repository extensions: `coordination` and `skill-dependencies`.

+ Unknown top-level fields are errors. `metadata` must be a string-to-string mapping;

+ `metadata.install-targets` additionally accepts only `claude-code`, `codex`, or

+ `claude-code codex`. Tool, argument, and path fields accept a string or a list of strings, while

+ `hooks` must be a mapping. Claude Boolean fields accept `true`/`false`, `yes`/`no`, `on`/`off`,

+ or `1`/`0`; other YAML shapes are not coerced. `context` accepts only `fork`, `effort` accepts

+ `low`, `medium`, `high`, `xhigh`, or `max`, and `shell` accepts `bash` or `powershell`. `agent`

+ and `background` require `context: fork`.

+ `coordination: exempt` requires this exact sentence in ordinary Markdown body prose:

+ ```text

+ This skill is coordination-exempt: skip the ai-coord gate for its declared work.

+ ```

+ Inline code, fenced or indented code, blockquotes, and clearly headed `Example` or `Examples`

+ sections do not count as declarations and do not trigger missing-frontmatter errors.

+ New schema diagnostics use these stable codes:

+ - Unknown field: `FRONTMATTER_UNKNOWN_FIELD`.

+ - Invalid types: `LICENSE_INVALID_TYPE`, `ALLOWED_TOOLS_INVALID_TYPE`,

+ `WHEN_TO_USE_INVALID_TYPE`, `ARGUMENTS_INVALID_TYPE`, `DISALLOWED_TOOLS_INVALID_TYPE`,

+ `MODEL_INVALID_TYPE`, `EFFORT_INVALID_TYPE`, `BACKGROUND_INVALID_TYPE`,

+ `HOOKS_INVALID_TYPE`, `PATHS_INVALID_TYPE`, `SHELL_INVALID_TYPE`, and

+ `METADATA_VALUE_INVALID_TYPE`. Existing field-specific type codes remain unchanged.

+ - Invalid values: `EFFORT_INVALID_VALUE` and `SHELL_INVALID_VALUE`, alongside the retained

+ compatibility, context, coordination, and install-target codes.

+ - Cross-field errors: `AGENT_CONTEXT_REQUIRED` and `BACKGROUND_CONTEXT_REQUIRED`.

+ - Explicit defaults: `disable-model-invocation: false` and `user-invocable: true` restate the

+ effective defaults and are accepted without findings, so catalogs that require explicit

+ booleans stay clean.

+ These diagnostics add findings without changing JSON schema version 1, deterministic finding

+ order, exit codes, or the existing `--fix-safe` boundary.

+ ### Conformance contract

+ | Area | Required contract | Intentional version 1 behavior |

+ | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |

+ | CLI | Usage and operational errors exit 2; doctor findings exit 1; safe-fix failures exit 3 | Operational errors are emitted once with no generic duplicate |

+ | Map output | Deterministic text, JSON, and DOT; skills, roots, edges, duplicates, unresolved references, hashes, and portfolio exposures remain available | Declared and inferred evidence remain independent; missing filters warn while returning an empty report |

+ | Discovery | Explicit roots, broad-root exclusions, portfolio roots, ignored entries requested directly, symlink exposures, and paths containing newlines are supported | Local dependencies resolve across every scanned root |

+ | Streaming | Large files and newline-free lines are scanned with bounded buffers; snippets are bounded match text | No ripgrep child process or cancellation lifecycle is required |

+ | Doctor | The complete supported frontmatter union plus every metadata, dependency, coordination, resource, README, prompt-hygiene, and CLI-version finding family is validated | YAML and OpenAI policy diagnostics are structural; safe fixes are isolated and atomic |

+ | Dependencies | Bare and external identifiers, uniqueness, self-reference, resolution, and target-name ordering are validated | External owner/repository case is preserved; repository names ending in `.git` are rejected |

+ The integration tests in `tests/conformance.rs`, `tests/map.rs`, `tests/doctor.rs`, and

+ `tests/catalog.rs` are the executable contract. Python captures are migration evidence, not golden

+ output fixtures.

+ ### Development

+ The monorepo selects nightly Rust with the minimal profile plus `clippy` and `rustfmt`.

+ ```sh

+ cargo test -p ai-skillet --locked

+ just rust-check

+ ```

+ From the monorepo root, `just install-cli` installs all five workspace binaries under `~/.local`.

+ ### License

+ MIT. See [LICENSE.md](../LICENSE.md).