Praxis Skill Authoring Governance
Treat a Praxis skill as executable platform guidance, not as generic documentation.
It must make a future implementation faster and more canonical by directing Codex to
the real owner, contracts, evidence, decisions, and focused proof.
Start From The Real Friction
- Capture the concrete repeated task, the decision that consumes time, and the
observable failure or rework it causes.
- Inspect the affected platform source, local
AGENTS.md, public contracts,
focused tests, operational examples, and direct consumers. Do not author from
a remembered API or only a ticket description.
- Classify the finding:
migration-skill-gap: the platform already supports the outcome but the
repeatable native route is absent or unclear;
ja-suportado-so-ux or ja-suportado-mal-nomeado-ou-mal-materializado:
improve adoption or materialization, not the contract;
suportado-parcialmente: identify the owning follow-up and the temporary
limit precisely;
lacuna-real-de-contrato: stop skill authoring as the primary remedy and
open an owner-specific platform RFC or implementation follow-up.
- State the canonical owner.
praxis-metadata-starter owns backend metadata,
schemas, resources, surfaces, actions, capabilities, and x-ui.
praxis-config-starter owns governed config and authoring persistence.
praxis-ui-angular owns public runtime libraries. Quickstarts prove contracts;
they do not redefine them.
Do not turn a missing tool, contract, or semantic capability into prose that
teaches a consumer-local workaround. Do not route primary intent with keywords,
regexes, labels, or aliases.
Choose The Smallest Useful Skill
Use one task-oriented skill when its workflow, evidence, owner, and validation
are coherent. Split only when a user can complete one task without loading the
other skill's detailed guidance. Keep praxis-* independent of Ergon/Archon;
put legacy discovery, Oracle behavior, migration gates, and Ergon evidence in
ergon-* skills.
Read portfolio-and-review.md when sizing a
new skill, reviewing overlap, or planning a delivery wave.
Each skill must contain:
- a trigger-rich frontmatter description;
- the canonical owner and the source paths/contracts that must be inspected;
- an evidence-first workflow with explicit decision points;
- prohibited local shortcuts and any required companion skills;
- the smallest validation that proves the promised outcome and derived-artifact
decision.
Keep SKILL.md procedural and concise. Put detailed matrices, examples, or
taxonomy in references/; add a script only for deterministic repeated work.
Author And Review
- Create the skill with the standard initializer, then replace all template
text. Keep its directory name and frontmatter
name identical.
- Test the description against at least two realistic prompts: one that should
trigger and one adjacent task that should not. Check that the workflow can
lead to
already supported as well as to an evidence-backed gap.
- For Java/Praxis guidance, inspect the actual starter annotations, base
controllers/services, schema or discovery projection, focused tests, and a
real host/consumer before asserting a canonical path. For Angular handoff,
prove that the backend contract can materialize in the relevant runtime,
including options, surfaces, actions, capabilities, errors, and applicable
stats/export.
- Record expected side effects for commands and mutations. Development-database
mutation authority may be pre-approved by the migration process, but the
skill must still require scoped probes, evidence, and cleanup or rollback
where the workflow creates test data.
- Reject a skill that repeats broad architecture without changing a concrete
future decision, hides uncertainty as fact, duplicates a neighboring skill,
or substitutes instructions for a missing platform contract.
Publish Canonically
The versioned source is this repository's codex-skills/; $CODEX_HOME/skills
is an installed projection. Never edit an installed copy as the authoritative
fix.
- Place the new skill in exactly one family manifest. Keep only real explicit
dependencies; do not use the manifest as a broad related-skills catalog.
- Update
skillMdSha256 and treeSha256 with the canonical audit flow.
- Run the skill-creator validator when available, then run the repository
structure validation and both family audits. Update generated issue drafts
when the repository's generator requires it.
- Sync the smallest family only after the source and manifest audit are clean.
Re-audit the installed target. Investigate an existing destination drift
instead of overwriting it casually.
For a selective installation, traverse the selected entries' manifest
dependencies transitively and inspect every required installed tree against
the canonical manifest. Reconcile missing/outdated dependencies within the
authorized scope, preserving unexplained local differences. Report entrypoint
parity and dependency-closure parity separately; a clean selected entrypoint
does not prove its companion guidance is current. Remaining family drift
outside that closure is a separate inventory result.
- Close with the classification, owner, evidence inspected, manifest change,
validation run, installation result, and any platform follow-up still open.
Do not claim a local installation is current merely because its directory exists.
The canonical tree hash and an audit are the proof.
Reviewing A Multi-Day Closure
Hash equality proves source/installation parity, not semantic coverage or runtime correctness.
For a retrospective, record the requested date range, repository/worktree heads, relevant committed
changes and uncommitted/untracked implementation evidence. Do not silently reduce several days to
the latest diff, or treat another task's later commit as part of an earlier validation.
Map each material behavior to its canonical source, public documentation, owner skill and focused
evidence. Separate guidance already adequate, guidance corrected, platform defects still open and
claims lacking proof. Retain links to tests or reproducible commands, not only ephemeral log paths
or historical passing counts. Distinguish documentation coverage, installation parity, fresh test
execution and remote integration in the closure. A documentation-only change may require no
generated artifacts itself while the underlying implementation still has publication or consumer
validation pending. Never turn that narrower conclusion into a full product certification.
1---2name: praxis-skill-authoring-governance3description: Use when creating, splitting, reviewing, retiring, or publishing a canonical Praxis Codex skill; when deciding whether recurring friction is a skill gap or a platform gap; or when reconciling skill scope, canonical owner, manifest dependencies, validation, and local-installation drift.4metadata:5 source: https://skillmd.com/skills/codexrodrigues/praxis-skill-authoring-governance6---78# Praxis Skill Authoring Governance910Treat a Praxis skill as executable platform guidance, not as generic documentation.11It must make a future implementation faster and more canonical by directing Codex to12the real owner, contracts, evidence, decisions, and focused proof.1314## Start From The Real Friction15161. Capture the concrete repeated task, the decision that consumes time, and the17 observable failure or rework it causes.182. Inspect the affected platform source, local `AGENTS.md`, public contracts,19 focused tests, operational examples, and direct consumers. Do not author from20 a remembered API or only a ticket description.213. Classify the finding:22 - `migration-skill-gap`: the platform already supports the outcome but the23 repeatable native route is absent or unclear;24 - `ja-suportado-so-ux` or `ja-suportado-mal-nomeado-ou-mal-materializado`:25 improve adoption or materialization, not the contract;26 - `suportado-parcialmente`: identify the owning follow-up and the temporary27 limit precisely;28 - `lacuna-real-de-contrato`: stop skill authoring as the primary remedy and29 open an owner-specific platform RFC or implementation follow-up.304. State the canonical owner. `praxis-metadata-starter` owns backend metadata,31 schemas, resources, surfaces, actions, capabilities, and `x-ui`.32 `praxis-config-starter` owns governed config and authoring persistence.33 `praxis-ui-angular` owns public runtime libraries. Quickstarts prove contracts;34 they do not redefine them.3536Do not turn a missing tool, contract, or semantic capability into prose that37teaches a consumer-local workaround. Do not route primary intent with keywords,38regexes, labels, or aliases.3940## Choose The Smallest Useful Skill4142Use one task-oriented skill when its workflow, evidence, owner, and validation43are coherent. Split only when a user can complete one task without loading the44other skill's detailed guidance. Keep `praxis-*` independent of Ergon/Archon;45put legacy discovery, Oracle behavior, migration gates, and Ergon evidence in46`ergon-*` skills.4748Read [portfolio-and-review.md](references/portfolio-and-review.md) when sizing a49new skill, reviewing overlap, or planning a delivery wave.5051Each skill must contain:5253- a trigger-rich frontmatter description;54- the canonical owner and the source paths/contracts that must be inspected;55- an evidence-first workflow with explicit decision points;56- prohibited local shortcuts and any required companion skills;57- the smallest validation that proves the promised outcome and derived-artifact58 decision.5960Keep `SKILL.md` procedural and concise. Put detailed matrices, examples, or61taxonomy in `references/`; add a script only for deterministic repeated work.6263## Author And Review64651. Create the skill with the standard initializer, then replace all template66 text. Keep its directory name and frontmatter `name` identical.672. Test the description against at least two realistic prompts: one that should68 trigger and one adjacent task that should not. Check that the workflow can69 lead to `already supported` as well as to an evidence-backed gap.703. For Java/Praxis guidance, inspect the actual starter annotations, base71 controllers/services, schema or discovery projection, focused tests, and a72 real host/consumer before asserting a canonical path. For Angular handoff,73 prove that the backend contract can materialize in the relevant runtime,74 including options, surfaces, actions, capabilities, errors, and applicable75 stats/export.764. Record expected side effects for commands and mutations. Development-database77 mutation authority may be pre-approved by the migration process, but the78 skill must still require scoped probes, evidence, and cleanup or rollback79 where the workflow creates test data.805. Reject a skill that repeats broad architecture without changing a concrete81 future decision, hides uncertainty as fact, duplicates a neighboring skill,82 or substitutes instructions for a missing platform contract.8384## Publish Canonically8586The versioned source is this repository's `codex-skills/`; `$CODEX_HOME/skills`87is an installed projection. Never edit an installed copy as the authoritative88fix.89901. Place the new skill in exactly one family manifest. Keep only real explicit91 dependencies; do not use the manifest as a broad related-skills catalog.922. Update `skillMdSha256` and `treeSha256` with the canonical audit flow.933. Run the skill-creator validator when available, then run the repository94 structure validation and both family audits. Update generated issue drafts95 when the repository's generator requires it.964. Sync the smallest family only after the source and manifest audit are clean.97 Re-audit the installed target. Investigate an existing destination drift98 instead of overwriting it casually.99 For a selective installation, traverse the selected entries' manifest100 dependencies transitively and inspect every required installed tree against101 the canonical manifest. Reconcile missing/outdated dependencies within the102 authorized scope, preserving unexplained local differences. Report entrypoint103 parity and dependency-closure parity separately; a clean selected entrypoint104 does not prove its companion guidance is current. Remaining family drift105 outside that closure is a separate inventory result.1065. Close with the classification, owner, evidence inspected, manifest change,107 validation run, installation result, and any platform follow-up still open.108109Do not claim a local installation is current merely because its directory exists.110The canonical tree hash and an audit are the proof.111112## Reviewing A Multi-Day Closure113114Hash equality proves source/installation parity, not semantic coverage or runtime correctness.115For a retrospective, record the requested date range, repository/worktree heads, relevant committed116changes and uncommitted/untracked implementation evidence. Do not silently reduce several days to117the latest diff, or treat another task's later commit as part of an earlier validation.118119Map each material behavior to its canonical source, public documentation, owner skill and focused120evidence. Separate guidance already adequate, guidance corrected, platform defects still open and121claims lacking proof. Retain links to tests or reproducible commands, not only ephemeral log paths122or historical passing counts. Distinguish documentation coverage, installation parity, fresh test123execution and remote integration in the closure. A documentation-only change may require no124generated artifacts itself while the underlying implementation still has publication or consumer125validation pending. Never turn that narrower conclusion into a full product certification.