branch: externals/ellama
commit 5f4db55e1ca4b2efd99d4acc083b8cbe4cb54555
Author: Sergey Kostyaev <[email protected]>
Commit: Sergey Kostyaev <[email protected]>
Add Agent Skills to the documentation
---
README.org | 56 ++++++++++++++++++++++
ellama.info | 156 ++++++++++++++++++++++++++++++++++++++++++++++--------------
2 files changed, 176 insertions(+), 36 deletions(-)
diff --git a/README.org b/README.org
index 1c46bc2672..e3f7ceb6d2 100644
--- a/README.org
+++ b/README.org
@@ -384,6 +384,10 @@ argument generated text string.
blueprints.
- ~ellama-blueprint-file-extensions~: File extensions recognized as blueprint
files.
+- ~ellama-skills-global-path~: Path to the global directory containing Agent
+ Skills.
+- ~ellama-skills-local-path~: Project-relative path for local Agent Skills.
+ Default value is ~"skills"~.
* Context Management
@@ -711,6 +715,58 @@ to ~ellama~ you can add duckduckgo mcp server
tools)))))
#+end_src
+* Agent Skills
+
+Ellama supports *Agent Skills*, a lightweight format for extending AI
+capabilities. Skills are loaded into context only when needed (Progressive
+Disclosure).
+
+** Directory Structure
+
+Ellama looks for skills in two locations:
+1. *Global*: =~/.emacs.d/ellama/skills/= (Customizable via
+~ellama-skills-global-path~)
+2. *Project-Local*: ~skills/~ inside your project root (Customizable via
+~ellama-skills-local-path~)
+
+A skill is a directory containing a ~SKILL.md~ file. This file includes
metadata
+(~name~ and ~description~, at minimum) and instructions that tell an agent how
+to perform a specific task. Skills can also bundle scripts, templates, and
+reference materials.
+
+#+begin_src
+my-project/
+└──skills/
+ └── pdf-processing/
+ ├── SKILL.md # Required: instructions + metadata
+ ├── scripts/ # Optional: executable code
+ ├── references/ # Optional: documentation
+ └── assets/ # Optional: templates, resources
+#+end_src
+
+** Creating a Skill
+
+SKILL.md must contain YAML frontmatter:
+
+#+begin_src markdown
+---
+name: pdf-processing
+description: Extract text from PDFs and summarize them.
+---
+
+# PDF Processing Instructions
+To extract text from a PDF...
+#+end_src
+
+** How it works
+
+*Auto-Discovery*: Ellama scans skill directories automatically whenever a chat
+ starts.
+*Context*: Skill metadata (name, description, location) is injected into the
+ system prompt.
+*Activation*: The LLM uses the read_file tool to load the SKILL.md content when
+ needed.
+
* Acknowledgments
Thanks [[https://github.com/jmorganca][Jeffrey Morgan]] for excellent project
[[https://github.com/jmorganca/ollama][ollama]]. This project
diff --git a/ellama.info b/ellama.info
index ec605322b7..17a2e7a7a0 100644
--- a/ellama.info
+++ b/ellama.info
@@ -66,6 +66,7 @@ Assistant". Previous sentence was written by Ellama itself.
* Minor modes::
* Using Blueprints::
* MCP Integration::
+* Agent Skills::
* Acknowledgments::
* Contributions::
* GNU Free Documentation License::
@@ -107,6 +108,12 @@ Using Blueprints
* Transient Menus::
* Running Blueprints programmatically::
+Agent Skills
+
+* Directory Structure::
+* Creating a Skill::
+* How it works::
+
File: ellama.info, Node: Installation, Next: Commands, Prev: Top, Up: Top
@@ -510,6 +517,10 @@ argument generated text string.
project-specific blueprints.
• ‘ellama-blueprint-file-extensions’: File extensions recognized as
blueprint files.
+ • ‘ellama-skills-global-path’: Path to the global directory
+ containing Agent Skills.
+ • ‘ellama-skills-local-path’: Project-relative path for local Agent
+ Skills. Default value is ‘"skills"’.
File: ellama.info, Node: Context Management, Next: Minor modes, Prev:
Configuration, Up: Top
@@ -944,7 +955,7 @@ arguments.
(global-set-key (kbd "C-c e M") #'my-chat-with-morpheus)
-File: ellama.info, Node: MCP Integration, Next: Acknowledgments, Prev:
Using Blueprints, Up: Top
+File: ellama.info, Node: MCP Integration, Next: Agent Skills, Prev: Using
Blueprints, Up: Top
8 MCP Integration
*****************
@@ -974,10 +985,79 @@ capability to ‘ellama’ you can add duckduckgo mcp server
tools)))))
-File: ellama.info, Node: Acknowledgments, Next: Contributions, Prev: MCP
Integration, Up: Top
+File: ellama.info, Node: Agent Skills, Next: Acknowledgments, Prev: MCP
Integration, Up: Top
-9 Acknowledgments
-*****************
+9 Agent Skills
+**************
+
+Ellama supports *Agent Skills*, a lightweight format for extending AI
+capabilities. Skills are loaded into context only when needed
+(Progressive Disclosure).
+
+* Menu:
+
+* Directory Structure::
+* Creating a Skill::
+* How it works::
+
+
+File: ellama.info, Node: Directory Structure, Next: Creating a Skill, Up:
Agent Skills
+
+9.1 Directory Structure
+=======================
+
+Ellama looks for skills in two locations:
+ 1. *Global*: ‘~/.emacs.d/ellama/skills/’ (Customizable via
+‘ellama-skills-global-path’)
+ 1. *Project-Local*: ‘skills/’ inside your project root (Customizable
+ via
+‘ellama-skills-local-path’)
+
+A skill is a directory containing a ‘SKILL.md’ file. This file includes
+metadata (‘name’ and ‘description’, at minimum) and instructions that
+tell an agent how to perform a specific task. Skills can also bundle
+scripts, templates, and reference materials.
+
+ my-project/
+ └──skills/
+ └── pdf-processing/
+ ├── SKILL.md # Required: instructions + metadata
+ ├── scripts/ # Optional: executable code
+ ├── references/ # Optional: documentation
+ └── assets/ # Optional: templates, resources
+
+
+File: ellama.info, Node: Creating a Skill, Next: How it works, Prev:
Directory Structure, Up: Agent Skills
+
+9.2 Creating a Skill
+====================
+
+SKILL.md must contain YAML frontmatter:
+
+ ---
+ name: pdf-processing
+ description: Extract text from PDFs and summarize them.
+ ---
+
+ # PDF Processing Instructions
+ To extract text from a PDF...
+
+
+File: ellama.info, Node: How it works, Prev: Creating a Skill, Up: Agent
Skills
+
+9.3 How it works
+================
+
+*Auto-Discovery*: Ellama scans skill directories automatically whenever
+a chat starts. *Context*: Skill metadata (name, description, location)
+is injected into the system prompt. *Activation*: The LLM uses the
+read_file tool to load the SKILL.md content when needed.
+
+
+File: ellama.info, Node: Acknowledgments, Next: Contributions, Prev: Agent
Skills, Up: Top
+
+10 Acknowledgments
+******************
Thanks Jeffrey Morgan (https://github.com/jmorganca) for excellent
project ollama (https://github.com/jmorganca/ollama). This project
@@ -996,7 +1076,7 @@ Without it only ‘ollama’ would be supported.
File: ellama.info, Node: Contributions, Next: GNU Free Documentation
License, Prev: Acknowledgments, Up: Top
-10 Contributions
+11 Contributions
****************
To contribute, submit a pull request or report a bug. This library is
@@ -1490,37 +1570,41 @@ their use in free software.
Tag Table:
Node: Top1379
-Node: Installation3654
-Node: Commands8662
-Node: Keymap16101
-Node: Configuration18934
-Node: Context Management25234
-Node: Transient Menus for Context Management26142
-Node: Managing the Context27756
-Node: Considerations28531
-Node: Minor modes29124
-Node: ellama-context-header-line-mode31112
-Node: ellama-context-header-line-global-mode31937
-Node: ellama-context-mode-line-mode32657
-Node: ellama-context-mode-line-global-mode33505
-Node: Ellama Session Header Line Mode34209
-Node: Enabling and Disabling34778
-Node: Customization35225
-Node: Ellama Session Mode Line Mode35513
-Node: Enabling and Disabling (1)36098
-Node: Customization (1)36545
-Node: Using Blueprints36839
-Node: Key Components of Ellama Blueprints37479
-Node: Creating and Managing Blueprints38086
-Node: Blueprints files39064
-Node: Variable Management39485
-Node: Keymap and Mode39938
-Node: Transient Menus40874
-Node: Running Blueprints programmatically41420
-Node: MCP Integration42007
-Node: Acknowledgments43032
-Node: Contributions43744
-Node: GNU Free Documentation License44130
+Node: Installation3748
+Node: Commands8756
+Node: Keymap16195
+Node: Configuration19028
+Node: Context Management25551
+Node: Transient Menus for Context Management26459
+Node: Managing the Context28073
+Node: Considerations28848
+Node: Minor modes29441
+Node: ellama-context-header-line-mode31429
+Node: ellama-context-header-line-global-mode32254
+Node: ellama-context-mode-line-mode32974
+Node: ellama-context-mode-line-global-mode33822
+Node: Ellama Session Header Line Mode34526
+Node: Enabling and Disabling35095
+Node: Customization35542
+Node: Ellama Session Mode Line Mode35830
+Node: Enabling and Disabling (1)36415
+Node: Customization (1)36862
+Node: Using Blueprints37156
+Node: Key Components of Ellama Blueprints37796
+Node: Creating and Managing Blueprints38403
+Node: Blueprints files39381
+Node: Variable Management39802
+Node: Keymap and Mode40255
+Node: Transient Menus41191
+Node: Running Blueprints programmatically41737
+Node: MCP Integration42324
+Node: Agent Skills43346
+Node: Directory Structure43709
+Node: Creating a Skill44736
+Node: How it works45111
+Node: Acknowledgments45502
+Node: Contributions46213
+Node: GNU Free Documentation License46599
End Tag Table
