shynlee04/hivemind-plugin/hf-l2-use-authoring-skills

The Iron Law

NO SKILL WITHOUT TRIGGER PHRASES IN THE DESCRIPTION

<files_to_read> .opencode/skills/use-authoring-skills/references/01-skill-anatomy.md .opencode/skills/use-authoring-skills/references/02-frontmatter-standard.md .opencode/skills/use-authoring-skills/references/03-three-patterns.md .opencode/skills/use-authoring-skills/references/05-skill-quality-matrix.md .opencode/skills/use-authoring-skills/scripts/validate-gate.sh .opencode/skills/use-authoring-skills/scripts/validate-skill.sh .opencode/skills/use-authoring-skills/scripts/check-overlaps.sh .opencode/get-shit-done/references/thinking-models-execution.md </files_to_read>

The description is the ONLY thing the agent sees before deciding to load a skill. If it doesn't contain specific phrases a user would say, the skill is invisible. Dead on arrival.

Not "the description should be good." The description IS the skill. Without it, nothing else matters.

What agents actually rationalize

HIERARCHY ENFORCEMENT — Run This FIRST

This skill is LAYER 4 in the loading chain (domain execution). Before any action:

1. Verify hierarchy chain:

``bash bash scripts/verify-hierarchy.sh use-authoring-skills `` This checks that meta-builder exists and routed to this skill.

1. Register this skill as loaded:

``bash bash scripts/register-skill.sh use-authoring-skills ``

1. Prerequisites:

• meta-builder must exist (routing source)
• Background skills should already be loaded by upstream skills

If hierarchy check fails → STOP. This skill should only be loaded after meta-builder routing.

Use Authoring Skills

MANDATORY FIRST STEP — Run This Before Anything Else

Every time this skill loads, run the preflight validator immediately:

bash scripts/validate-gate.sh <create|edit|audit> "<user-request>" <skill-dir>

• <create> — building a new skill from scratch or from a document
• <edit> — modifying an existing skill
• <audit> — reviewing/grading an existing skill
• <user-request> — the user's exact words in quotes
• <skill-dir> — directory where the skill lives (default: .)

If this exits non-zero, you are BLOCKED. Fix the reported issue and re-run. Do not proceed to any other step until Gate 0 passes.

Step-by-Step Checklist (Follow In Order)

Copy this checklist into task_plan.md and check off each item as you complete it. You may not skip steps.

- [ ] STEP 1: Run validate-gate.sh — must exit 0
- [ ] STEP 2: Run decision tree below — pick ONE path
- [ ] STEP 3: Load the ONE matching reference file (not all)
- [ ] STEP 4: Ask questions if unclear (max 3, question tool only)
- [ ] STEP 5: Write frontmatter — run validate-skill.sh
- [ ] STEP 6: Write body — follow agentskills.io principles (see below)
- [ ] STEP 7: Run validate-skill.sh — if FAIL, fix and repeat STEP 7
- [ ] STEP 8: Run check-overlaps.sh — if FAIL, fix and repeat STEP 8
- [ ] STEP 9: Dispatch critic subagent for review — if FAIL, fix and repeat STEP 9
- [ ] STEP 10: Final validate-gate.sh re-run — must exit 0

Decision Tree — Pick Your Path

User says...                          → Load
─────────────────────────────────────────────────────────
"create a skill" / "make a skill"     → references/03-three-patterns.md
"create a skill like this @file"      → references/03-three-patterns.md (template path)
"audit this skill" / "review skill"   → references/05-skill-quality-matrix.md
"fix triggers" / "skill not loading"  → references/11-description-optimization.md
"improve this skill" / "refactor"     → references/07-iterative-refinement.md
"skill overlaps with..."              → references/08-conflict-detection.md
"write evals for skill"               → references/10-eval-lifecycle.md
"write scripts for skill"             → references/09-script-authoring.md
"make skill work on X platform"       → references/06-cross-platform-activation.md
"doctor" / "what's wrong with..."     → references/12-anti-deception.md

Rule: Load only ONE reference file from the decision tree. Do not load all references.

agentskills.io Principles (Apply During STEP 6)

These are the core design principles from agentskills.io. Apply them when writing skill content:

1. Procedures over declarations — Teach HOW to do something, not WHAT something is. Use imperative verbs: "Run this script", "Check the output", "If X, do Y". Avoid: "This skill handles...", "The agent should...".

1. Defaults, not menus — Pick one approach as the primary path. Mention alternatives in one sentence. Do not present 5 options and ask the agent to choose. Example: "Use bash scripts/validate-skill.sh to validate. For Python-only skills, pytest is an acceptable alternative."

1. Match specificity to fragility — Be prescriptive for fragile steps (file formats, YAML syntax, tool invocation). Be flexible for creative steps (body content, examples). Frontmatter format = prescriptive. Example scenarios = flexible.

1. Checklists for multi-step workflows — Any workflow with 3+ steps must be a checklist with [ ] items. Agents check items off as they go.

1. Validation loops — Every significant action follows: do → validate → fix → repeat. Never declare done without running the validator.

1. Bundle scripts in scripts/ — Reusable validation, initialization, and cleanup logic lives in scripts/. Reference them from SKILL.md, don't inline shell commands.

Validation Loop (STEP 7–9)

After writing skill content, enter this loop:

LOOP START:
  1. Run: bash scripts/validate-skill.sh <skill-dir>
  2. If exit code ≠ 0:
     - Read the FAIL messages
     - Fix each issue
     - Go to step 1
  3. Run: bash scripts/check-overlaps.sh <skill-dir>
  4. If exit code ≠ 0:
     - Read overlap warnings
     - Resolve conflicts
     - Go to step 3
  5. Dispatch critic subagent:
     - Task: "Review this skill against agentskills.io principles"
     - Pass: skill-dir path + the agentskills.io principles from this file
     - If critic reports issues → fix them → go to step 1
  6. All checks passed → exit loop
LOOP END

Maximum iterations: 5. If the loop hasn't passed after 5 iterations, stop and report what's blocking.

Question Enforcement (STEP 4)

When intent is unclear:

• Maximum 3 questions per session. Not 4. Not "just one more."
• Use the question tool only. Do not ask questions in plain text output.
• Wait for answers before proceeding to implementation.
• If still unclear after 3 questions, proceed with the most reasonable default and document the assumption in task_plan.md.

Gate System

Run enforcement: bash scripts/validate-gate.sh <action> "<request>" <dir> — exits non-zero if blocked.

Worked Example: Document → Skill Conversion

Input: User provides a 200-line markdown command file to convert into a skill.

STEP 1: bash scripts/validate-gate.sh create "Convert this command file into a skill" . → exits 0, creates task_plan.md.

STEP 2: Decision tree → "create a skill like this @file" → load references/03-three-patterns.md.

STEP 3: Pattern decision: focused how-to guide → P2 (balanced depth). Record in task_plan.md.

STEP 4: Questions if needed (max 3 via question tool).

STEP 5: Write frontmatter:

---
name: hf-l2-use-authoring-skills
description: Synthesizes Repomix-packed codebase analysis into structured research reports with citations. Use when the user asks to analyze a codebase deeply, create research reports from Repomix output, or synthesize findings from multiple code sources.
---

Run bash scripts/validate-skill.sh . → passes.

STEP 6: Write body following agentskills.io principles (procedures, defaults, checklists).

STEP 7–9: Validation loop → validate-skill.sh → check-overlaps.sh → critic subagent → all pass.

STEP 10: bash scripts/validate-gate.sh create "Convert this command file into a skill" . → exits 0.

Output: Complete skill at target directory with references/ and scripts/.

Anti-Patterns — With Detection

Platform Adaptation

Always write frontmatter per agentskills.io spec — it is the lowest common denominator.

Scripts

All 8 scripts passed audit — each has real validation logic, exits non-zero on failure, and contains no placeholder/TODO text. Unlike stub scripts (which exit 0 always), these enforce actual constraints.