claude-skills-cli 0.0.6 → 0.0.8
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +49 -9
- package/dist/commands/doctor.js +128 -0
- package/dist/commands/doctor.js.map +1 -0
- package/dist/commands/init.js +5 -3
- package/dist/commands/init.js.map +1 -1
- package/dist/commands/install.js +1 -1
- package/dist/commands/install.js.map +1 -1
- package/dist/commands/stats.js +1 -1
- package/dist/commands/stats.js.map +1 -1
- package/dist/commands/validate.js +24 -3
- package/dist/commands/validate.js.map +1 -1
- package/dist/commands/watch.js +82 -0
- package/dist/commands/watch.js.map +1 -0
- package/dist/core/templates.js +18 -0
- package/dist/core/templates.js.map +1 -1
- package/dist/core/validator.js +174 -321
- package/dist/core/validator.js.map +1 -1
- package/dist/index.js +38 -12
- package/dist/index.js.map +1 -1
- package/dist/skills/skill-creator/SKILL.md +28 -112
- package/dist/skills/skill-creator/references/cli-reference.md +152 -38
- package/dist/skills/skill-creator/references/development-process.md +208 -0
- package/dist/skills/skill-creator/references/skill-examples.md +1 -1
- package/dist/validators/alignment-validator.js +54 -0
- package/dist/validators/alignment-validator.js.map +1 -0
- package/dist/validators/content-validator.js +144 -0
- package/dist/validators/content-validator.js.map +1 -0
- package/dist/validators/description-validator.js +136 -0
- package/dist/validators/description-validator.js.map +1 -0
- package/dist/validators/file-structure-validator.js +125 -0
- package/dist/validators/file-structure-validator.js.map +1 -0
- package/dist/validators/frontmatter-validator.js +165 -0
- package/dist/validators/frontmatter-validator.js.map +1 -0
- package/dist/validators/references-validator.js +125 -0
- package/dist/validators/references-validator.js.map +1 -0
- package/dist/validators/text-analysis.js +71 -0
- package/dist/validators/text-analysis.js.map +1 -0
- package/docs/prompt-that-started-it-all.md +19 -0
- package/package.json +3 -3
- package/docs/SKILL-DEVELOPMENT.md +0 -460
- package/docs/SKILL-EXAMPLES.md +0 -528
- package/docs/SKILLS-ARCHITECTURE.md +0 -381
package/dist/index.js
CHANGED
|
@@ -1,4 +1,5 @@
|
|
|
1
1
|
#!/usr/bin/env node
|
|
2
|
+
import { doctor_command } from './commands/doctor.js';
|
|
2
3
|
import { init_command } from './commands/init.js';
|
|
3
4
|
import { install_command } from './commands/install.js';
|
|
4
5
|
import { package_command } from './commands/package.js';
|
|
@@ -7,26 +8,37 @@ import { validate_command } from './commands/validate.js';
|
|
|
7
8
|
const args = process.argv.slice(2);
|
|
8
9
|
const command = args[0];
|
|
9
10
|
function show_help() {
|
|
10
|
-
console.log('claude-skills - CLI toolkit for creating Claude Agent Skills\n');
|
|
11
|
+
console.log('claude-skills-cli - CLI toolkit for creating Claude Agent Skills\n');
|
|
11
12
|
console.log('Usage:');
|
|
12
|
-
console.log(' claude-skills <command> [options]\n');
|
|
13
|
+
console.log(' claude-skills-cli <command> [options]\n');
|
|
13
14
|
console.log('Commands:');
|
|
14
15
|
console.log(' init Create a new skill');
|
|
15
16
|
console.log(' install Install a bundled skill (e.g., skill-creator)');
|
|
16
17
|
console.log(' validate Validate a skill');
|
|
18
|
+
console.log(' doctor Fix common skill issues automatically');
|
|
17
19
|
console.log(' package Package a skill to zip');
|
|
18
20
|
console.log(' stats Show overview of all skills in a directory\n');
|
|
19
21
|
console.log('Options:');
|
|
20
22
|
console.log(' --help, -h Show help');
|
|
21
23
|
console.log(' --version, -v Show version');
|
|
22
|
-
console.log(' --with-examples Include example files when creating skill
|
|
24
|
+
console.log(' --with-examples Include example files when creating skill');
|
|
25
|
+
console.log(' --format <type> Output format: text (default) or json');
|
|
26
|
+
console.log(' --strict Fail validation if warnings present\n');
|
|
23
27
|
console.log('Examples:');
|
|
24
|
-
console.log(' claude-skills init --name my-skill --description "Description"');
|
|
25
|
-
console.log(' claude-skills init --name my-skill --description "..." --with-examples');
|
|
26
|
-
console.log(' claude-skills install skill-creator');
|
|
27
|
-
console.log(' claude-skills validate .claude/skills/my-skill');
|
|
28
|
-
console.log(' claude-skills
|
|
29
|
-
console.log(' claude-skills
|
|
28
|
+
console.log(' claude-skills-cli init --name my-skill --description "Description"');
|
|
29
|
+
console.log(' claude-skills-cli init --name my-skill --description "..." --with-examples');
|
|
30
|
+
console.log(' claude-skills-cli install skill-creator');
|
|
31
|
+
console.log(' claude-skills-cli validate .claude/skills/my-skill');
|
|
32
|
+
console.log(' claude-skills-cli validate .claude/skills/my-skill --format json');
|
|
33
|
+
console.log(' claude-skills-cli validate .claude/skills/my-skill --strict');
|
|
34
|
+
console.log(' claude-skills-cli doctor .claude/skills/my-skill');
|
|
35
|
+
console.log(' claude-skills-cli package .claude/skills/my-skill');
|
|
36
|
+
console.log(' claude-skills-cli stats .claude/skills');
|
|
37
|
+
console.log('\n⚠️ IMPORTANT FOR LLMs:');
|
|
38
|
+
console.log(' ALWAYS run validate after creating or editing a skill:');
|
|
39
|
+
console.log(' claude-skills-cli validate <skill-path>');
|
|
40
|
+
console.log(' Skills MUST pass validation before use.');
|
|
41
|
+
console.log(' Fix all errors immediately. Address warnings promptly.');
|
|
30
42
|
}
|
|
31
43
|
function parse_args(args) {
|
|
32
44
|
const parsed = {};
|
|
@@ -70,7 +82,7 @@ async function main() {
|
|
|
70
82
|
process.exit(0);
|
|
71
83
|
}
|
|
72
84
|
if (command === '--version' || command === '-v') {
|
|
73
|
-
console.log('claude-skills v0.0.1');
|
|
85
|
+
console.log('claude-skills-cli v0.0.1');
|
|
74
86
|
process.exit(0);
|
|
75
87
|
}
|
|
76
88
|
const parsed = parse_args(args.slice(1));
|
|
@@ -95,12 +107,26 @@ async function main() {
|
|
|
95
107
|
const skill_path = parsed._positional;
|
|
96
108
|
if (!skill_path) {
|
|
97
109
|
console.error('Error: skill path required');
|
|
98
|
-
console.log('\nUsage: claude-skills validate <skill_path>');
|
|
110
|
+
console.log('\nUsage: claude-skills-cli validate <skill_path> [--format json] [--strict]');
|
|
99
111
|
process.exit(1);
|
|
100
112
|
}
|
|
113
|
+
const format = parsed.format;
|
|
101
114
|
validate_command({
|
|
102
115
|
skill_path,
|
|
103
116
|
strict: parsed.strict === true,
|
|
117
|
+
format: format === 'json' ? 'json' : 'text',
|
|
118
|
+
});
|
|
119
|
+
break;
|
|
120
|
+
}
|
|
121
|
+
case 'doctor': {
|
|
122
|
+
const skill_path = parsed._positional;
|
|
123
|
+
if (!skill_path) {
|
|
124
|
+
console.error('Error: skill path required');
|
|
125
|
+
console.log('\nUsage: claude-skills-cli doctor <skill_path>');
|
|
126
|
+
process.exit(1);
|
|
127
|
+
}
|
|
128
|
+
doctor_command({
|
|
129
|
+
skill_path,
|
|
104
130
|
});
|
|
105
131
|
break;
|
|
106
132
|
}
|
|
@@ -108,7 +134,7 @@ async function main() {
|
|
|
108
134
|
const skill_path = parsed._positional;
|
|
109
135
|
if (!skill_path) {
|
|
110
136
|
console.error('Error: skill path required');
|
|
111
|
-
console.log('\nUsage: claude-skills package <skill_path>');
|
|
137
|
+
console.log('\nUsage: claude-skills-cli package <skill_path>');
|
|
112
138
|
process.exit(1);
|
|
113
139
|
}
|
|
114
140
|
await package_command({
|
package/dist/index.js.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAEA,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AACxD,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AACxD,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAE1D,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;AACnC,MAAM,OAAO,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC;AAExB,SAAS,SAAS;IACjB,OAAO,CAAC,GAAG,CACV,
|
|
1
|
+
{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
|
|
@@ -1,143 +1,59 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: skill-creator
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
principles. Use when building new skills, planning skill
|
|
6
|
-
architecture, or writing skill content.
|
|
3
|
+
# prettier-ignore
|
|
4
|
+
description: Design and create Claude Skills using progressive disclosure principles. Use when building new skills, planning skill architecture, or writing skill content.
|
|
7
5
|
---
|
|
8
6
|
|
|
9
7
|
# Skill Creator
|
|
10
8
|
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
## Quick Start
|
|
14
|
-
|
|
15
|
-
Creating a minimal skill:
|
|
16
|
-
|
|
17
|
-
1. Create directory: `.claude/skills/my-skill/`
|
|
18
|
-
2. Create `SKILL.md` with frontmatter (name, description) and body
|
|
19
|
-
3. Test in conversation
|
|
20
|
-
4. Add references/ as content grows
|
|
9
|
+
Create effective Claude Skills using progressive disclosure.
|
|
21
10
|
|
|
22
11
|
## When to Create a Skill
|
|
23
12
|
|
|
24
13
|
Create a skill when you notice:
|
|
25
14
|
|
|
26
|
-
- **Repeating context** across conversations (
|
|
15
|
+
- **Repeating context** across conversations (schemas, patterns,
|
|
27
16
|
rules)
|
|
28
17
|
- **Domain expertise** needed repeatedly (API integration, framework
|
|
29
18
|
conventions)
|
|
30
|
-
- **Project-specific knowledge**
|
|
31
|
-
|
|
32
|
-
Example: "I keep explaining this database schema" → Create a
|
|
33
|
-
database-schema skill.
|
|
34
|
-
|
|
35
|
-
## Skill Architecture
|
|
19
|
+
- **Project-specific knowledge** Claude should know automatically
|
|
36
20
|
|
|
37
|
-
|
|
21
|
+
## Skill Structure
|
|
38
22
|
|
|
39
23
|
```
|
|
40
24
|
my-skill/
|
|
41
|
-
├── SKILL.md #
|
|
42
|
-
├── references/ #
|
|
43
|
-
├── scripts/ #
|
|
44
|
-
└── assets/ #
|
|
25
|
+
├── SKILL.md # Core instructions + metadata
|
|
26
|
+
├── references/ # Detailed docs (loaded as needed)
|
|
27
|
+
├── scripts/ # Executable operations
|
|
28
|
+
└── assets/ # Templates, images, files
|
|
45
29
|
```
|
|
46
30
|
|
|
47
|
-
**SKILL.md** - Core instructions with YAML frontmatter (name,
|
|
48
|
-
description) + markdown body
|
|
49
|
-
|
|
50
|
-
**references/** - Detailed docs loaded only when Claude needs them
|
|
51
|
-
(schemas, API docs, guides)
|
|
52
|
-
|
|
53
|
-
**scripts/** - Deterministic operations Claude can execute without
|
|
54
|
-
generating code (validation, generation)
|
|
55
|
-
|
|
56
|
-
**assets/** - Files used directly in output without loading into
|
|
57
|
-
context (templates, images)
|
|
58
|
-
|
|
59
31
|
## Progressive Disclosure
|
|
60
32
|
|
|
61
33
|
Skills load in 3 levels:
|
|
62
34
|
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
with core patterns and links
|
|
68
|
-
|
|
69
|
-
**Level 3: Resources** (unlimited, as needed) - references/ scripts/
|
|
70
|
-
assets/ loaded only when used
|
|
71
|
-
|
|
72
|
-
**Key principle**: Keep Levels 1 & 2 lean. Move details to Level 3.
|
|
73
|
-
|
|
74
|
-
## Development Process
|
|
35
|
+
1. **Metadata** (~27 tokens) - YAML frontmatter for triggering
|
|
36
|
+
2. **Instructions** (<680 tokens) - SKILL.md body with core patterns
|
|
37
|
+
3. **Resources** (unlimited) - references/ scripts/ assets/ loaded on
|
|
38
|
+
demand
|
|
75
39
|
|
|
76
|
-
1
|
|
77
|
-
2. **Gather** - Collect 3-5 concrete examples of skill usage
|
|
78
|
-
3. **Plan** - Decide what goes in SKILL.md vs references/ vs scripts/
|
|
79
|
-
4. **Structure** - Create directory with SKILL.md and needed
|
|
80
|
-
subdirectories
|
|
81
|
-
5. **Write** - Craft description, then SKILL.md body following
|
|
82
|
-
patterns
|
|
83
|
-
6. **Enhance** - Add references, scripts, assets as needed
|
|
84
|
-
7. **Iterate** - Test in conversations, refine based on actual usage
|
|
40
|
+
**Key**: Keep Levels 1 & 2 lean. Move details to Level 3.
|
|
85
41
|
|
|
86
|
-
##
|
|
87
|
-
|
|
88
|
-
**Descriptions**: Include "Use when..." triggers, <200 chars optimal.
|
|
89
|
-
Format: [Domain] + [Operations] + [Trigger keywords]
|
|
90
|
-
|
|
91
|
-
**SKILL.md Body**: Target ~50 lines, max ~150. Structure: Quick
|
|
92
|
-
Start + Core Patterns (3-5) + Links. Use imperative voice, concrete
|
|
93
|
-
examples.
|
|
94
|
-
|
|
95
|
-
**References**: Detailed docs with no size limit. Use descriptive
|
|
96
|
-
filenames.
|
|
97
|
-
|
|
98
|
-
## Common Patterns
|
|
99
|
-
|
|
100
|
-
**Succeeds**: Domain expertise, concrete examples, keyword-rich
|
|
101
|
-
descriptions, clear triggers, scripts for deterministic tasks
|
|
102
|
-
|
|
103
|
-
**Fails**: Generic descriptions, bloated SKILL.md, second person
|
|
104
|
-
voice, missing triggers, vague content
|
|
105
|
-
|
|
106
|
-
See [skill-examples.md](references/skill-examples.md) for detailed
|
|
107
|
-
patterns.
|
|
108
|
-
|
|
109
|
-
## Implementation
|
|
110
|
-
|
|
111
|
-
Skills can be created manually (mkdir, touch SKILL.md) or using tools
|
|
112
|
-
like `claude-skills-cli`.
|
|
42
|
+
## Quick Start
|
|
113
43
|
|
|
114
|
-
|
|
44
|
+
1. Create directory: `.claude/skills/my-skill/`
|
|
45
|
+
2. Create `SKILL.md` with frontmatter and body
|
|
46
|
+
3. Test in conversation
|
|
47
|
+
4. Add references/ as content grows
|
|
115
48
|
|
|
116
49
|
## Reference Documentation
|
|
117
50
|
|
|
118
|
-
|
|
119
|
-
|
|
51
|
+
- [writing-guide.md](references/writing-guide.md) - Writing effective
|
|
52
|
+
skills
|
|
53
|
+
- [development-process.md](references/development-process.md) -
|
|
54
|
+
Step-by-step workflow
|
|
55
|
+
- [skill-examples.md](references/skill-examples.md) - Patterns and
|
|
56
|
+
examples
|
|
57
|
+
- [cli-reference.md](references/cli-reference.md) - CLI tool usage
|
|
120
58
|
- [anthropic-resources.md](references/anthropic-resources.md) -
|
|
121
|
-
Official
|
|
122
|
-
- [writing-guide.md](references/writing-guide.md) - Voice, structure,
|
|
123
|
-
and code examples
|
|
124
|
-
- [skill-examples.md](references/skill-examples.md) - Real-world
|
|
125
|
-
patterns and anti-patterns
|
|
126
|
-
- [cli-reference.md](references/cli-reference.md) - Tool commands
|
|
127
|
-
(claude-skills-cli)
|
|
128
|
-
- [cli-feedback.md](references/cli-feedback.md) - Real-world CLI usage
|
|
129
|
-
patterns
|
|
130
|
-
|
|
131
|
-
## Notes
|
|
132
|
-
|
|
133
|
-
- Skills are iterative - start minimal, refine through real usage
|
|
134
|
-
- Description drives discovery - invest time in crafting it
|
|
135
|
-
- Test in actual conversations to validate effectiveness
|
|
136
|
-
- Progressive disclosure is key - resist urge to front-load everything
|
|
137
|
-
|
|
138
|
-
<!--
|
|
139
|
-
PROGRESSIVE DISCLOSURE:
|
|
140
|
-
- This is Level 2 - principles and architecture only
|
|
141
|
-
- Tool-specific details are in references/
|
|
142
|
-
- Target: ~75 lines for optimal scannability
|
|
143
|
-
-->
|
|
59
|
+
Official best practices
|
|
@@ -9,13 +9,13 @@ Complete command-line reference for the `claude-skills-cli` tool
|
|
|
9
9
|
|
|
10
10
|
```bash
|
|
11
11
|
npm install -g claude-skills-cli
|
|
12
|
-
claude-skills --version
|
|
12
|
+
claude-skills-cli --version
|
|
13
13
|
```
|
|
14
14
|
|
|
15
15
|
### Using npx (No Installation)
|
|
16
16
|
|
|
17
17
|
```bash
|
|
18
|
-
npx claude-skills <command>
|
|
18
|
+
npx claude-skills-cli <command>
|
|
19
19
|
```
|
|
20
20
|
|
|
21
21
|
### Using pnpm
|
|
@@ -32,9 +32,9 @@ npm install --save-dev claude-skills-cli
|
|
|
32
32
|
# Use via package.json scripts
|
|
33
33
|
{
|
|
34
34
|
"scripts": {
|
|
35
|
-
"skill:init": "claude-skills init",
|
|
36
|
-
"skill:validate": "claude-skills validate",
|
|
37
|
-
"skill:package": "claude-skills package"
|
|
35
|
+
"skill:init": "claude-skills-cli init",
|
|
36
|
+
"skill:validate": "claude-skills-cli validate",
|
|
37
|
+
"skill:package": "claude-skills-cli package"
|
|
38
38
|
}
|
|
39
39
|
}
|
|
40
40
|
```
|
|
@@ -50,7 +50,7 @@ Create a new skill directory with standard structure.
|
|
|
50
50
|
#### Syntax
|
|
51
51
|
|
|
52
52
|
```bash
|
|
53
|
-
claude-skills init [options]
|
|
53
|
+
claude-skills-cli init [options]
|
|
54
54
|
```
|
|
55
55
|
|
|
56
56
|
#### Options
|
|
@@ -67,17 +67,17 @@ claude-skills init [options]
|
|
|
67
67
|
|
|
68
68
|
```bash
|
|
69
69
|
# Create skill with default location (.claude/skills/)
|
|
70
|
-
npx claude-skills init --name my-skill
|
|
70
|
+
npx claude-skills-cli init --name my-skill
|
|
71
71
|
|
|
72
72
|
# With description
|
|
73
|
-
npx claude-skills init --name my-skill \
|
|
73
|
+
npx claude-skills-cli init --name my-skill \
|
|
74
74
|
--description "SQLite queries. Use when writing database operations"
|
|
75
75
|
|
|
76
76
|
# Custom path
|
|
77
|
-
npx claude-skills init --path /custom/path/my-skill
|
|
77
|
+
npx claude-skills-cli init --path /custom/path/my-skill
|
|
78
78
|
|
|
79
79
|
# Custom path with description
|
|
80
|
-
npx claude-skills init --path /custom/path/my-skill \
|
|
80
|
+
npx claude-skills-cli init --path /custom/path/my-skill \
|
|
81
81
|
--description "Brief description"
|
|
82
82
|
```
|
|
83
83
|
|
|
@@ -109,7 +109,7 @@ Next steps:
|
|
|
109
109
|
3. Add executable scripts to scripts/
|
|
110
110
|
4. Remove example files you don't need
|
|
111
111
|
|
|
112
|
-
Validate with: claude-skills validate .claude/skills/my-skill
|
|
112
|
+
Validate with: claude-skills-cli validate .claude/skills/my-skill
|
|
113
113
|
```
|
|
114
114
|
|
|
115
115
|
---
|
|
@@ -121,7 +121,7 @@ Validate skill structure and progressive disclosure compliance.
|
|
|
121
121
|
#### Syntax
|
|
122
122
|
|
|
123
123
|
```bash
|
|
124
|
-
claude-skills validate <skill_path> [options]
|
|
124
|
+
claude-skills-cli validate <skill_path> [options]
|
|
125
125
|
```
|
|
126
126
|
|
|
127
127
|
#### Arguments
|
|
@@ -140,14 +140,14 @@ claude-skills validate <skill_path> [options]
|
|
|
140
140
|
|
|
141
141
|
```bash
|
|
142
142
|
# Validate skill
|
|
143
|
-
npx claude-skills validate .claude/skills/my-skill
|
|
143
|
+
npx claude-skills-cli validate .claude/skills/my-skill
|
|
144
144
|
|
|
145
145
|
# Strict mode (warnings = errors)
|
|
146
|
-
npx claude-skills validate .claude/skills/my-skill --strict
|
|
146
|
+
npx claude-skills-cli validate .claude/skills/my-skill --strict
|
|
147
147
|
|
|
148
148
|
# Validate multiple skills
|
|
149
|
-
npx claude-skills validate .claude/skills/skill-1
|
|
150
|
-
npx claude-skills validate .claude/skills/skill-2
|
|
149
|
+
npx claude-skills-cli validate .claude/skills/skill-1
|
|
150
|
+
npx claude-skills-cli validate .claude/skills/skill-2
|
|
151
151
|
```
|
|
152
152
|
|
|
153
153
|
#### Validation Checks
|
|
@@ -156,6 +156,8 @@ npx claude-skills validate .claude/skills/skill-2
|
|
|
156
156
|
|
|
157
157
|
- Description length: <200 chars (optimal), <300 chars (warning),
|
|
158
158
|
<1024 chars (max)
|
|
159
|
+
- Description format: Must be on single line (warns if multi-line,
|
|
160
|
+
suggests `doctor` command)
|
|
159
161
|
- Description includes trigger keywords ("Use when...", "Use for...",
|
|
160
162
|
"Use to...")
|
|
161
163
|
- Description comma count (warns if >3, suggesting list bloat)
|
|
@@ -248,6 +250,112 @@ npx claude-skills validate .claude/skills/skill-2
|
|
|
248
250
|
|
|
249
251
|
---
|
|
250
252
|
|
|
253
|
+
### `doctor` - Fix Common Issues
|
|
254
|
+
|
|
255
|
+
Automatically fix common skill issues to ensure compatibility with
|
|
256
|
+
Claude Code.
|
|
257
|
+
|
|
258
|
+
#### Syntax
|
|
259
|
+
|
|
260
|
+
```bash
|
|
261
|
+
claude-skills-cli doctor <skill_path>
|
|
262
|
+
```
|
|
263
|
+
|
|
264
|
+
#### Arguments
|
|
265
|
+
|
|
266
|
+
| Argument | Type | Required | Description |
|
|
267
|
+
| -------------- | ------ | -------- | ----------------------- |
|
|
268
|
+
| `<skill_path>` | string | Yes | Path to skill directory |
|
|
269
|
+
|
|
270
|
+
#### What It Fixes
|
|
271
|
+
|
|
272
|
+
**Multi-line Descriptions:**
|
|
273
|
+
|
|
274
|
+
When formatters like Prettier wrap descriptions across multiple lines,
|
|
275
|
+
Claude Code cannot recognize the skill. The doctor command:
|
|
276
|
+
|
|
277
|
+
1. Detects multi-line descriptions in YAML frontmatter
|
|
278
|
+
2. Adds `# prettier-ignore` comment before the description field
|
|
279
|
+
3. Reflows the description to a single line
|
|
280
|
+
|
|
281
|
+
**Example:**
|
|
282
|
+
|
|
283
|
+
Before:
|
|
284
|
+
|
|
285
|
+
```yaml
|
|
286
|
+
---
|
|
287
|
+
name: my-skill
|
|
288
|
+
description:
|
|
289
|
+
This is a long description that got wrapped by prettier across
|
|
290
|
+
multiple lines
|
|
291
|
+
---
|
|
292
|
+
```
|
|
293
|
+
|
|
294
|
+
After:
|
|
295
|
+
|
|
296
|
+
```yaml
|
|
297
|
+
---
|
|
298
|
+
name: my-skill
|
|
299
|
+
# prettier-ignore
|
|
300
|
+
description: This is a long description that got wrapped by prettier across multiple lines
|
|
301
|
+
---
|
|
302
|
+
```
|
|
303
|
+
|
|
304
|
+
#### Examples
|
|
305
|
+
|
|
306
|
+
```bash
|
|
307
|
+
# Fix multi-line description
|
|
308
|
+
npx claude-skills-cli doctor .claude/skills/my-skill
|
|
309
|
+
|
|
310
|
+
# Common workflow after formatting
|
|
311
|
+
npx prettier --write .claude/skills/my-skill/SKILL.md
|
|
312
|
+
npx claude-skills-cli doctor .claude/skills/my-skill
|
|
313
|
+
npx claude-skills-cli validate .claude/skills/my-skill
|
|
314
|
+
```
|
|
315
|
+
|
|
316
|
+
#### Output
|
|
317
|
+
|
|
318
|
+
**When issues are found:**
|
|
319
|
+
|
|
320
|
+
```
|
|
321
|
+
📋 Running doctor on: my-skill
|
|
322
|
+
============================================================
|
|
323
|
+
📋 Found multi-line description. Fixing...
|
|
324
|
+
✅ Fixed multi-line description!
|
|
325
|
+
|
|
326
|
+
Changes made:
|
|
327
|
+
• Added # prettier-ignore comment before description
|
|
328
|
+
• Reflowed description to single line
|
|
329
|
+
|
|
330
|
+
✓ Run validate command to confirm the fix
|
|
331
|
+
```
|
|
332
|
+
|
|
333
|
+
**When no issues exist:**
|
|
334
|
+
|
|
335
|
+
```
|
|
336
|
+
📋 Running doctor on: my-skill
|
|
337
|
+
============================================================
|
|
338
|
+
✅ No issues found. Description is already on a single line.
|
|
339
|
+
```
|
|
340
|
+
|
|
341
|
+
#### Exit Codes
|
|
342
|
+
|
|
343
|
+
| Code | Meaning |
|
|
344
|
+
| ---- | ---------------------------- |
|
|
345
|
+
| 0 | Success (fixed or no issues) |
|
|
346
|
+
| 1 | Error (file not found, etc.) |
|
|
347
|
+
|
|
348
|
+
#### When to Use
|
|
349
|
+
|
|
350
|
+
Run `doctor` when:
|
|
351
|
+
|
|
352
|
+
- Validation warns about multi-line descriptions
|
|
353
|
+
- After running code formatters (Prettier, dprint, etc.)
|
|
354
|
+
- After manually editing SKILL.md files
|
|
355
|
+
- Before packaging or distributing skills
|
|
356
|
+
|
|
357
|
+
---
|
|
358
|
+
|
|
251
359
|
### `package` - Create Distribution Zip
|
|
252
360
|
|
|
253
361
|
Package skill into a zip file for distribution.
|
|
@@ -255,7 +363,7 @@ Package skill into a zip file for distribution.
|
|
|
255
363
|
#### Syntax
|
|
256
364
|
|
|
257
365
|
```bash
|
|
258
|
-
claude-skills package <skill_path> [options]
|
|
366
|
+
claude-skills-cli package <skill_path> [options]
|
|
259
367
|
```
|
|
260
368
|
|
|
261
369
|
#### Arguments
|
|
@@ -275,13 +383,13 @@ claude-skills package <skill_path> [options]
|
|
|
275
383
|
|
|
276
384
|
```bash
|
|
277
385
|
# Package skill (validates first)
|
|
278
|
-
npx claude-skills package .claude/skills/my-skill
|
|
386
|
+
npx claude-skills-cli package .claude/skills/my-skill
|
|
279
387
|
|
|
280
388
|
# Custom output directory
|
|
281
|
-
npx claude-skills package .claude/skills/my-skill --output builds/
|
|
389
|
+
npx claude-skills-cli package .claude/skills/my-skill --output builds/
|
|
282
390
|
|
|
283
391
|
# Skip validation (not recommended)
|
|
284
|
-
npx claude-skills package .claude/skills/my-skill --skip-validation
|
|
392
|
+
npx claude-skills-cli package .claude/skills/my-skill --skip-validation
|
|
285
393
|
```
|
|
286
394
|
|
|
287
395
|
#### Excluded Files
|
|
@@ -325,7 +433,7 @@ The created zip can be:
|
|
|
325
433
|
|
|
326
434
|
```bash
|
|
327
435
|
# 1. Create skill
|
|
328
|
-
npx claude-skills init --name database-queries \
|
|
436
|
+
npx claude-skills-cli init --name database-queries \
|
|
329
437
|
--description "SQLite queries. Use when writing SELECT, INSERT, UPDATE"
|
|
330
438
|
|
|
331
439
|
# 2. Edit SKILL.md
|
|
@@ -334,14 +442,20 @@ vim .claude/skills/database-queries/SKILL.md
|
|
|
334
442
|
# 3. Add references
|
|
335
443
|
vim .claude/skills/database-queries/references/schema.md
|
|
336
444
|
|
|
337
|
-
# 4.
|
|
338
|
-
npx
|
|
445
|
+
# 4. Format (if using formatter)
|
|
446
|
+
npx prettier --write .claude/skills/database-queries/SKILL.md
|
|
447
|
+
|
|
448
|
+
# 5. Fix any formatting issues
|
|
449
|
+
npx claude-skills-cli doctor .claude/skills/database-queries
|
|
450
|
+
|
|
451
|
+
# 6. Validate
|
|
452
|
+
npx claude-skills-cli validate .claude/skills/database-queries
|
|
339
453
|
|
|
340
|
-
#
|
|
341
|
-
npx claude-skills validate .claude/skills/database-queries
|
|
454
|
+
# 7. Fix any remaining issues, re-validate
|
|
455
|
+
npx claude-skills-cli validate .claude/skills/database-queries
|
|
342
456
|
|
|
343
|
-
#
|
|
344
|
-
npx claude-skills package .claude/skills/database-queries
|
|
457
|
+
# 8. Package
|
|
458
|
+
npx claude-skills-cli package .claude/skills/database-queries
|
|
345
459
|
```
|
|
346
460
|
|
|
347
461
|
### Strict Validation in CI
|
|
@@ -350,7 +464,7 @@ npx claude-skills package .claude/skills/database-queries
|
|
|
350
464
|
# package.json
|
|
351
465
|
{
|
|
352
466
|
"scripts": {
|
|
353
|
-
"test:skills": "claude-skills validate .claude/skills/* --strict"
|
|
467
|
+
"test:skills": "claude-skills-cli validate .claude/skills/* --strict"
|
|
354
468
|
}
|
|
355
469
|
}
|
|
356
470
|
|
|
@@ -364,7 +478,7 @@ npm run test:skills
|
|
|
364
478
|
# Bash script to validate all skills
|
|
365
479
|
for skill in .claude/skills/*/; do
|
|
366
480
|
echo "Validating $skill"
|
|
367
|
-
npx claude-skills validate "$skill" || exit 1
|
|
481
|
+
npx claude-skills-cli validate "$skill" || exit 1
|
|
368
482
|
done
|
|
369
483
|
```
|
|
370
484
|
|
|
@@ -372,8 +486,8 @@ done
|
|
|
372
486
|
|
|
373
487
|
```bash
|
|
374
488
|
# One-liner with validation
|
|
375
|
-
npx claude-skills init --name my-skill --description "Brief desc" && \
|
|
376
|
-
npx claude-skills validate .claude/skills/my-skill
|
|
489
|
+
npx claude-skills-cli init --name my-skill --description "Brief desc" && \
|
|
490
|
+
npx claude-skills-cli validate .claude/skills/my-skill
|
|
377
491
|
```
|
|
378
492
|
|
|
379
493
|
---
|
|
@@ -473,10 +587,10 @@ description: Database helper
|
|
|
473
587
|
```json
|
|
474
588
|
{
|
|
475
589
|
"scripts": {
|
|
476
|
-
"skill:new": "claude-skills init",
|
|
477
|
-
"skill:validate": "claude-skills validate .claude/skills/*",
|
|
478
|
-
"skill:validate:strict": "claude-skills validate .claude/skills/* --strict",
|
|
479
|
-
"skill:package": "claude-skills package",
|
|
590
|
+
"skill:new": "claude-skills-cli init",
|
|
591
|
+
"skill:validate": "claude-skills-cli validate .claude/skills/*",
|
|
592
|
+
"skill:validate:strict": "claude-skills-cli validate .claude/skills/* --strict",
|
|
593
|
+
"skill:package": "claude-skills-cli package",
|
|
480
594
|
"skill:check": "npm run skill:validate:strict"
|
|
481
595
|
},
|
|
482
596
|
"devDependencies": {
|
|
@@ -491,11 +605,11 @@ description: Database helper
|
|
|
491
605
|
|
|
492
606
|
```bash
|
|
493
607
|
# Check CLI version
|
|
494
|
-
npx claude-skills --version
|
|
608
|
+
npx claude-skills-cli --version
|
|
495
609
|
|
|
496
610
|
# Show help
|
|
497
|
-
npx claude-skills --help
|
|
498
|
-
npx claude-skills init --help
|
|
611
|
+
npx claude-skills-cli --help
|
|
612
|
+
npx claude-skills-cli init --help
|
|
499
613
|
```
|
|
500
614
|
|
|
501
615
|
---
|