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.

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/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