agentleFS
hushh-labshushh-labs/hushh-research/.agents/skills/codex-skill-authoring/SKILL.md

codex-skill-authoring

Skill40 starsChanged 3 days agoApache-2.0View on GitHub

Use when creating, renaming, retrofitting, linting, or scaffolding repo-local Codex skills for hushh-research.

The file

Show its rules and text

We split this skill into the rules it gives an agent

14 rules. About 0 are common, 6 are distinctive, and 8 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈6

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 8

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Avoid overlap with repo-context and docs-governance.

    line 12
  2. Distinctive:

    Run the skill linter before changing the skill fleet so the current drift and coverage state are explicit.

    line 49
  3. Very specific:

    Update the repo-context index, workflow packs, and agent-facing docs when an entrypoint or rename becomes canonical.

    line 52
  4. Distinctive:

    Keep blocking versus advisory skill drift explicit.

    line 55
  5. Very specific:

    When PR governance comment templates change, enforce them through skill_lint.py so stale public-comment headings such as Acknowledgment, …

    line 56
  6. Very specific:

    Keep recurring SOPs short in skills and route durable detail to canonical docs or workflow packs.

    line 57
  7. Very specific:

    Treat compact-kernel lint findings as blocking.

    line 58
  8. Distinctive:

    When retrofitting a skill, scan the full skill body for duplicated rules, stale historical examples, and oversized decision trees.

    line 61
  9. Distinctive:

    When a skill asks planning or operator questions, require research-backed question shape from the truth-first kernel: current truth, …

    line 62
  10. Very specific:

    When skill or workflow changes alter docs homes, route through docs-governance and the docs/development/references.md classification model …

    line 63
  11. Distinctive:

    When route governance changes alter required reads or checks, update the owning frontend, cache, voice, mobile, docs, and surface-map …

    line 64
  12. Very specific:

    If the task begins with broad repo discovery or choosing the correct owner family, start with repo-context.

    line 68
  13. Very specific:

    If the task is docs-home governance outside the skill system, use docs-governance.

    line 69
  14. Distinctive:

    After skill creation or retrofit, hand off to the correct owner skill for the actual domain work.

    line 70

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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. .agents/skills

Non-owned surfaces:

  1. repo-context
  2. docs-governance

Do Use

  1. Creating new owner or spoke skills under .agents/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. .agents/skills/codex-skill-authoring/references/skill-contract.md
  2. .agents/skills/codex-skill-authoring/references/truth-first-operating-kernel.md
  3. .agents/skills/codex-skill-authoring/references/authoring-workflow.md
  4. .agents/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 an entrypoint or rename becomes canonical. Read canonical .agents/ sources directly; verify actual host discovery separately. Do not generate per-host adapters or fleet copies.
  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/development/references.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 .agents/skills/codex-skill-authoring/scripts/truth_first_smoke.py
python3 .agents/skills/codex-skill-authoring/scripts/compact_kernel_smoke.py
python3 .agents/skills/codex-skill-authoring/scripts/skill_lint.py
python3 .agents/skills/codex-skill-authoring/scripts/skill_fleet_audit.py --text
python3 .agents/skills/codex-skill-authoring/scripts/trigger_evals.py --text
python3 .agents/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 agents audit
python3 -m py_compile .agents/skills/codex-skill-authoring/scripts/skill_lint.py .agents/skills/codex-skill-authoring/scripts/truth_first_smoke.py .agents/skills/codex-skill-authoring/scripts/init_skill.py .agents/skills/codex-skill-authoring/scripts/compact_kernel_smoke.py .agents/skills/codex-skill-authoring/scripts/skill_fleet_audit.py .agents/skills/codex-skill-authoring/scripts/trigger_evals.py .agents/skills/codex-skill-authoring/scripts/test_trigger_evals.py

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.