Align skill with Anthropic skills guide

agents/nelson.md

@@ -1,6 +1,6 @@
 ---
 name: nelson
-description: England expects every agent to do its duty
+description: Coordinates multi-agent work using Royal Navy squadron patterns with sailing orders, risk-tiered quality gates, and a captain's log.
 ---
 
 # Nelson

scripts/check-references.sh

@@ -11,65 +11,36 @@ error() {
 }
 
 # ---------- 1. SKILL.md → references ----------
-# Every backtick-quoted path in MUST read/consult/use directives
+# Every backtick-quoted references/ path in SKILL.md must exist
 echo "Checking SKILL.md → reference files..."
 while IFS= read -r path; do
   if [ ! -f "$SKILL_DIR/$path" ]; then
     error "SKILL.md references '$path' but $SKILL_DIR/$path does not exist"
   fi
-# Case-insensitive: match "MUST" regardless of markdown emphasis
-done < <(grep -Ei 'MUST (read|consult|use|read and apply)' "$SKILL_DIR/SKILL.md" \
-  | grep -oE '`references/[^`]+`' \
+done < <(grep -oE '`references/[^`]+\.md`' "$SKILL_DIR/SKILL.md" \
   | tr -d '`' \
   | sort -u)
 
-# ---------- 2. Index → sub-files ----------
-# Each index file's backtick-quoted .md paths must resolve
-for index in admiralty-templates standing-orders damage-control; do
-  index_file="$REF_DIR/$index.md"
-  if [ ! -f "$index_file" ]; then
-    error "Index file $index_file does not exist"
-    continue
-  fi
-
-  echo "Checking $index.md → sub-files..."
-  while IFS= read -r path; do
-    if [ ! -f "$REF_DIR/$path" ]; then
-      error "$index.md references '$path' but $REF_DIR/$path does not exist"
-    fi
-  done < <(grep -oE "\`${index}/[^\`]+\.md\`" "$index_file" \
-    | tr -d '`' \
-    | sort -u)
-done
-
-# ---------- 3. Sub-file → index (orphan check) ----------
-# Every .md in a sub-directory must be listed in its parent index
-for index in admiralty-templates standing-orders damage-control; do
-  index_file="$REF_DIR/$index.md"
-  subdir="$REF_DIR/$index"
-  [ -d "$subdir" ] || continue
-
-  echo "Checking for orphans in $index/..."
-  for file in "$subdir"/*.md; do
-    # Skip if glob matched no files (bash returns literal pattern)
+# ---------- 2. Subdirectory orphan check ----------
+# Every .md in a subdirectory must be referenced somewhere in SKILL.md
+echo "Checking for orphaned subdirectory files..."
+for subdir in admiralty-templates standing-orders damage-control; do
+  [ -d "$REF_DIR/$subdir" ] || continue
+  for file in "$REF_DIR/$subdir"/*.md; do
     [ -f "$file" ] || continue
     basename=$(basename "$file")
-    if ! grep -qE "\`${index}/${basename}\`" "$index_file"; then
-      error "$index/$basename exists on disk but is not listed in $index.md"
+    if ! grep -qE "\`references/${subdir}/${basename}\`" "$SKILL_DIR/SKILL.md"; then
+      error "$subdir/$basename exists on disk but is not referenced in SKILL.md"
     fi
   done
 done
 
-# ---------- 4. Reference file cross-refs ----------
-# Backtick-quoted paths in non-index reference files
+# ---------- 3. Reference file cross-refs ----------
+# Backtick-quoted paths in top-level reference files
 echo "Checking cross-references in reference files..."
 for ref_file in "$REF_DIR"/*.md; do
   [ -f "$ref_file" ] || continue
   basename=$(basename "$ref_file")
-  # Skip index files (they are validated in Section 2)
-  case "$basename" in
-    admiralty-templates.md|standing-orders.md|damage-control.md) continue ;;
-  esac
 
   # Paths like `references/foo.md` (relative to skill root)
   while IFS= read -r path; do
@@ -90,7 +61,7 @@ for ref_file in "$REF_DIR"/*.md; do
     | sort -u)
 done
 
-# ---------- 5. Subdirectory file cross-refs ----------
+# ---------- 4. Subdirectory file cross-refs ----------
 # Backtick-quoted paths in subdirectory files
 echo "Checking cross-references in subdirectory files..."
 for subdir in admiralty-templates standing-orders damage-control; do
@@ -119,19 +90,15 @@ for subdir in admiralty-templates standing-orders damage-control; do
   done
 done
 
-# ---------- 6. Reverse orphan check ----------
-# Every top-level .md in references/ should be referenced by a MUST directive in SKILL.md
+# ---------- 5. Reverse orphan check ----------
+# Every top-level .md in references/ should be referenced by SKILL.md
 echo "Checking for unreferenced top-level reference files..."
 for ref_file in "$REF_DIR"/*.md; do
   [ -f "$ref_file" ] || continue
   basename=$(basename "$ref_file")
-  # Skip index files (their sub-files are already checked in Section 2)
-  case "$basename" in
-    admiralty-templates.md|standing-orders.md|damage-control.md) continue ;;
-  esac
 
   if ! grep -qE "\`references/${basename}\`" "$SKILL_DIR/SKILL.md"; then
-    error "$basename exists in references/ but is not referenced by any MUST directive in SKILL.md"
+    error "$basename exists in references/ but is not referenced in SKILL.md"
   fi
 done
 

skills/nelson/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: nelson
-description: Command a Royal Navy agent squadron from sailing orders through execution and stand-down. Use when work can be parallelized, requires tight coordination, or needs explicit action-station controls, quality gates, and a final captain's log.
+description: Commands a Royal Navy agent squadron from sailing orders through execution and stand-down. Use when work can be parallelized, requires tight coordination, or needs explicit action-station controls, quality gates, and a final captain's log.
+argument-hint: "[mission description]"
 ---
 
 # Nelson
@@ -14,7 +15,7 @@ Execute this workflow for the user's mission.
 - Define what is out of scope.
 - Define stop criteria and required handoff artifacts.
 
-You MUST read `references/admiralty-templates.md` and use the sailing-orders template when the user does not provide structure.
+You MUST read `references/admiralty-templates/sailing-orders.md` and use the sailing-orders template when the user does not provide structure.
 
 ## 2. Form The Squadron
 
@@ -29,11 +30,11 @@ You MUST read `references/admiralty-templates.md` and use the sailing-orders tem
 - Do not exceed 10 squadron-level agents (admiral, captains, red-cell navigator). Crew are additional.
 - Assign each captain a ship name from `references/crew-roles.md` matching task weight (frigate for general, destroyer for high-risk, patrol vessel for small, flagship for critical-path, submarine for research).
 - Captain decides crew composition per ship using the crew-or-direct decision tree in `references/crew-roles.md`.
-- Captains may also deploy Royal Marines during execution for short-lived sorties — see `references/royal-marines.md`.
+- Captains may also deploy Royal Marines during execution for short-lived sorties — see `references/royal-marines.md` and use `references/admiralty-templates/marine-deployment-brief.md` for the deployment brief.
 
 You MUST read `references/squadron-composition.md` for selection rules.
 You MUST read `references/crew-roles.md` for ship naming and crew composition.
-You MUST consult `references/standing-orders.md` before forming the squadron.
+You MUST consult the Standing Orders table below before forming the squadron.
 
 ## 3. Draft Battle Plan
 
@@ -43,12 +44,13 @@ You MUST consult `references/standing-orders.md` before forming the squadron.
 - Keep one task in progress per agent unless the mission explicitly requires multitasking.
 - For each captain's task, include a ship manifest. If crew are mustered, list crew roles with sub-tasks and sequence. If the captain implements directly (0 crew), note "Captain implements directly." If the captain anticipates needing marine support, note marine capacity in the ship manifest (max 2).
 
-You MUST read `references/admiralty-templates.md` for the battle plan and ship manifest template.
-You MUST consult `references/standing-orders.md` when assigning files or if scope is unclear.
+You MUST read `references/admiralty-templates/battle-plan.md` for the battle plan template.
+You MUST read `references/admiralty-templates/ship-manifest.md` for the ship manifest template.
+You MUST consult the Standing Orders table below when assigning files or if scope is unclear.
 
 **Before proceeding to Step 4:** Verify sailing orders exist, squadron is formed, and every task has an owner, deliverable, and action station tier.
 
-**Crew Briefing:** When spawning each teammate via `Task()`, you MUST include a crew briefing using the template from `references/admiralty-templates.md`. Teammates do NOT inherit the lead's conversation context — they start with a clean slate and need explicit mission context to operate independently.
+**Crew Briefing:** When spawning each teammate via `Task()`, you MUST include a crew briefing using the template from `references/admiralty-templates/crew-briefing.md`. Teammates do NOT inherit the lead's conversation context — they start with a clean slate and need explicit mission context to operate independently.
 
 ## 4. Run Quarterdeck Rhythm
 
@@ -61,10 +63,10 @@ You MUST consult `references/standing-orders.md` when assigning files or if scop
 - Check for active marine deployments; verify marines have returned and outputs are incorporated.
 - Track burn against token/time budget.
 - Re-scope early when a task drifts from mission metric.
-- When a mission encounters difficulties, you MUST consult `references/damage-control.md` for recovery and escalation procedures.
+- When a mission encounters difficulties, you MUST consult the Damage Control table below for recovery and escalation procedures.
 
-You MUST  use `references/admiralty-templates.md` for the quarterdeck report template.
-You MUST consult `references/standing-orders.md` if admiral is doing implementation or tasks are drifting from scope.
+You MUST use `references/admiralty-templates/quarterdeck-report.md` for the quarterdeck report template.
+You MUST consult the Standing Orders table below if admiral is doing implementation or tasks are drifting from scope.
 You MUST use `references/commendations.md` for recognition signals and graduated correction.
 
 ## 5. Set Action Stations
@@ -78,10 +80,11 @@ You MUST use `references/commendations.md` for recognition signals and graduated
 - Task completion.
 - Agent idle with unverified outputs.
 - Before final synthesis.
-- For crewed tasks, verify crew outputs align with role boundaries (consult `references/crew-roles.md` and `references/standing-orders.md` if role violations are detected).
+- For crewed tasks, verify crew outputs align with role boundaries (consult `references/crew-roles.md` and the Standing Orders table below if role violations are detected).
 - Marine deployments follow station-tier rules in `references/royal-marines.md`. Station 2+ marine deployments require admiral approval.
 
-You MUST consult `references/standing-orders.md` if tasks lack a tier or red-cell is assigned implementation work.
+You MUST read `references/admiralty-templates/red-cell-review.md` for the red-cell review template.
+You MUST consult the Standing Orders table below if tasks lack a tier or red-cell is assigned implementation work.
 
 ## 6. Stand Down And Log Action
 
@@ -94,9 +97,41 @@ You MUST consult `references/standing-orders.md` if tasks lack a tier or red-cel
 - Mentioned in Despatches: name agents and contributions that were exemplary.
 - Record reusable patterns and failure modes for future missions.
 
-You MUST use `references/admiralty-templates.md` for the captain's log template.
+You MUST use `references/admiralty-templates/captains-log.md` for the captain's log template.
 You MUST use `references/commendations.md` for Mentioned in Despatches criteria.
 
+## Standing Orders
+
+Consult the specific standing order that matches the situation.
+
+| Situation | Standing Order |
+|---|---|
+| Choosing between single-session and multi-agent | `references/standing-orders/becalmed-fleet.md` |
+| Deciding whether to add another agent | `references/standing-orders/crew-without-canvas.md` |
+| Assigning files to agents in the battle plan | `references/standing-orders/split-keel.md` |
+| Task scope drifting from sailing orders | `references/standing-orders/drifting-anchorage.md` |
+| Admiral doing implementation instead of coordinating | `references/standing-orders/admiral-at-the-helm.md` |
+| Assigning work to the red-cell navigator | `references/standing-orders/press-ganged-navigator.md` |
+| Tasks proceeding without a risk tier classification | `references/standing-orders/unclassified-engagement.md` |
+| Captain implementing instead of coordinating crew | `references/standing-orders/captain-at-the-capstan.md` |
+| Crewing every role regardless of task needs | `references/standing-orders/all-hands-on-deck.md` |
+| Spawning one crew member for an atomic task | `references/standing-orders/skeleton-crew.md` |
+| Assigning crew work outside their role | `references/standing-orders/pressed-crew.md` |
+| Captain deploying marines for crew work or sustained tasks | `references/standing-orders/battalion-ashore.md` |
+
+## Damage Control
+
+Consult the specific procedure that matches the situation.
+
+| Situation | Procedure |
+|---|---|
+| Agent unresponsive, looping, or producing no useful output | `references/damage-control/man-overboard.md` |
+| Session interrupted (context limit, crash, timeout) | `references/damage-control/session-resumption.md` |
+| Completed task found faulty, other tasks are sound | `references/damage-control/partial-rollback.md` |
+| Mission cannot succeed, continuing wastes budget | `references/damage-control/scuttle-and-reform.md` |
+| Issue exceeds current authority or needs clarification | `references/damage-control/escalation.md` |
+| Ship's crew consuming disproportionate tokens or time | `references/damage-control/crew-overrun.md` |
+
 ## Admiralty Doctrine
 
 - Optimize for mission throughput, not equal work distribution.

skills/nelson/references/action-stations.md

@@ -2,6 +2,16 @@
 
 Classify each task before execution. Apply the minimum required controls.
 
+## Contents
+
+- [Station 0: Patrol](#station-0-patrol)
+- [Station 1: Caution](#station-1-caution)
+- [Station 2: Action](#station-2-action)
+- [Station 3: Trafalgar](#station-3-trafalgar)
+- [Risk Classification Decision Tree](#risk-classification-decision-tree)
+- [Failure-Mode Checklist](#failure-mode-checklist)
+- [Marine Deployments](#marine-deployments)
+
 ## Station 0: Patrol
 
 Criteria:

skills/nelson/references/squadron-composition.md

@@ -37,4 +37,4 @@ Choose the first condition that matches.
 
 ## Anti-Patterns
 
-See `references/standing-orders.md` for the full list of standing orders and known anti-patterns.
+See the Standing Orders table in SKILL.md for the full list of standing orders and known anti-patterns.