barebrowse 0.3.1 → 0.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.
- package/CHANGELOG.md +6 -0
- package/README.md +11 -6
- package/docs/skill-template.md +119 -0
- package/package.json +1 -1
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,11 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
+
## 0.3.2
|
|
4
|
+
|
|
5
|
+
- Skill install table in README: per-agent instructions for Claude Code, Cursor, Windsurf, Copilot (project + global scope)
|
|
6
|
+
- Clarified that `npm install barebrowse` is still required — the skill file is documentation only
|
|
7
|
+
- New: `docs/skill-template.md` — generic template for any CLI tool to create a skill file, with frontmatter reference, install locations, and skill-vs-MCP comparison
|
|
8
|
+
|
|
3
9
|
## 0.3.1
|
|
4
10
|
|
|
5
11
|
- Fix `.npmignore`: exclude `.claude/memory/`, `.claude/stash/`, `.claude/settings.local.json` from package (leaked in 0.3.0)
|
package/README.md
CHANGED
|
@@ -41,14 +41,19 @@ barebrowse click 8 # Click element
|
|
|
41
41
|
barebrowse close # End session
|
|
42
42
|
```
|
|
43
43
|
|
|
44
|
-
Outputs go to `.barebrowse/` as files -- agents read them with their file tools, no token waste in tool responses.
|
|
44
|
+
Outputs go to `.barebrowse/` as files -- agents read them with their file tools, no token waste in tool responses.
|
|
45
45
|
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
46
|
+
**Teach your agent the commands** by installing the skill file (a markdown reference the agent reads as context). The CLI tool itself still needs `npm install barebrowse` -- the skill just teaches the agent how to use it.
|
|
47
|
+
|
|
48
|
+
| Agent | Project scope | Global scope |
|
|
49
|
+
|-------|---------------|--------------|
|
|
50
|
+
| **Claude Code** | `.claude/skills/barebrowse/SKILL.md` (auto-detected) | `barebrowse install --skill` |
|
|
51
|
+
| **Cursor** | `.cursor/rules/barebrowse.md` | `~/.cursor/rules/barebrowse.md` |
|
|
52
|
+
| **Windsurf** | `.windsurf/rules/barebrowse.md` | `~/.windsurf/rules/barebrowse.md` |
|
|
53
|
+
| **Copilot** | Append to `.github/copilot-instructions.md` | N/A |
|
|
54
|
+
| **Any agent** | Copy `SKILL.md` to project root or context dir | Varies |
|
|
50
55
|
|
|
51
|
-
|
|
56
|
+
Source file: [.claude/skills/barebrowse/SKILL.md](.claude/skills/barebrowse/SKILL.md). For writing your own skill files: [docs/skill-template.md](docs/skill-template.md).
|
|
52
57
|
|
|
53
58
|
### 2. MCP server -- for Claude Desktop, Cursor, and other MCP clients
|
|
54
59
|
|
|
@@ -0,0 +1,119 @@
|
|
|
1
|
+
# Skill Template — Teaching AI Agents to Use CLI Tools
|
|
2
|
+
|
|
3
|
+
A **skill** is a markdown file that teaches a coding agent (Claude Code, etc.) how to use a CLI tool. No code, no dependencies, no scripts — just a markdown file with YAML frontmatter that the agent reads as context.
|
|
4
|
+
|
|
5
|
+
## What's in a skill file
|
|
6
|
+
|
|
7
|
+
```markdown
|
|
8
|
+
---
|
|
9
|
+
name: your-tool
|
|
10
|
+
description: One-liner explaining what the tool does.
|
|
11
|
+
allowed-tools: Bash(your-tool:*)
|
|
12
|
+
---
|
|
13
|
+
|
|
14
|
+
# your-tool — Brief Title
|
|
15
|
+
|
|
16
|
+
One paragraph: what it does, what it's for.
|
|
17
|
+
|
|
18
|
+
## Quick Start
|
|
19
|
+
|
|
20
|
+
\```bash
|
|
21
|
+
your-tool init # Setup
|
|
22
|
+
your-tool do-thing # Core action
|
|
23
|
+
your-tool status # Check state
|
|
24
|
+
your-tool cleanup # Teardown
|
|
25
|
+
\```
|
|
26
|
+
|
|
27
|
+
## Commands
|
|
28
|
+
|
|
29
|
+
| Command | Description |
|
|
30
|
+
|---------|-------------|
|
|
31
|
+
| `your-tool init` | ... |
|
|
32
|
+
| `your-tool do-thing <arg>` | ... |
|
|
33
|
+
| `your-tool status` | ... |
|
|
34
|
+
| `your-tool cleanup` | ... |
|
|
35
|
+
|
|
36
|
+
## Output Format
|
|
37
|
+
|
|
38
|
+
Describe what the tool outputs and where (stdout, files, etc.)
|
|
39
|
+
Show a real example so the agent knows what to expect.
|
|
40
|
+
|
|
41
|
+
## Workflow Pattern
|
|
42
|
+
|
|
43
|
+
1. Step one
|
|
44
|
+
2. Step two
|
|
45
|
+
3. Repeat as needed
|
|
46
|
+
4. Clean up
|
|
47
|
+
|
|
48
|
+
## Tips
|
|
49
|
+
|
|
50
|
+
- Gotchas, edge cases, best practices
|
|
51
|
+
- Things the agent should always/never do
|
|
52
|
+
```
|
|
53
|
+
|
|
54
|
+
## Frontmatter fields
|
|
55
|
+
|
|
56
|
+
| Field | Required | What it does |
|
|
57
|
+
|-------|----------|--------------|
|
|
58
|
+
| `name` | Yes | Tool identifier. Shown in Claude's skill list. |
|
|
59
|
+
| `description` | Yes | One-liner. Shown when Claude lists available skills. |
|
|
60
|
+
| `allowed-tools` | Yes | Auto-grants Bash permission. `Bash(your-tool:*)` means any command starting with `your-tool`. |
|
|
61
|
+
|
|
62
|
+
## How to install
|
|
63
|
+
|
|
64
|
+
The skill file is just a `.md` file placed where the agent can find it:
|
|
65
|
+
|
|
66
|
+
### Claude Code
|
|
67
|
+
|
|
68
|
+
| Scope | Location | How |
|
|
69
|
+
|-------|----------|-----|
|
|
70
|
+
| **This project only** | `.claude/skills/your-tool/SKILL.md` | Copy file into project |
|
|
71
|
+
| **All projects (global)** | `~/.config/claude/skills/your-tool/SKILL.md` | Copy file to home config |
|
|
72
|
+
|
|
73
|
+
### Other coding agents (Cursor, Windsurf, Copilot, etc.)
|
|
74
|
+
|
|
75
|
+
| Agent | Project scope | Global scope |
|
|
76
|
+
|-------|---------------|--------------|
|
|
77
|
+
| **Cursor** | `.cursor/rules/your-tool.md` | `~/.cursor/rules/your-tool.md` |
|
|
78
|
+
| **Windsurf** | `.windsurf/rules/your-tool.md` | `~/.windsurf/rules/your-tool.md` |
|
|
79
|
+
| **GitHub Copilot** | `.github/copilot-instructions.md` (append) | N/A |
|
|
80
|
+
| **Generic** | Drop in project root as `your-tool.context.md` | Varies by agent |
|
|
81
|
+
|
|
82
|
+
> **Note:** Non-Claude agents ignore the YAML frontmatter — they just read it as markdown context. The `allowed-tools` field is Claude Code specific.
|
|
83
|
+
|
|
84
|
+
## What the skill does NOT do
|
|
85
|
+
|
|
86
|
+
- Does not install the CLI tool — `npm install` (or equivalent) is still required
|
|
87
|
+
- Does not run any code — it's pure documentation
|
|
88
|
+
- Does not replace MCP — it's an alternative integration path (see below)
|
|
89
|
+
|
|
90
|
+
## Skill vs MCP
|
|
91
|
+
|
|
92
|
+
| | Skill (CLI) | MCP Server |
|
|
93
|
+
|---|---|---|
|
|
94
|
+
| **What it is** | Markdown file teaching the agent CLI commands | Long-running JSON-RPC process |
|
|
95
|
+
| **How agent calls it** | `bash` tool with shell commands | Native tool calls via MCP protocol |
|
|
96
|
+
| **State** | Tool manages its own state (daemon, files, etc.) | MCP server holds state in memory |
|
|
97
|
+
| **Install** | Copy a `.md` file | Register server in config JSON |
|
|
98
|
+
| **Deps at runtime** | CLI tool must be installed (`npm install`) | CLI tool must be installed (`npx` or global) |
|
|
99
|
+
| **Works with** | Claude Code (+ any agent that reads project docs) | Any MCP client (Claude Desktop, Cursor, VS Code, etc.) |
|
|
100
|
+
| **Pros** | Simple, debuggable, no process management | Structured schemas, wide MCP client support |
|
|
101
|
+
| **Cons** | Agent needs Bash access, less structured | Extra process, protocol overhead |
|
|
102
|
+
|
|
103
|
+
Both require the underlying tool to be installed. Choose based on your agent's capabilities.
|
|
104
|
+
|
|
105
|
+
## Example: barebrowse
|
|
106
|
+
|
|
107
|
+
barebrowse ships its skill at `.claude/skills/barebrowse/SKILL.md`. Install options:
|
|
108
|
+
|
|
109
|
+
```bash
|
|
110
|
+
# Project-local (Claude Code picks it up automatically)
|
|
111
|
+
cp node_modules/barebrowse/.claude/skills/barebrowse/SKILL.md .claude/skills/barebrowse/SKILL.md
|
|
112
|
+
|
|
113
|
+
# Global (all projects)
|
|
114
|
+
barebrowse install --skill
|
|
115
|
+
# copies to ~/.config/claude/skills/barebrowse/SKILL.md
|
|
116
|
+
|
|
117
|
+
# For Cursor
|
|
118
|
+
cp node_modules/barebrowse/.claude/skills/barebrowse/SKILL.md .cursor/rules/barebrowse.md
|
|
119
|
+
```
|