Imported from shynlee04/hivemind-plugin (assets/.hivemind/skills/hf-l2-use-authoring-skills/SKILL.md). Install upstream with npx skills add shynlee04/hivemind-plugin --skill hf-l2-use-authoring-skills. Copyright stays with the author.

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 scripts/verify-hierarchy.sh use-authoring-skills

   This checks that meta-builder exists and routed to this skill.

2. Register this skill as loaded:

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

3. 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...".

2. 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."

3. 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.

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

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

6. 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.

Enforcement lives primarily in SKILL.md text (Iron Law + Validation Gate). Scripts supplement for mechanical checks (structure validation, gate enforcement). If a script ever becomes a stub (exits 0 without checking), delete it — the text enforcement is the source of truth.

Validation Gate

Before a skill is done:

• Description has trigger phrases (specific things users would say)
• Description uses third person
• SKILL.md body uses imperative form
• SKILL.md is lean (1,500-2,000 words, <5k max)
• All referenced files exist and have real content (not stubs)
• No script stubs that exit 0 always
• No dead references to files/scripts that don't exist
• Works standalone — doesn't require other HiveMind skills

Three Operating Rules

1. Run validate-gate.sh first — before reading, writing, or planning anything.
2. Procedures over declarations — teach HOW, not WHAT. Use checklists for 3+ step workflows.
3. Validate before done — run the validation loop (STEP 7–9). No exceptions.

Self-Correction

When the Task Keeps Failing

[Detection] validate-skill.sh repeatedly fails (3+ iterations). check-overlaps.sh reports persistent conflicts. Critic subagent keeps flagging the same issues after 3 fix cycles. [Recovery] STOP the validation loop. Read the exact failure messages from each failing script. Address the root cause rather than patching symptoms. If overlap conflicts persist: the skill may need scope reduction or should be merged with the overlapping skill. If critic reports are unclear: ask the user which specific principle is violated before continuing. Do not exceed 5 total iterations — beyond that, the skill needs redesign, not refinement.

When Unsure About the Next Step

[Detection] The user's request doesn't clearly map to any decision tree path. validate-gate.sh exits with an ambiguous error. Pattern selection (P1/P2/P3) is unclear for the task. [Recovery] Run bash scripts/validate-gate.sh <action> "<user-request>" <dir> to create task_plan.md — this will clarify intent and pattern. Check the pattern field in task_plan.md: if unset, default to P2 (balanced depth) for most authoring tasks. Use the question tool for up to 3 clarifications — but proceed with reasonable defaults if still unclear after 3 questions.

When the User Contradicts Skill Guidance

[Detection] User says "don't bother with the checklist" or "skip validation, just write it" or "I know the agentskills.io spec, ignore it." User wants to bypass the 10-step checklist or validation loop. [Recovery] Acknowledge the user's authority but warn: "Skipping validation means the skill may have broken frontmatter, phantom references, or dead trigger phrases. The skill may silently fail to load." If the user insists, document skipped steps in task_plan.md and mark the skill as "unvalidated." Never claim a skill passed validation if any gate was skipped.

When an Edge Case Is Encountered

[Detection] Skill being audited uses a non-standard frontmatter format (different YAML spec). User wants to author a skill for a platform not in the adaptation table. Script fails due to missing dependency (bash version, jq not installed). Skill has content in multiple languages. [Recovery] For non-standard frontmatter: validate against agentskills.io spec and flag deviations. For unsupported platforms: apply agentskills.io patterns as the lowest common denominator, then document platform-specific adaptations. For missing dependencies: check if the script has fallback logic — if not, inform the user which dependency is needed. For multi-language skills: treat the primary language as canonical and flag translations for separate review.