---
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 compact-kernel lint findings as blocking; report owner lanes as `master <skill-id>` while keeping manifest role `owner`.
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.

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

```bash
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
```
