agentic-praxis-grimoire

Skill Authoring and Maintenance

Purpose and ownership

This guide is the normative maintainer-facing procedure for creating, correcting, supporting, maturing, deprecating, or removing an APG skill. The project model owns general artifact destination and practice lifecycle policy. The skill catalog owns current leaves, discovery shape, and maturity labels. Provenance owns source, rights, derivation, and notice records. Evaluations and exits own bounded evidence and phase history.

This procedure does not grant authority. Work requires a human-authorized phase or assignment, and repository policy continues to own project-specific parameters.

Choose the owner

Need	Destination
A concise rule that must apply to nearly all repository work	Root instruction
A demonstrated gap in an existing triggerable procedure	Existing skill correction
One coherent reusable problem with no adequate existing owner	New skill
Detailed guidance needed only after one skill triggers	Supporting reference
A stable skill-local operation that benefits from deterministic execution	Deterministic helper
Architecture, authority, privacy, test, release, or repository-specific requirements	Project policy
An observation, scenario result, source mapping, or bounded review	Evidence only
Duplicated, unjustified, incompatible, or excessively project-specific material	Rejection

External packaging, repeated slogans, or authoritative tone do not establish an APG owner. Prefer the smallest existing owner that can address a demonstrated gap without broadening its trigger.

Lifecycle

Authorize and define the concrete problem.
Inspect existing owners, repository policy, and native capability.
Inventory source identity, publication status, reuse rights, and notice duties.
Classify the change as new skill, frontmatter-only correction, behavior-bearing correction, support/helper addition, maturity-only disposition, or deprecation/removal.
Freeze acceptance, representative non-trigger, edge or stop, and rollback evidence proportional to the change.
Establish baseline behavior when behavior will change.
Author the smallest APG-native artifact in its owning destination.
Run the affected scenarios, apg-check-skill-library, and repository gates.
Obtain fresh non-author review of the resulting state.
Record provenance, maturity, maintenance impact, disposition, limitations, and rollback.

Do not infer permission to expand the change from this lifecycle. An unmet authority, privacy, rights, or safety condition stops the work.

Change-class matrix

Class	Required evidence	Default correction bound	Mechanical checks	Independent review	Records	Rollback	Maturity effect
New skill	Ownership gap; source rights; multiple independent positive and non-trigger families; edge or stop behavior	One candidate plus one bounded material correction	Full library, catalog, projection, link, and repository gates	Fresh procedure and complete-diff review	Public evaluation, provenance, catalog, ADR or exit as required; private source evidence when needed	Remove leaf, projection, catalog row, active references, and support while preserving history	None unless separately authorized
Frontmatter-only discovery correction	Reproduced discovery gap and unaffected procedure baseline	One correction	Metadata, catalog, projection, discovery-focused regression	Fresh non-author leaf review	Evaluation/provenance/exit update proportional to the correction	Restore prior frontmatter and rerun discovery checks	None
Behavior-bearing procedure correction	Frozen gap; current and candidate results on the same affected positive, non-trigger, and edge or stop cases	One bounded correction unless the phase declares another finite bound	Full checker plus affected repository regression	Fresh non-author procedure and resulting-state review	Public evaluation and provenance; private exact evidence when needed	Restore prior leaf, rerun frozen cases and gates, supersede the decision if material	None unless separately authorized
Support file or deterministic helper	Demonstrated leaf-local need, interface, safety boundary, dependency status, and executable examples where applicable	One bounded correction	Leaf shape, links, helper syntax and behavior, repository regression	Fresh code/content and safety review	Catalog or guide only when behavior changes; provenance/evaluation as needed	Remove support and references together; restore prior leaf	None
Maturity-only disposition	Complete evidence inventory against the accepted maturity criteria	No procedure correction; any correction becomes another class	Full current checker and regression evidence	Fresh per-skill disposition review	Catalog, evaluation, provenance, ADR/exit as required	Revert label and supersede unsupported disposition; do not erase evidence	Only the explicitly authorized label change
Deprecation or removal	Replacement or obsolescence evidence, dependency/reference inventory, migration and history plan	One bounded reconciliation pass	Full checker during deprecation; post-removal catalog/projection/reference gates	Fresh ownership, impact, and complete-diff review	Catalog, provenance, roadmap/evaluation/exit, and replacement links	Restore retained version when safe or supersede with a corrected transition	`deprecated` only when explicitly authorized; removal is not maturity

Exact commands, scenario counts, and record depth remain phase- and repository-owned. The defaults above are not universal gates for unrelated projects.

New-skill threshold

Retain a new skill only when all of the following are supported:

one coherent reusable problem exists;
instructions, existing skills, project policy, and native capability do not already own it adequately;
the trigger is precise and material non-triggers are explicit;
the procedure is independently removable;
authority and project-owned policy remain outside the skill;
source and derivation rights are known; and
representative positive, non-trigger, edge or stop, and independent-review evidence supports retention.

Reject or route elsewhere when any missing condition is structural rather than correctable within one bounded iteration.

Source-derived work

Record one APG provenance mode:

copied: expression is reproduced substantially verbatim;
adapted: recognizable expression or structure is modified;
synthesized: new APG-native expression combines evaluated ideas and project evidence without preserving source expression;
inspired: a source prompted investigation but no material expression or procedure was retained.

External license labels do not replace complete rights and notice review for copied or adapted expression. Preserve required notices before adoption. Frequency, source ownership, or permissive-looking metadata does not establish semantic value or APG authority.

Scenario guidance

Use representative positive, non-trigger, and edge or stop behavior without a fixed universal count. A new skill normally needs multiple independent positive and non-trigger families. A frontmatter-only correction may use focused discovery cases. A behavior-bearing correction compares current and candidate behavior against the same frozen cases. Support/helper changes add direct interface, failure, and safety evidence appropriate to the helper.

Comparative A/B evidence is optional unless a phase expressly makes it part of the claim. Passing prose inspection is not a substitute for executable evidence when behavior is deterministic and testable.

Maintenance, deprecation, and removal

Re-evaluate an owner when evidence shows over-triggering, authority drift, source or license change, changed harness discovery, repeated corrections, stale project assumptions, better native capability, overlap with another owner, or a credible deprecation/removal need.

Repeated correction is a design signal, not permission for indefinite editing. Stop and reconsider the owner when the declared correction bound is exhausted or when a correction changes the original problem, authority, or safety model.

Deprecation keeps the leaf only while an explicit transition needs it and uses the deprecated catalog maturity when authorized. Removal reconciles the canonical leaf, discovery projection, catalog, provenance, evaluations, active references, replacement guidance, and rollback. Historical ADRs, exits, and evaluations remain intact.

Mechanical checker

Run:

bin/apg-check-skill-library [--root <path>] [--format text|json]
bin/apg-check-skill-library --help

The default root is the repository containing the command. --root permits read-only validation of another APG-shaped tree. Exit 0 means the adopted mechanical subset passed; exit 1 reports library noncompliance; exit 2 reports command-line misuse.

The checker validates:

a real canonical skills/ tree, regular skills/README.md, regular SKILL.md leaves, and contained optional scripts, references, assets, or agents directories;
APG’s plain-scalar name and description subset, name grammar, directory agreement, uniqueness, Use when descriptions, one H1, and exactly one of each adopted H2 owner;
nonempty support directories and contained support symlinks;
accepted same-line literal Markdown links and images outside fenced code, resolved from the containing Markdown file and contained within the leaf;
the exact catalog table under the recognized current or historical catalog heading, including canonical bijection, links, trigger cells, and maturity vocabulary; and
exact checked-in .agents/skills/<name> projections to each declared direct or chatgpt/-nested canonical path, resolved identity, and containment.

ADR 0022 and APG30 accept exactly direct leaves and skills/chatgpt/<name> leaves while keeping projections flat. The checker derives each exact relative target from the canonical path, keeps frontmatter names globally unique, excludes namespace owners from counts, and rejects unknown namespaces or deeper owners. Historical public policy remains version-bounded rather than being reinterpreted by current development.

The parser deliberately does not implement general YAML or Markdown. Every column-zero frontmatter mapping key must contain only ASCII letters, digits, underscores, or hyphens followed immediately by its key-terminating colon. Blank lines and comments remain accepted, and indented optional metadata is uninterpreted. Required frontmatter values must use exact name: value and description: value syntax as top-level, unquoted, one-line plain scalars without inline comments. Unsupported top-level key syntax fails closed. Link recognition is limited to unescaped same-line inline link/image syntax with a literal token or angle-bracket destination; external schemes and fragment-only references are not fetched, local fragments are removed before resolution, and percent escapes are not decoded. Headings, links, and the catalog are recognized only outside backtick or tilde fenced code. A closing fence must use the opening marker character at least as many times and may contain only spaces or tabs after the marker. Frontmatter is not scanned as Markdown. A contained .md support symlink is scanned with local destinations resolved from the symlink’s containing directory. Unsupported Markdown forms receive no semantic validation.

The checker cannot prove trigger quality, usefulness, authority, privacy, source rights, provenance truth, scenario quality, client discovery or invocation, over-triggering, maturity fitness, public-release completeness, production readiness, or stable behavior. Those remain evidence and review responsibilities. Passing the checker does not authorize a change or alter maturity.

Public release completeness is mechanically owned by apg-public-release and the strict public-surface policy under ADR 0009. That release gate composes the skill-library checker but does not change this lifecycle, validate semantic skill quality, or authorize maturity promotion.

Phase records and identity checks

Skill work follows the phase and record identity guide. Assign the canonical phase ID before implementation. Finalize the leaf, tests, catalog, capability map, integration owners, provenance, evaluation, exit, and applicable indexes before commit. Use semantic source versions and phase-local evidence IDs as durable identities. Exact Git identities ordinarily belong in post-commit managed reports or transient verification evidence; an explicitly authorized publication-excluded reproducibility record may retain them without becoming public or canonical identity.

Run the standard-library record checker when a phase changes records or current owners:

bin/apg-check-record-identity [--root <path>] [--format text|json]
  [--expect-available <phase>] [--expect-allocated <phase>]

It validates the adopted mechanical phase, ADR, exit, and index subset. A focused changed-file and current-owner scan separately checks whether an internal or maintainer-project hash is being used as a durable identity. Do not replace that semantic review with a repository-wide hexadecimal ban.

Public v0.2.0 carries the six ADR 0010 stable dispositions without changing a skill procedure. APG14 publication evidence is distribution evidence; future skill correction, maturity rollback, deprecation, or removal continues to require this lifecycle and separate authority.

Public v0.3.0 carries all nineteen ADR 0018 release-included skills: fourteen stable and five provisional. APG24 distribution and lifecycle evidence does not promote a provisional row, change a trigger, or substitute projection success for this maintenance procedure. No SKILL.md changes in APG24.

APG25 applies one behavior-bearing correction to composing-approved-roadmap-assignments after freezing three representative before/after assignment pairs and a failing focused test. The leaf now loads repository structured defaults, omits repeated ordinary procedure, and retains authority, acceptance, stop, and successor boundaries. Its trigger, name, provisional maturity, catalog row, projection, and route do not change.

APG26 applies this new-skill lifecycle separately to pytest-test-profile and converting-bash-scripts-to-python. Each candidate has current source and rights evidence, thirty frozen positive/non-trigger/edge or stop families, failing-first focused contracts, explicit project and authority boundaries, rollback, and fresh non-author review. Both are retained provisional; pytest needs no behavior-bearing candidate correction, while conversion uses one bounded option-injection correction. The generic native skill scaffold does not add harness metadata or support directories when APG’s checked direct-child text-only leaf contract has no demonstrated need for them.

APG28A adopts the corrected move of the pytest-profile contract test beneath the mirrored skill owner without changing SKILL.md, maturity, catalog, projection, or route state. The runner collects it as pytest and the inventory checks its production owner and exact mirror.

APG29 applies one behavior-bearing correction to each of implementing-with-test-discipline, planning-repository-work, reviewing-and-verifying-repository-work, and composing-approved-roadmap-assignments. Fifty-one frozen cases cover useful- test coverage remediation, scoped testing, mock and real boundaries, formal and non-phase defaults, and manager-prompt compression. Names, triggers, maturity rows, catalog descriptions, projections, and capability-map entries remain unchanged.

APG30 applies this lifecycle to one new provisional subrouter and one procedure-preserving canonical move. Thirty frozen cases cover direct and nested discovery, catalog identity, flat projections, project/user lifecycle, historical release compatibility, router ownership, and stop boundaries. chatgpt-manager-workflow begins provisional. The moved composing-approved-roadmap-assignments bytes and maturity remain unchanged; its catalog path, flat projection, and local-map owner change together.

APG32 applies this lifecycle to minitest-test-profile. Current official Minitest, separately extracted mock, Ruby, and RubyGems sources establish the version and rights boundary before thirty-six trigger, non-trigger, semantic, structural, and stop families are frozen. A failing-first mirrored contract then covers the leaf, route, projection, and scenario inventory. The retained candidate begins provisional after one bounded trigger and ownership correction. The native skill scaffold is used, while harness metadata and support directories are omitted because the checked APG direct-child text-only contract demonstrates no need for them.

APG33 applies this lifecycle to dockerfile-profile. Current official Docker documentation, Dockerfile frontend, BuildKit, and OCI Image Spec sources establish the version and rights boundary before forty trigger, non-trigger, semantic, structural, platform, protected-data, truthfulness, and authority families are frozen. A failing-first mirrored contract then covers the leaf, route, projection, threshold rows, and scenario inventory. The retained candidate begins provisional after one bounded context, ownership, and measurement correction. The native skill scaffold is used, while harness metadata and support directories are omitted because the checked APG direct-child text-only contract demonstrates no need for them.

APG34 applies this lifecycle to vagrantfile-profile. Current official Vagrant release and development source, documentation, licensing, and declared Ruby compatibility establish the version and rights boundary before forty trigger, non-trigger, configuration, box, provider, plugin, network, folder, provisioner, trigger, state, structural, truthfulness, and authority families are frozen. A failing-first mirrored contract then covers the leaf, route, projection, threshold rows, and scenario inventory. The retained candidate begins provisional after one bounded source-semantics and machine-measurement correction. The native skill scaffold is used, while harness metadata and support directories are omitted because the checked APG direct-child text-only contract demonstrates no need for them.

APG38 applies this lifecycle independently to the four APG37 replacement candidates. go-test-profile and go-cmp-test-profile pass current-source review, public-safe fixture conversion, isolated compatibility evidence, one coherent correction cycle, and fresh corrected-state review, then begin provisional. matryer-is-test-profile and nix-test-profile do not pass: fresh corrected-state review finds new material attribution/false-escalation and FreeBSD sandbox-default defects after their correction cycles. Both are deferred-material-defect, and all current integration surfaces are removed. Candidate deferral does not promote or block the retained owners.

APG39 re-authors the two deferred candidates as fresh authoring-branch leaves from their APG38 corrected-state defects: wrapper severity follows registration completeness rather than depth, relaxed-mode severity follows causality rather than count, and sandbox defaults are stated separately and exactly per platform with the actual configuration controlling. The candidates are authored-pending-independent-review; the lifecycle’s independent review, fixtures, compatibility evidence, correction cycle, and integration belong to a later separately authorized Codex phase.

APG40 applies that lifecycle. nix-test-profile passes one coherent source-fact correction cycle, forty executable public-safe scenarios, source-only corpus calibration, rights/privacy review, and fresh non-author corrected-state review, then begins provisional. matryer-is-test-profile is deferred-material-defect: its corrected-state equality mechanism still misstates exact source, so the one-cycle rule forbids another behavior correction and its current surfaces are removed. Mechanical public-test privacy repair does not consume a behavior cycle.

APG41 applies readiness review to all fourteen live provisional rows without promoting them. Minitest, Dockerfile, and Vagrantfile each receive one candidate-independent removal-description repair: remove the public scenario fixture with the focused test and derive surviving counts from live inventories instead of embedding historical totals. These are rollback wording and contract repairs, not behavior corrections. Fresh corrected-state review accepts all three.

APG42 publishes the exact APG41 skill set without changing a leaf, trigger, procedure, source calibration, route, projection target, or maturity row. Release inclusion leaves fourteen rows stable and fourteen provisional. matryer-is-test-profile and go-testing-stack remain absent; ADR 0026’s independent Go component ownership remains controlling.

Canonical leaves may exist only at skills/<name>/SKILL.md or skills/chatgpt/<name>/SKILL.md. The namespace is not a skill, names remain globally unique, and catalog links and projection targets must name the exact canonical path. Adding another namespace class requires a separate design and checker decision.

This site is open source. Improve this page.