Skip to content

Commit 20cca16

Browse files
pinin4fjordsclaude
andcommitted
Refactor Claude skills for better delegation and reduced verbosity
This refactor addresses issues where skills that should invoke other skills often skip those invocations. Key changes: **Stronger delegation patterns:** - Add "Skill Dependencies (MANDATORY)" tables at top of skills - Use explicit ">>> STOP. INVOKE /skill NOW." checkpoint blocks - Replace passive "Use Skill tool with..." language with imperative commands **Reduced verbosity:** - run-tutorial: 408 → 214 lines (-48%) - validate: 249 → 194 lines (-22%) - Extract detailed content to reference files **New reference files:** - run-tutorial/references/acceptable-differences.md: What to flag vs ignore - run-tutorial/references/pr-workflow.md: PR creation workflow - shared/repo-conventions.md: Directory mapping used by multiple skills **New skill:** - check-inline-code: Review inline code formatting (from feature branch) All critical assertions and checks are preserved, either inline or in reference files. Writing style checks from PR #774 are maintained. Co-Authored-By: Claude Opus 4.5 <[email protected]>
1 parent ae49408 commit 20cca16

File tree

8 files changed

+403
-370
lines changed

8 files changed

+403
-370
lines changed
Lines changed: 91 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,91 @@
1+
---
2+
name: Check Inline Code Formatting
3+
description: Review inline code in markdown files for proper formatting and syntax highlighting. Check for missing backticks on CLI flags, filenames, and code elements. Verify that inline syntax highlighting (#!groovy) is used appropriately. Use when reviewing documentation or quiz questions.
4+
---
5+
6+
# Check Inline Code Formatting
7+
8+
Review inline code in markdown files for proper formatting and appropriate use of syntax highlighting.
9+
10+
## What to Check
11+
12+
### 1. Missing Backticks
13+
14+
The following should always be wrapped in backticks:
15+
16+
**CLI flags and options:**
17+
18+
- `-resume`, `-profile`, `-params-file`, `--input`, etc.
19+
20+
**Filenames and paths:**
21+
22+
- `nextflow.config`, `.command.sh`, `work/`, `modules/`, etc.
23+
24+
**Commands:**
25+
26+
- `nextflow run`, `nextflow log`, `docker run`, etc.
27+
28+
**Code elements:**
29+
30+
- Variable names: `params.input`, `outputDir`
31+
- Process names: `SAYHELLO`
32+
- Operators and methods: `collect()`, `map()`, `view()`
33+
- Directives: `container`, `publishDir`, `memory`
34+
35+
### 2. Inline Syntax Highlighting
36+
37+
Use `` `#!groovy code` `` for Groovy/Nextflow code that benefits from syntax colouring.
38+
39+
**DO use `#!groovy` for:**
40+
41+
- Variable interpolation: `` `#!groovy ${variable}` ``
42+
- Closures: `` `#!groovy { meta.id }` `` or `` `#!groovy .map { it * 2 }` ``
43+
- Method chains with closures: `` `#!groovy channel.of(1,2,3).map { it * 2 }` ``
44+
- String interpolation: `` `#!groovy "${greeting}-output.txt"` ``
45+
- Type declarations: `` `#!groovy param: String = 'value'` ``
46+
47+
**DO NOT use `#!groovy` for:**
48+
49+
- Single words or identifiers: use `` `outputDir` `` not `` `#!groovy outputDir` ``
50+
- Simple directives: use `` `container 'uri'` `` not `` `#!groovy container 'uri'` ``
51+
- Plain dot notation: use `` `processName.out` `` not `` `#!groovy processName.out` ``
52+
- Keywords alone: use `` `include` `` not `` `#!groovy include` ``
53+
54+
**The rule:** Only use `#!groovy` when there's meaningful syntax structure (braces, interpolation, operators) that highlighting will visually enhance. A single word or simple expression gains nothing from syntax highlighting.
55+
56+
### 3. Consistency
57+
58+
- Similar code references should be formatted the same way throughout a document
59+
- Quiz answer options should have consistent formatting
60+
61+
## Examples
62+
63+
### Good inline code formatting
64+
65+
```markdown
66+
Run the workflow with `nextflow run main.nf -resume`.
67+
68+
The `#!groovy ${greeting}` variable is interpolated into the string.
69+
70+
Set memory with `#!groovy process { withName: 'FOO' { memory = '4.GB' } }`.
71+
72+
The `container` directive specifies the Docker image.
73+
74+
Access outputs with `processName.out.outputName`.
75+
```
76+
77+
### Bad inline code formatting
78+
79+
```markdown
80+
<!-- Missing backticks -->
81+
82+
Run the workflow with nextflow run main.nf -resume.
83+
84+
<!-- Unnecessary #!groovy on single word -->
85+
86+
The `#!groovy container` directive specifies the image.
87+
88+
<!-- Missing #!groovy on closure -->
89+
90+
Transform with `.map { it.toUpperCase() }`.
91+
```

.claude/skills/find-todos/SKILL.md

Lines changed: 1 addition & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -7,15 +7,7 @@ description: Search markdown files, Nextflow scripts, and config files for TODO/
77

88
Search the training materials codebase for TODO and FIXME comments to identify pending work.
99

10-
## Working Directory
11-
12-
**IMPORTANT**: All commands in this skill must be executed from the repository root directory.
13-
14-
- The repository root is the directory containing `mkdocs.yml`, `docs/`, and `.github/`
15-
- Verify you are in the correct directory before running any commands (check for these files/folders)
16-
- All file paths in this skill are relative to the repository root
17-
- Do not change directories during skill execution
18-
- Use paths relative to repository root only
10+
Execute from repository root. See [../shared/repo-conventions.md](../shared/repo-conventions.md) for directory structure.
1911

2012
## Tasks to Perform
2113

0 commit comments

Comments
 (0)