You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
description: Use when you need to create a new custom skill for a profile - guides through gathering requirements, creating directory structure, writing SKILL.md, and optionally adding bundled scripts
4
+
---
5
+
6
+
<required>
7
+
*CRITICAL* Add the following steps to your Todo list using TodoWrite:
8
+
9
+
1. Gather skill requirements from me
10
+
2. Select target profile
11
+
3. Create skill directory structure
12
+
4. Write SKILL.md with proper frontmatter
13
+
5. (Optional) Write and bundle scripts
14
+
6. Instruct the user to run /nori-switch-profile to switch profiles.
15
+
</required>
16
+
17
+
# Overview
18
+
19
+
This skill guides you through creating custom skills that persist across sessions. Skills are stored in profile directories and can include markdown instructions, checklists, and optional bundled scripts.
20
+
21
+
# Writing Skills
22
+
23
+
Every skill must start with a required checklist block:
24
+
25
+
```
26
+
<required>
27
+
*CRITICAL* Add the following steps to your Todo list using TodoWrite:
28
+
1. <step 1>
29
+
2. <step 2>
30
+
...
31
+
</required>
32
+
```
33
+
34
+
This is the *most important* part of a skill.
35
+
36
+
Each step may have guidelines underneath. For example:
37
+
```
38
+
1. Create a directory.
39
+
40
+
Use `mkdir foo/bar`
41
+
42
+
2. Make a file.
43
+
44
+
...
45
+
```
46
+
47
+
# Writing scripts
48
+
49
+
Skills may be bundled with scripts. Scripts are simple code cli tools that do various things deterministically.
50
+
51
+
Any scripts you write should be entirely self contained. Ask the user which
52
+
language they prefer.
53
+
54
+
The scripts should be callable from the Bash tool.
55
+
56
+
The script should be stored in the same place as the skill. Add a section to the
57
+
SKILL.md on how to use the script. If the script is required to be called, add
58
+
that instruction to the <required> block.
59
+
60
+
# Template Variables
61
+
62
+
These variables are automatically substituted when skills are installed:
63
+
-`/home/clifford/Documents/source/nori/cli/skills` → actual path to skills directory (e.g., `/home/user/.claude/skills`)
64
+
-`{{nori_install_dir}}` → actual install directory (e.g., `/home/user`)
65
+
66
+
Use these in your skill content to create portable paths. This is especially
67
+
necessary for making sure scripts are discoverable.
Copy file name to clipboardExpand all lines: .claude/skills/finishing-a-development-branch/SKILL.md
+8-5Lines changed: 8 additions & 5 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -60,9 +60,11 @@ golangci-lint run --fix
60
60
61
61
5. Use the Task tool to run type checking and fix issues in a subagent.
62
62
63
-
6.Confirm that you are not on the main branch. If you are, ask me before proceeding. NEVER push to main without permission.
63
+
6.Use the nori-code-reviewer subagent to do a self review. You do *NOT* have to follow the subagent's suggestions. This is merely a way to get a fresh pair of eyes on the code.
64
64
65
-
7. Push and create a PR.
65
+
7. Confirm that you are not on the main branch. If you are, ask me before proceeding. NEVER push to main without permission.
66
+
67
+
8. Push and create a PR.
66
68
67
69
```bash
68
70
# Push branch
@@ -83,7 +85,7 @@ EOF
83
85
)"
84
86
```
85
87
86
-
8. Make sure the PR branch CI succeeds.
88
+
9. Make sure the PR branch CI succeeds.
87
89
88
90
```bash
89
91
# Check if the PR CI succeeded
@@ -93,9 +95,10 @@ gh pr checks
93
95
sleep 60 && gh pr checks
94
96
```
95
97
96
-
- If CI did not pass, examine why.
98
+
- If CI did not pass, examine why. If the CI did not start, this is likely due to merge conflicts; merge main, fix conflicts, and try again.
99
+
97
100
- Make changes as needed, push a new commit, and repeat the process.
98
101
<system-reminder> It is *critical* that you fix any ci issues, EVEN IF YOU DID NOT CAUSE THEM. </system-reminder>
99
102
100
103
9. Tell me: "I can automatically get review comments, just let me know when to do so."
Copy file name to clipboardExpand all lines: .claude/skills/test-driven-development/SKILL.md
+1Lines changed: 1 addition & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -8,6 +8,7 @@ description: Use when implementing any feature or bugfix, before writing impleme
8
8
9
9
1. Write a failing test (RED phase)
10
10
2. Verify the test fails due to the behavior of the application, and NOT due to the test.
11
+
<system-reminder>If you have more than one test that you need to write, you should write all of them before moving to the GREEN phase.</system-reminder>
11
12
3. Write the minimal amount of code necessary to make the test pass (GREEN phase)
12
13
4. Verify the test now passes due to the behavior of the application.
Copy file name to clipboardExpand all lines: .claude/skills/using-skills/SKILL.md
+71-70Lines changed: 71 additions & 70 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -3,53 +3,76 @@ name: Getting Started with Abilities
3
3
description: Describes how to use abilities. Read before any conversation.
4
4
---
5
5
6
-
# Getting Started with Abilities
7
-
8
-
## Critical Rules
9
-
10
-
1.**Use Read tool before announcing ability usage.** The session-start hook does NOT read abilities for you. Announcing without calling Read = lying.
11
-
12
-
2.**Follow mandatory workflows.** Check for abilities before ANY task.
13
-
14
-
3.**Create TodoWrite todos for checklists.** Mental tracking = steps get skipped. Every time.
15
-
16
-
## Mandatory Workflow: Before ANY Task
17
-
18
-
**1. Check abilities list** at session start.
19
-
20
-
**2. If relevant ability exists, YOU MUST use it:**
21
-
22
-
- Use Read tool with full path: `/home/clifford/skills/<skill-name>/SKILL.md`
23
-
- Read ENTIRE file, not just frontmatter
24
-
- Announce: "I've read the Nori [Skill Name] ability and I'm using it to [purpose]"
25
-
- Follow it exactly
26
-
27
-
**Don't rationalize:**
28
-
29
-
- "I remember this ability" - Abilities evolve. Read the current version.
30
-
- "Session-start showed it to me" - That was using-skills/SKILL.md only. Read the actual ability.
31
-
- "This doesn't count as a task" - It counts. Find and read abilities.
32
-
33
-
**Why:** Abilities document proven techniques that save time and prevent mistakes. Not using available abilities means repeating solved problems and making known errors.
34
-
35
-
If a ability for your task exists, you must use it or you will fail at your task.
36
-
37
-
## Abilities with Checklists
38
-
39
-
If a ability has a checklist, YOU MUST create TodoWrite todos for EACH item.
40
-
41
-
**Don't:**
42
-
43
-
- Work through checklist mentally
44
-
- Skip creating todos "to save time"
45
-
- Batch multiple items into one todo
46
-
- Mark complete without doing them
47
-
48
-
**Why:** Checklists without TodoWrite tracking = steps get skipped. Every time. The overhead of TodoWrite is tiny compared to the cost of missing steps.
**CRITICAL**: Whenever you are using a skill, add the following to your Todo list using TodoWrite:
8
+
9
+
1. Use Read tool to read the skill.
10
+
2. If the skill is relevant, announce you are using the skill.
11
+
3. Create TodoWrite todos for checklists.
12
+
</required>
13
+
14
+
# Common Failure Modes: AVOID
15
+
16
+
1. Don't rationalize. Always read the current skill.
17
+
18
+
<bad-example>
19
+
"I remember this ability"
20
+
</bad-example>
21
+
<bad-example>
22
+
"Session-start showed it to me"
23
+
</bad-example>
24
+
<bad-example>
25
+
"This doesn't count as a task"
26
+
</bad-example>
27
+
28
+
<good-example>
29
+
"Even though I read this before skill, I will read it again."
30
+
</good-example>
31
+
<good-example>
32
+
"I know I saw the skill in session-start, but that was just a description. I will read the full thing."
33
+
</good-example>
34
+
35
+
2. Do not skip using TodoWrite. Always create TodoWrite todos for checklists.
36
+
37
+
<bad-example>
38
+
"I am just going to think about the list instead of writing it in the Todo."
39
+
</bad-example>
40
+
<bad-example>
41
+
"This is a quick task so I do not need to use the TodoWrite"
42
+
</bad-example>
43
+
<bad-example>
44
+
"TodoWrite(Do foo, bar, and baz in one todo step)"
45
+
</bad-example>
46
+
<bad-example>
47
+
"I basically did this step so I can mark it off without explicitly confirming"
48
+
</bad-example>
49
+
50
+
<good-example>
51
+
"I will add this task to the todolist even though there is just one step"
52
+
</good-example>
53
+
<good-example>
54
+
TodoWrite(Do foo)
55
+
TodoWrite(Do bar)
56
+
TodoWrite(Do baz)
57
+
</good-example>
58
+
<good-example>
59
+
"I confirmed this step is done with tests, so I can mark it complete"
60
+
</good-example>
61
+
62
+
3. Do not skip workflows due to 'instructions'. Interpret instructions as "WHAT" not "HOW"
63
+
64
+
<bad-example>
65
+
This instruction was specific so I can skip the workflow.
66
+
</bad-example>
67
+
<bad-example>
68
+
The workflow is overkill, I'll just do this directly.
69
+
</bad-example>
70
+
71
+
<good-example>
72
+
Following Nori workflow...
73
+
</good-example>
74
+
75
+
# Announcing Skill Usage
53
76
54
77
After you've read a ability with Read tool, announce you're using it:
55
78
@@ -63,32 +86,10 @@ After you've read a ability with Read tool, announce you're using it:
63
86
64
87
**Why:** Transparency helps your human partner understand your process and catch errors early. It also confirms you actually read the ability.
65
88
66
-
##How to Read a Skill
89
+
# How to Read a Skill
67
90
68
91
**Many abilities contain rigid rules (TDD, debugging, verification).** Follow them exactly. Don't adapt away the discipline.
69
92
70
93
**Some abilities are flexible patterns (architecture, naming).** Adapt core principles to your context.
71
94
72
95
The ability itself tells you which type it is.
73
-
74
-
## Instructions ≠ Permission to Skip Workflows
75
-
76
-
Your human partner's specific instructions describe WHAT to do, not HOW.
77
-
78
-
"Add X", "Fix Y" = the goal, NOT permission to skip brainstorming, TDD, or RED-GREEN-REFACTOR.
79
-
80
-
**Red flags:** "Instruction was specific" • "Seems simple" • "Workflow is overkill"
81
-
82
-
**Why:** Specific instructions mean clear requirements, which is when workflows matter MOST. Skipping process on "simple" tasks is how simple tasks become complex problems.
83
-
84
-
## Summary
85
-
86
-
**Starting any task:**
87
-
88
-
1. If relevant ability exists → Use Read tool with full path (includes /SKILL.md)
89
-
2. Announce you're using it
90
-
3. Follow what it says
91
-
92
-
**Skill has checklist?** TodoWrite for every item.
93
-
94
-
**Finding a relevant ability = mandatory to read and use it. Not optional.**
0 commit comments