codex-skill-authoring

name	codex-skill-authoring
description	Use when creating, renaming, retrofitting, linting, or scaffolding repo-local Codex skills for hushh-research.

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 context-size findings from ./bin/hushh codex audit as review-required advisories: extract durable detail before adding more SOP, but do not split a skill just because it crosses a line-count threshold.
11. Enforce the truth-first operating kernel through deterministic smoke fixtures so skills, workflows, and agents do not slide back into blind premise acceptance.

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/skill_lint.py
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