codex-skill-authoring

Hussh Codex Skill Authoring Skill

Purpose and Trigger

• Primary scope: codex-skill-authoring-intake
• Trigger on creating or renaming repo-local skills, tightening the skill contract, adding skill tooling, or evolving the owner/spoke taxonomy.
• Avoid overlap with repo-context and docs-governance.

Coverage and Ownership

• Role: owner
• Owner family: codex-skill-authoring

Owned repo surfaces:

1. .codex/skills

Non-owned surfaces:

1. repo-context
2. docs-governance

Do Use

1. Creating new owner or spoke skills under .codex/skills.
2. Enforcing the shared local skill contract, skill.json manifests, and workflow-pack contracts.
3. Scaffolding skills, manifests, and workflow packs and validating the fleet for drift, overlap, or orphaned surfaces.

Do Not Use

1. Broad repo-orientation work that should start with repo-context.
2. Product implementation or subsystem-specific work that already belongs to another owner skill.
3. Docs-home governance outside the skill system itself.

Read First

1. .codex/skills/codex-skill-authoring/references/skill-contract.md
2. .codex/skills/codex-skill-authoring/references/truth-first-operating-kernel.md
3. .codex/skills/codex-skill-authoring/references/authoring-workflow.md
4. .codex/skills/repo-context/references/index-contract.md

Workflow

1. Run the skill linter before changing the skill fleet so the current drift and coverage state are explicit.
2. Decide whether the work needs a new owner, a new spoke, or a tighter existing skill.
3. Scaffold with init_skill.py using explicit role, owner family, owned repo surfaces, task types, verification bundles, and optional workflow packs.
4. Update the repo-context index, workflow packs, and agent-facing docs when a new entrypoint or rename becomes canonical.
5. For new owner skills or workflow-pack changes, run a second lint/audit pass after the edits instead of trusting the first clean run.
6. For licensing, onboarding, subtree, CI, or branch-governance skill changes, do a third check from the canonical repo entrypoint before calling the taxonomy stable.
7. Keep blocking versus advisory skill drift explicit. Only owner/workflow drift that weakens runtime, deploy, release, or test authority should block the core loop; metadata-only drift should stay advisory.
8. When PR governance comment templates change, enforce them through skill_lint.py so stale public-comment headings such as Acknowledgment, Verification, or maintainer-only Next do not re-enter generated templates.
9. Keep recurring SOPs short in skills and route durable detail to canonical docs or workflow packs. Skills should point to runtime-db-fact-sheet.md, the data-plane contract, or a workflow playbook rather than duplicating long table inventories.
10. Treat compact-kernel lint findings as blocking; report owner lanes as owner <skill-id> so the human-facing label matches the manifest role.
11. Enforce the truth-first operating kernel through deterministic smoke fixtures so skills, workflows, and agents do not slide back into blind premise acceptance.
12. For industry-grade skills, prefer a compact operating kernel in SKILL.md plus focused references/ files for detailed gates, templates, and calibration rules. Do not let incident-specific fixes accumulate as repeated inline SOP unless they belong in deterministic scripts or a focused reference.
13. When retrofitting a skill, scan the full skill body for duplicated rules, stale historical examples, and oversized decision trees. Keep the main skill procedural; move reusable detail into references and executable logic into scripts.
14. When a skill asks planning or operator questions, require research-backed question shape from the truth-first kernel: current truth, recommended path, risk if accepted blindly, decision needed, and recommended option first.
15. When skill or workflow changes alter docs homes, route through docs-governance and the docs/reference/README.md classification model instead of inventing a parallel docs taxonomy.
16. When route governance changes alter required reads or checks, update the owning frontend, cache, voice, mobile, docs, and surface-map skills together so future agents see the same route contract cascade.

Handoff Rules

1. If the task begins with broad repo discovery or choosing the correct owner family, start with repo-context.
2. If the task is docs-home governance outside the skill system, use docs-governance.
3. After skill creation or retrofit, hand off to the correct owner skill for the actual domain work.
4. Route licensing skill work to oss-license-governance, contributor setup skill work to contributor-onboarding, and upstream/subtree sync skill work to subtree-upstream-governance.

Required Checks

python3 .codex/skills/codex-skill-authoring/scripts/truth_first_smoke.py
python3 .codex/skills/codex-skill-authoring/scripts/compact_kernel_smoke.py
python3 .codex/skills/codex-skill-authoring/scripts/skill_lint.py
python3 .codex/skills/codex-skill-authoring/scripts/skill_fleet_audit.py --text
python3 .codex/skills/codex-skill-authoring/scripts/trigger_evals.py --text
python3 .codex/skills/codex-skill-authoring/scripts/init_skill.py --name example-owner --role owner --owner-family example-owner --owned-path README.md --task-type repo-orientation --verification-bundle example-owner --workflow-pack example-owner --dry-run
./bin/hushh codex audit
python3 -m py_compile .codex/skills/codex-skill-authoring/scripts/skill_lint.py .codex/skills/codex-skill-authoring/scripts/truth_first_smoke.py .codex/skills/codex-skill-authoring/scripts/init_skill.py .codex/skills/codex-skill-authoring/scripts/compact_kernel_smoke.py .codex/skills/codex-skill-authoring/scripts/skill_fleet_audit.py .codex/skills/codex-skill-authoring/scripts/trigger_evals.py .codex/skills/codex-skill-authoring/scripts/test_trigger_evals.py