agent-systems-skills

Agent Systems Skills

A maintainability-focused collection for agent-engineered systems. These skills help coding agents understand, change, verify, and retire observable agent behavior without replacing project-specific rules or the host agent's native workflows.

Release status: v1.x is the current published stable line. The changes documented here target the unreleased v2.0.0 line; they are not a release claim.

Skills

These skills are explicitly invoked. They do not apply to ordinary software projects that lack executable agent-specific behavior.

Installation

Use the open-source skills CLI to inspect the repository before installing:

npx skills add zixun/agent-systems-skills --list

Install Plan Pro Max on its own when you want planning and None or Standard review decisions:

npx skills add zixun/agent-systems-skills \
  --skill agent-systems-plan-pro-max \
  --global

For a plan that selects Review requirement: Deep, install its same-release companion pair because the current skills CLI does not resolve companion dependencies automatically:

npx skills add zixun/agent-systems-skills \
  --skill agent-systems-plan-pro-max \
  --skill agent-systems-deep-change-review \
  --global

Deep Change Review and Maintainability Audit remain independently installable; for example:

npx skills add zixun/agent-systems-skills \
  --skill agent-systems-deep-change-review \
  --global

Or install the complete collection:

npx skills add zixun/agent-systems-skills \
  --skill '*' \
  --global

The CLI can target a specific supported host with --agent, for example --agent codex or --agent claude-code. Follow the CLI's discovery result instead of copying the same skill into several platform directories manually.

Repository contributors may clone this project and link from their host's discovery directory to the canonical skill folder. Keep the clone as the only physical source; do not maintain divergent copies.

Preparing for v2.0.0

v2.0.0 introduces Review requirement: None | Standard | Deep. Reinstall Plan Pro Max alone for None and Standard plans; add Deep Change Review from the same release only for Deep plans:

npx skills add zixun/agent-systems-skills \
  --skill agent-systems-plan-pro-max \
  --global
npx skills list --global

For a Deep plan, install the pair shown above and confirm both skills resolve from the same collection release. For a project-scoped installation, run the same add and list commands without --global. Invocation names are unchanged. A former v1 plan already approved with unbounded Deep closure wording must either finish under v1 or be cancelled, replanned, and approved under v2's one-pass review contract.

The CLI cannot update a discovery-directory link that you created manually. In every manually configured discovery root, update the Plan Pro Max link and, for Deep use, its companion link to this repository's canonical folders; skills list alone cannot prove a manually managed link targets the new release.

Usage

Invoke the skill by name in an appropriate host workflow:

$agent-systems-plan-pro-max strengthen my plan for this agent workflow migration
$agent-systems-maintainability-audit audit this agent-engineered project
$agent-systems-deep-change-review review my current uncommitted agent-system change

agent-systems-plan-pro-max augments the host's native Plan mode and remains read-only. It does not produce a competing plan or replace the host's plan format, tools, approval boundary, or transition into execution. Every plan records Review requirement: None, Standard, or Deep from review-sufficiency evidence. None adds no review workflow beyond proportionate verification. Standard requires one independent ordinary review when the planner can explain why that reviewer can cover the changed behavior, direct consumers, and failure evidence; it then batches in-scope repairs and affected tests without automatic re-review. Deep applies only when the plan names why Standard is insufficient and what distinct evidence needs independent coverage. If implementation drift invalidates that argument, the host pauses for a revised, user-approved plan before increasing review cost.

Deep Change Review remains read-only both when invoked directly and from an approved Deep plan. It performs one general independent review plus only the targeted reviews needed for the stated evidence gap, then reports verified findings, coverage, target identity, and residual risk. The host may repair verified in-scope root causes and run affected verification, but must state that the repaired complete target was not automatically independently re-reviewed. Installing the review skill does not create an independent reviewer runtime.

When earlier design work has already settled user decisions, provide those conclusions as a Decision Handoff when invoking Plan Pro Max. The handoff is optional and tool-neutral: it can be carried in the request, conversation, or user-provided material without a prescribed format. Plan Pro Max treats confirmed decisions as constraints, then independently verifies current implementation, consumers, compatibility, and retirement evidence before it strengthens the host's plan.

Public contract

The following are versioned public contracts:

• each skill's invocation name;
• applicability and explicit non-applicability boundaries;
• required host capabilities;
• whether the skill may modify the target project;
• the semantic result delivered to the user.

For the v2 Plan Pro Max contract, the review requirement level is public. Standard specifies one ordinary independent review when its sufficiency argument holds. Only Deep requires the same-release Deep Change Review companion for one independently checked review with the distinct evidence Standard lacks. Direct Deep Change Review and Maintainability Audit remain independently installable and read-only.

Internal question order, instruction wording, and natural-language formatting may evolve without being treated as stable APIs. Breaking public-contract changes require a major-version change and migration notes; compatible additions use a minor version, and fixes use a patch version.

Compatibility

Installation compatibility means that a host can discover and invoke the canonical skill. Behavioral compatibility requires representative fresh-context evals proving that the host follows the skill's intended discipline and boundaries.

Host agents, models, and tool surfaces evolve independently. A platform not listed as behaviorally verified may still run the skills, but the project does not claim equivalent outcomes without evidence.

Repository layout

• skills/: canonical skill sources, metadata, synthetic eval definitions, and fixtures.
• tests/: deterministic repository and skill-contract checks.
• docs/adr/: durable design decisions for the collection.
• CONTEXT.md: the collection's domain language.
• docs/releasing.md: maintainer release evidence and publication checklist.

All organizations, credentials, domains, paths, and scenarios in eval fixtures are synthetic. Placeholder identifiers such as ACME_TRACE_TOKEN and reserved .invalid domains are test data, not dependencies to configure.

Development

Run the deterministic checks with Python 3.9 or later:

python3 -m unittest discover -s tests

Before publishing a changed skill, also run the current platform skill validator and forward-test judgment-dependent behavior in a fresh context. Changes to Plan Pro Max's review requirement must exercise None, a direct bounded-but-sensitive Standard change, and a Deep case whose named evidence gap needs a targeted reviewer. Deep changes additionally validate one same-release Deep Change Review, root-cause repair, affected verification, and honest reporting that no automatic re-review occurred. See the release checklist.

Contributions are welcome under the rules in CONTRIBUTING.md. Report sensitive problems according to SECURITY.md.

License

Released under the MIT License. Copyright (c) 2026 zixun.