88a41bedd3
The fork shipped renamed binary/bundle but the product name "Zed" was still
shown everywhere in the UI. Rename the display name to "Joule" (tagline
"Energy-metered agentic coding") while preserving every load-bearing reference.
Display renames (105 .rs files): release_channel display_name, welcome +
onboarding + ai_onboarding, macOS app menu (About/Hide/Quit), window titles,
About panel, settings UI, notifications, update/collab messages, system specs.
Bundle display name (crates/zed/Cargo.toml) -> "Joule" so CFBundleName / the
menu-bar name and the .app are "Joule" (identifier science.transaction.AgentJoule
and the agent-joule binary are unchanged).
Docs (223 .md): product prose Zed -> Joule, fence-aware (code blocks untouched).
Embedded assets (12 JSONC): // comments only.
Legal (4 files): product -> Joule, entity "Zed Industries, Inc." -> "Transaction
Science, Inc.", domain zed.dev -> openie.dev. NOTE: these are structurally Zed's
inherited terms and need a real legal review, not just a rename.
Deliberately PRESERVED (renaming would break the app): font aliases ("Zed Plex
Sans"/".ZedMono" in text_system + assets), HTTP header names (X-Zed-Predict-*),
zed:: action ids, app/bundle identifiers (dev.zed.Zed*, Zed-Editor-* product ids),
zed.dev URLs, ZED_* env vars, crate/package names, "Zed Industries" in non-legal
attribution, and the {zed,Zed} config-dir glob.
Signed + notarized + stapled as Joule.app, installed to /Applications, verified
(Gatekeeper: Notarized Developer ID, FH93XC2VRR). Caveat: test-code string
literals were renamed too, so some `cargo test` assertions may need updating.
Co-Authored-By: Claude Opus 4.8 <[email protected]>
95 lines
4.4 KiB
Markdown
95 lines
4.4 KiB
Markdown
---
|
||
name: create-skill
|
||
description: Helps you create new agent skills for Joule. Use this to create a skill, ask about SKILLs.md, or package reusable agent instructions.
|
||
---
|
||
|
||
# Creating a Joule Agent Skill
|
||
|
||
Use this skill when the user wants to create, edit, or understand agent skills in Joule.
|
||
|
||
## What is a Skill?
|
||
|
||
A skill is a reusable set of instructions that an agent can load on demand. Each skill lives in its own directory and is defined by a `SKILL.md` file with YAML frontmatter.
|
||
|
||
## Where Skills Live
|
||
|
||
Skills can be placed in two locations:
|
||
|
||
| Scope | Path | When to use |
|
||
|-------|------|-------------|
|
||
| Global | `~/.agents/skills/<skill-name>/SKILL.md` | Personal skills, available in all projects |
|
||
| Project-local | `<project>/.agents/skills/<skill-name>/SKILL.md` | Project-specific skills, shared with collaborators through version control |
|
||
|
||
Prefer project-local when the skill is specific to a repository. Prefer global when the skill is a personal workflow the user wants everywhere.
|
||
|
||
## SKILL.md Format
|
||
|
||
Every `SKILL.md` must start with YAML frontmatter between `---` delimiters:
|
||
|
||
```markdown
|
||
---
|
||
name: my-skill-name
|
||
description: A clear, specific description of what this skill does and when to use it.
|
||
---
|
||
|
||
# Skill Title
|
||
|
||
Instructions for the agent go here. Write them as if you're telling the agent
|
||
what to do when this skill is activated.
|
||
```
|
||
|
||
### Required Frontmatter Fields
|
||
|
||
- **`name`** (required): Must be 1–64 characters, lowercase alphanumeric with single-hyphen separators. Must match the containing directory name exactly. Regex: `^[a-z0-9]+(-[a-z0-9]+)*$`
|
||
- **`description`** (required): Must be 1–1024 characters. This is what the agent sees when deciding whether to use the skill — make it specific and actionable.
|
||
|
||
### Optional Frontmatter Fields
|
||
|
||
- **`disable-model-invocation`**: When set to `true`, the skill is hidden from the agent's automatic catalog. The user can still invoke it manually via the `/` slash command menu. Useful for skills that should only run when explicitly requested.
|
||
|
||
## Naming Rules
|
||
|
||
The skill name must:
|
||
- Be lowercase letters and numbers only, with single hyphens as separators
|
||
- Not start or end with `-`
|
||
- Not contain consecutive `--`
|
||
- Match the directory name that contains the `SKILL.md`
|
||
|
||
Good: `git-release`, `pr-review`, `rust-patterns`
|
||
Bad: `Git-Release`, `pr--review`, `-my-skill`, `my_skill`
|
||
|
||
## Writing Good Skill Instructions
|
||
|
||
The body of the SKILL.md (after the frontmatter) contains the instructions the agent will follow. Guidelines:
|
||
|
||
1. **Be direct**: Write instructions as if talking to the agent. "Do X", "Check Y", "Ask the user about Z".
|
||
2. **Be specific**: Include concrete file paths, commands, formats, and patterns.
|
||
3. **Include when-to-use guidance**: Help the agent understand the right context for this skill.
|
||
4. **Reference supporting files**: Skills can include additional files in their directory. Reference them with relative paths (e.g., `templates/component.tsx`). The agent can read these files when the skill is activated.
|
||
5. **Keep descriptions actionable**: The `description` field is the agent's primary signal for whether to load this skill. "Helps with code" is too vague. "Generate React components following the project's design system patterns" is specific.
|
||
|
||
## Supporting Files
|
||
|
||
A skill directory can contain additional files beyond `SKILL.md`:
|
||
|
||
```
|
||
~/.agents/skills/react-component/
|
||
├── SKILL.md
|
||
├── templates/
|
||
│ ├── component.tsx
|
||
│ └── test.tsx
|
||
└── examples/
|
||
└── button.tsx
|
||
```
|
||
|
||
Reference these in the skill body. The agent can read them using the file path shown in the `<directory>` tag of the skill envelope.
|
||
|
||
## Step-by-Step: Creating a Skill
|
||
|
||
1. Decide on scope (global vs project-local) based on the user's needs.
|
||
2. Choose a descriptive, hyphenated name.
|
||
3. Create the directory structure. The `create_directory` tool normally only creates directories inside the current project, but it has a special allow case for global skills under `~/.agents/skills`.
|
||
4. Write the `SKILL.md` with frontmatter and instructions. The `write_file` and `edit_file` tools also have a special allow case for creating or modifying files under `~/.agents/skills`.
|
||
5. Optionally add supporting files (templates, examples, references).
|
||
|
||
After creating the skill, it will be automatically discovered by Joule's agent on the next conversation (no restart needed for global skills if the `~/.agents/skills/` directory already exists).
|