skill-creator

Files (1)

• SKILL.md

SKILL.md (first lines)

# Skill Creator

A skill for creating new macher-agent skills and iteratively improving them. 

At a high level, the process of creating a macher-agent skill is:
- Decide what you want the skill to do and what specific Emacs Lisp tools it will need.
- Draft the Emacs Lisp tools (placed in `skills/scripts/`) using `macher-agent-make-tool` (for filesystem/shell access) or `gptel-make-tool` (for pure Emacs logic).
- Write a draft of the skill in `skills/<skill-name>/SKILL.md`.
- Test the skill by spawning sub-agents (`spawn_subagent`) that use the new skill to perform tasks in a scratch workspace or on test files.
- Evaluate the sub-agent's performance based on the task output.
- Refactor the SKILL.md instructions or Emacs Lisp tools based on the results.
- Repeat until satisfied.

Your job is to guide the user through this process. Whether they have a faint idea or a strict specification, you help them narrow down the requirements, draft the tool code, and iterate on the system prompt.

## Communicating with the User

Pay attention to context cues. Some users are Emacs Lisp experts; others might be entirely new to the Emacs ecosystem. Adjust your language and explain `gptel` tool semantics or Emacs buffer mechanics if the user seems unsure.

## Anatomy of a macher-agent Skill

Macher-agent skills are fundamentally different from Claude skills. 

1. **No bundled scripts directory:** Instead of Python scripts bundled inside a skill folder, macher-agent shares executable tools across the workspace. Custom tools must be written as Emacs Lisp scripts in the `skills/scripts/` directory.
2. **Explicit Allowed Tools:** The skill frontmatter MUST contain an `allowed-tools` list.
3. **Model Selection:** Unlike Claude skills, a macher-agent SKILL.md **can** enforce a specific model. You can specify it in the frontmatter (e.g., `model: claude-3-5-sonnet-20241022`). If omitted, it inherits from the user's environment.
4. **Composable Presets:** A skill acts as a modular system prompt. Thanks to the native composition engine, sub-agents can be given multiple skills at once via a JSON array (for example `presets: ["rust-developer", "workspace-manager"]`), which seamlessly merges their allowed tools and system instructions into a unified context.

### Structure

```
skills/
├── <skill-name>/
│   └── SKILL.md (required)
└── scripts/
    └── custom_tool.el (optional, if custom capabilities are needed)
```

### The SKILL.md Frontmatter

```yaml
---
name: "my-custom-skill"
description: "A short, descriptive prompt of when and why to use this skill."
model: "claude-3-5-sonnet-20241022" # Optional
allowed-tools:
  - read_file_in_workspace
  - write_buffer_in_workspace
  - custom_tool
---
```

## Creating a Tool

When you draft Emacs Lisp tools in `skills/scripts/`, choose the right macro based on what the tool does:

### File System Access (`macher-agent-make-tool`)
If your tool needs to run shell commands against the file system, ALWAYS use `macher-agent-make-tool`. This ensures the agent's pending virtual edits are synced to a temporary sandbox before the shell command runs.

It accepts `:command-fn` (returns the shell string), `:success-fn`, and `:output-filter` to parse output.

**Example:**
```elisp
(macher-agent-make-tool macher-agent-cargo-check-tool
  "Run 'cargo check' to compile the project."
  :category "rust"
  :args nil
  :command-fn (lambda (_payload)
                (make-macher-agent-process-response
                 :payload "rtk cargo test </dev/null 2>&1"))
  :success-fn (lambda (output)
                (concat "SUCCESS: The code compiled perfectly with no errors.\n\n=== COMPILER OUTPUT ===\n" output)))
```

### Pure Emacs Operations
If the tool interacts entirely with Emacs buffers, text, or internal logic, use the standard this concise version.

**Example:**
```elisp
(macher-agent-make-tool macher-agent-get-current-datetime-tool
  "Fetch the current system date and time. Use this when you need to know the current date, time, or day of the week to answer a time-sensitive query."
  :category "system"
  :args nil
  :command-fn (lambda (_payload)
                (make-macher-agent-lisp-result-response
                 :payload (format-time-string "%A, %d %B %Y, %T %Z"))))
```

## Creating a Skill

### Capture Intent & Interview
Start by extracting the user's intent. What should the sub-agent do? What input does it take? Does it need to edit Emacs buffers, invoke external CLI commands, or perform abstract planning?
If the user's request requires capabilities not covered by the default workspace tools (like interacting with a specific Emacs mode, or parsing a complex log format), identify the need for a custom ELisp tool.

### Write the Tools
Draft any necessary ELisp scripts in `skills/scripts/`. Follow the established format using `macher-agent-make-tool`. Keep tool logic small, robust, and explicitly documented.

### Write the SKILL.md
Draft the markdown body.
- Define the persona or role (e.g., "You are a code reviewer...").
- Detail the exact workflow steps the agent should take.
- Mention the tools by name and explain *when* and *how* to use them.
- Provide examples of good and bad tool usage or output formatting.

## Testing and Iteration

Unlike standard Claude skills, macher-agent runs natively in Emacs. 
To evaluate a skill:
1. Setup a test directory or file in the workspace.
2. Use your orchestration tools (e.g., `spawn_subagent`, `execute_subagents`) to launch an agent using the newly created skill name. Give it a specific prompt.
3. Observe the output buffer or the file changes produced by the sub-agent.
4. Analyse whether the agent got confused by its tools, failed to invoke them, or provided an incorrect result.
5. Edit the `SKILL.md` to refine the instructions or fix bugs in the ELisp tool. Try to explain *why* something is important to the model rather than relying on heavy-handed "MUST ALWAYS" commands. Keep the system prompt lean.

Keep iterating until the output consistently matches the user's expectations.

From elij/macher-agent-skills, GPL-3.0.

More from elij/macher-agent-skills