@andysama/openskills 1.3.2

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.
Files changed (6) hide show
  1. package/LICENSE +17 -0
  2. package/README.md +535 -0
  3. package/dist/cli.js +732 -0
  4. package/examples/my-first-skill/SKILL.md +61 -0
  5. package/examples/my-first-skill/references/skill-format.md +77 -0
  6. package/package.json +60 -0
package/examples/my-first-skill/SKILL.md ADDED
@@ -0,0 +1,61 @@
1
+ ---
2
+ name: my-first-skill
3
+ description: Example skill demonstrating Anthropic SKILL.md format. Load when learning to create skills or testing the OpenSkills loader.
4
+ ---
5
+
6
+ # My First Skill
7
+
8
+ This is an example skill demonstrating the Anthropic SKILL.md format.
9
+
10
+ ## Purpose
11
+
12
+ This skill shows how to structure procedural guidance for AI coding agents using progressive disclosure.
13
+
14
+ ## When to Use
15
+
16
+ Load this skill when:
17
+ - Learning how skills work
18
+ - Testing the OpenSkills loader
19
+ - Understanding the SKILL.md format
20
+
21
+ ## Instructions
22
+
23
+ To create a skill:
24
+
25
+ 1. Create a directory: `mkdir my-skill/`
26
+ 2. Add SKILL.md with YAML frontmatter:
27
+ ```yaml
28
+ ---
29
+ name: my-skill
30
+ description: When to use this skill
31
+ ---
32
+ ```
33
+ 3. Write instructions in imperative form (not second person)
34
+ 4. Reference bundled resources as needed
35
+
36
+ ## Bundled Resources
37
+
38
+ For detailed information about the SKILL.md specification:
39
+
40
+ See `references/skill-format.md`
41
+
42
+ ## Best Practices
43
+
44
+ - Write in imperative/infinitive form: "To do X, execute Y"
45
+ - NOT second person: avoid "You should..."
46
+ - Keep SKILL.md under 5,000 words
47
+ - Move detailed content to references/
48
+ - Use scripts/ for executable code
49
+ - Use assets/ for templates and output files
50
+
51
+ ## Resource Resolution
52
+
53
+ When this skill is loaded, the base directory is provided:
54
+
55
+ ```
56
+ Base directory: /path/to/my-first-skill
57
+ ```
58
+
59
+ Relative paths resolve from base directory:
60
+ - `references/skill-format.md` → `/path/to/my-first-skill/references/skill-format.md`
61
+ - `scripts/helper.sh` → `/path/to/my-first-skill/scripts/helper.sh`
package/examples/my-first-skill/references/skill-format.md ADDED
@@ -0,0 +1,77 @@
1
+ # SKILL.md Format Reference
2
+
3
+ ## YAML Frontmatter (Required)
4
+
5
+ Every SKILL.md must start with YAML frontmatter:
6
+
7
+ ```yaml
8
+ ---
9
+ name: skill-name # Required: hyphen-case identifier
10
+ description: When to use # Required: 1-2 sentences, third-person
11
+ ---
12
+ ```
13
+
14
+ ## Markdown Body (Required)
15
+
16
+ After frontmatter, write instructions in **imperative/infinitive form**:
17
+
18
+ **Good:**
19
+ - "To accomplish X, execute Y"
20
+ - "Load this skill when Z"
21
+ - "See references/guide.md for details"
22
+
23
+ **Avoid:**
24
+ - "You should do X"
25
+ - "If you need Y"
26
+ - "When you want Z"
27
+
28
+ ## Progressive Disclosure
29
+
30
+ Skills load in three levels:
31
+
32
+ 1. **Metadata** (always in context): name + description
33
+ 2. **SKILL.md** (loaded when relevant): core instructions
34
+ 3. **Resources** (loaded as needed): detailed documentation
35
+
36
+ ## Bundled Resources (Optional)
37
+
38
+ ### references/
39
+
40
+ Documentation loaded into context as needed:
41
+ - API documentation
42
+ - Database schemas
43
+ - Detailed guides
44
+
45
+ ### scripts/
46
+
47
+ Executable code (Python/Bash/etc.):
48
+ - Can be run without loading to context
49
+ - Use for deterministic, repeatable tasks
50
+
51
+ ### assets/
52
+
53
+ Files used in output (not loaded to context):
54
+ - Templates
55
+ - Images
56
+ - Boilerplate code
57
+
58
+ ## File Size Guidelines
59
+
60
+ - **SKILL.md**: Under 5,000 words
61
+ - **references/**: Unlimited (loaded selectively)
62
+ - **scripts/**: Executable, not counted
63
+ - **assets/**: Not loaded to context
64
+
65
+ ## Example Structure
66
+
67
+ ```
68
+ pdf-editor/
69
+ ├── SKILL.md (~2,000 words)
70
+ ├── references/
71
+ │ └── pdf-api.md (detailed API docs)
72
+ ├── scripts/
73
+ │ ├── rotate.py (executable)
74
+ │ └── merge.py
75
+ └── assets/
76
+ └── template.pdf (boilerplate)
77
+ ```
package/package.json ADDED
@@ -0,0 +1,60 @@
1
+ {
2
+ "name": "@andysama/openskills",
3
+ "version": "1.3.2",
4
+ "description": "Universal skills loader for AI coding agents - install and load Anthropic SKILL.md format skills in any agent",
5
+ "type": "module",
6
+ "main": "./dist/cli.js",
7
+ "bin": {
8
+ "openskills": "./dist/cli.js"
9
+ },
10
+ "files": [
11
+ "dist",
12
+ "examples"
13
+ ],
14
+ "scripts": {
15
+ "build": "tsup",
16
+ "dev": "tsup --watch",
17
+ "test": "vitest run",
18
+ "test:watch": "vitest",
19
+ "test:coverage": "vitest run --coverage",
20
+ "typecheck": "tsc --noEmit",
21
+ "prepublishOnly": "npm run typecheck && npm run build && npm test"
22
+ },
23
+ "keywords": [
24
+ "anthropic",
25
+ "claude",
26
+ "claude-code",
27
+ "skills",
28
+ "ai",
29
+ "agents",
30
+ "coding-agent",
31
+ "cursor",
32
+ "windsurf",
33
+ "aider",
34
+ "progressive-disclosure",
35
+ "automation",
36
+ "developer-tools"
37
+ ],
38
+ "author": "OpenSkills Contributors",
39
+ "license": "Apache-2.0",
40
+ "repository": {
41
+ "type": "git",
42
+ "url": "https://github.com/andysama-work/openskills.git"
43
+ },
44
+ "homepage": "https://github.com/andysama-work/openskills#readme",
45
+ "engines": {
46
+ "node": ">=20.6.0"
47
+ },
48
+ "dependencies": {
49
+ "@inquirer/prompts": "^7.9.0",
50
+ "chalk": "^5.6.2",
51
+ "commander": "^12.1.0",
52
+ "ora": "^9.0.0"
53
+ },
54
+ "devDependencies": {
55
+ "@types/node": "^24.9.1",
56
+ "tsup": "^8.5.0",
57
+ "typescript": "^5.9.3",
58
+ "vitest": "^4.0.3"
59
+ }
60
+ }