Skip to content

Commit aec7a7a

Browse files
jfarcandjfarcand
committed
docs: rewrite skills page with correct Markdown format, sections, and cross-referencing
1 parent 8219bba commit aec7a7a

1 file changed

Lines changed: 122 additions & 55 deletions

File tree

‎docs/src/content/docs/agents/skills.md‎

Lines changed: 122 additions & 55 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
---
22
title: "Skills"
3-
description: "Skill files, auto-discovery, GitHub import, and the Agent Skills standard"
3+
description: "Skill files, sections, auto-discovery, GitHub import, and the Agent Skills standard"
44
---
55

66
<!--
@@ -21,97 +21,164 @@ description: "Skill files, auto-discovery, GitHub import, and the Agent Skills s
2121

2222
## Overview
2323

24-
Skills are reusable units of agent behavior — a system prompt, a set of tools, and configuration packaged together. Atmosphere discovers skill files automatically and makes them available to `@Agent` classes.
24+
A skill file is a **Markdown document** that becomes the agent's system prompt. Specific sections (`## Tools`, `## Skills`, `## Channels`, `## Guardrails`) are also parsed for protocol metadata — they populate the A2A Agent Card, MCP server info, and channel routing.
2525

2626
## Skill File Format
2727

28-
A skill file is a YAML document placed at `META-INF/skills/` on the classpath. It defines the agent's personality, capabilities, and constraints.
29-
30-
```yaml
31-
# META-INF/skills/code-reviewer.skills
32-
name: code-reviewer
33-
description: Reviews pull requests for correctness and style
34-
version: 1.0.0
35-
36-
system_prompt: |
37-
You are a senior code reviewer. Focus on correctness, performance,
38-
and readability. Be concise. Cite line numbers.
39-
40-
tools:
41-
- name: readFile
42-
description: Read a file from the repository
43-
parameters:
44-
path:
45-
type: string
46-
required: true
47-
- name: listFiles
48-
description: List files in a directory
49-
parameters:
50-
directory:
51-
type: string
52-
required: true
53-
54-
config:
55-
temperature: 0.2
56-
max_tokens: 4096
28+
A skill file is plain Markdown. The `# Title` becomes the agent's display name. The body text becomes the system prompt verbatim. Named sections provide structured metadata.
29+
30+
```markdown
31+
# Dr. Molar — Emergency Dental Assistant
32+
33+
You are Dr. Molar, a friendly dental emergency assistant.
34+
You help patients who have broken, chipped, or cracked teeth.
35+
36+
## Skills
37+
- Assess dental emergencies (broken, chipped, cracked teeth)
38+
- Provide first-aid instructions for dental injuries
39+
- Recommend pain management strategies
40+
41+
## Tools
42+
- assess_emergency: Classify the severity of a dental emergency
43+
- pain_relief: Recommend appropriate pain management
44+
45+
## Channels
46+
- slack
47+
- telegram
48+
- web
49+
50+
## Guardrails
51+
- Always state you are an AI, not a real dentist
52+
- Never diagnose — only provide general guidance
53+
- Always recommend seeing a real dentist
54+
```
55+
56+
### Section Semantics
57+
58+
| Section | What it does |
59+
|---------|-------------|
60+
| `# Title` | Agent display name in console UI and Agent Card |
61+
| Body text | Becomes the system prompt sent to the LLM |
62+
| `## Skills` | Exported as capabilities in the A2A Agent Card |
63+
| `## Tools` | Cross-referenced against `@AiTool` methods at startup. Mismatches produce warnings. |
64+
| `## Channels` | Enables routing to listed channels (web, slack, telegram, discord, whatsapp, messenger) |
65+
| `## Guardrails` | Included in the system prompt and exported to MCP server info |
66+
67+
### Tool Cross-Referencing
68+
69+
At startup, the framework cross-references the `## Tools` section against `@AiTool` methods on the agent class. If a tool is listed in the skill file but no matching `@AiTool` method exists, a warning is logged:
70+
5771
```
72+
WARN: Skill file lists tool 'assess_emergency' but no @AiTool method found
73+
```
74+
75+
This catches typos and stale skill files.
5876

5977
## Auto-Discovery
6078

61-
Atmosphere scans `META-INF/skills/` on the classpath at startup. Any `.skills` file found is loaded and registered. No explicit configuration is needed — just place the file in the right location.
79+
Atmosphere searches for skill files in this order:
80+
81+
1. `META-INF/skills/{agent-name}/SKILL.md` — preferred, can be packaged in JARs
82+
2. `prompts/{agent-name}.md`
83+
3. `prompts/{agent-name}-skill.md`
84+
4. `prompts/skill.md` — fallback
85+
86+
No `skillFile` attribute needed — the framework matches by agent name automatically.
87+
88+
```
89+
src/main/resources/
90+
prompts/
91+
dentist-skill.md # matches @Agent(name = "dentist")
92+
ceo-skill.md # matches @Agent(name = "ceo")
93+
```
6294

63-
For Maven projects, put skill files in `src/main/resources/META-INF/skills/`.
95+
For distributing skills as Maven JARs:
6496

6597
```
6698
src/main/resources/
6799
META-INF/
68100
skills/
69-
code-reviewer.skills
70-
summarizer.skills
101+
code-reviewer/
102+
SKILL.md # matches @Agent(name = "code-reviewer")
71103
```
72104

73105
## Referencing Skills from `@Agent`
74106

75-
You can explicitly bind a skill file to an agent:
107+
Explicitly bind a skill file:
76108

77109
```java
78-
@Agent(name = "code-reviewer", skillFile = "META-INF/skills/code-reviewer.skills")
79-
public class CodeReviewerAgent {
80-
// agent uses the code-reviewer skill
81-
}
110+
@Agent(name = "dentist", skillFile = "prompts/dentist-skill.md",
111+
description = "Emergency dental assistant")
112+
public class DentistAgent { ... }
113+
```
114+
115+
Or let auto-discovery find it by name:
116+
117+
```java
118+
@Agent(name = "dentist", description = "Emergency dental assistant")
119+
public class DentistAgent { ... }
120+
// auto-discovers prompts/dentist-skill.md or prompts/dentist.md
121+
```
122+
123+
## Multi-Agent Skill Files
124+
125+
In a `@Coordinator` fleet, each agent has its own skill file. The coordinator also has one:
126+
127+
```
128+
prompts/
129+
ceo-skill.md # @Coordinator(name = "ceo")
130+
research-skill.md # @Agent(name = "research")
131+
strategy-skill.md # @Agent(name = "strategy")
132+
finance-skill.md # @Agent(name = "finance")
133+
writer-skill.md # @Agent(name = "writer")
82134
```
83135

84-
If no `skillFile` attribute is specified, Atmosphere matches by convention — an agent named `code-reviewer` will pick up `META-INF/skills/code-reviewer.skills` if present.
136+
Each specialist agent gets its own system prompt, tools, guardrails, and channel configuration. The coordinator's skill file describes the orchestration strategy.
85137

86138
## Importing Skills from GitHub
87139

88-
The Atmosphere CLI can import skills from GitHub repositories:
140+
The Atmosphere CLI imports skills from GitHub and generates a complete Spring Boot project:
89141

90142
```bash
91-
atmosphere import https://github.com/org/repo/path/to/skill.skills
143+
# Import from Anthropic's skills repository
144+
atmosphere import https://github.com/anthropics/skills/blob/main/skills/frontend-design/SKILL.md
145+
146+
cd frontend-design && LLM_API_KEY=your-key ./mvnw spring-boot:run
147+
# Open http://localhost:8080/atmosphere/console/
92148
```
93149

94-
Imported skills are placed into your project's `META-INF/skills/` directory and are auto-discovered on the next build.
150+
The import command:
151+
1. Parses the Markdown into `@Agent` annotations
152+
2. Extracts `## Tools` into `@AiTool` method stubs
153+
3. Places the skill file at `META-INF/skills/` for auto-discovery
154+
4. Generates a Spring Boot project that compiles and runs immediately
95155

96-
Over 1,200 skills are available in the public skill registry. Browse them at [github.com/Atmosphere/skills](https://github.com/Atmosphere/skills).
156+
Compatible with [Anthropic](https://github.com/anthropics/skills), [Antigravity](https://github.com/sickn33/antigravity-awesome-skills) (1,200+ skills), [K-Dense AI](https://github.com/K-Dense-AI/claude-scientific-skills), and any repository following the [Agent Skills](https://agentskills.io/specification) format.
97157

98158
## Trusted Sources
99159

100-
By default, Atmosphere only loads skill files from the local classpath. To load skills from remote sources at runtime, configure trusted sources:
160+
Remote imports are restricted to trusted sources by default. Use `--trust` for other URLs:
101161

102-
```properties
103-
atmosphere.skills.trusted-sources=https://github.com/Atmosphere/*,https://github.com/your-org/*
104-
```
162+
```bash
163+
# Trusted by default
164+
atmosphere import https://github.com/anthropics/skills/...
105165

106-
Skills from untrusted sources are rejected at load time.
166+
# Other sources require --trust
167+
atmosphere import https://github.com/my-org/skills/... --trust
168+
```
107169

108170
## The Agent Skills Standard
109171

110172
Atmosphere skill files follow the **Agent Skills** standard — an open specification for portable agent skill definitions. Skills written for Atmosphere can be used by any runtime that supports the standard, and vice versa.
111173

112-
Key properties of the standard:
113-
114-
- **Portable** — skill files are runtime-agnostic YAML documents
115-
- **Composable** — agents can combine multiple skills
116-
- **Versioned** — each skill declares a semantic version
174+
- **Portable** — pure Markdown, runtime-agnostic
175+
- **Composable** — agents can reference multiple skill files
176+
- **Versioned** — YAML frontmatter supports semantic versioning
117177
- **Discoverable** — standard directory layout enables auto-discovery
178+
179+
## See Also
180+
181+
- [@Agent](/docs/agents/agent/) — how agents reference skill files
182+
- [@Coordinator](/docs/agents/coordinator/) — multi-agent skill file patterns
183+
- [Dentist Agent sample](https://github.com/Atmosphere/atmosphere/tree/main/samples/spring-boot-dentist-agent) — skill file with tools, channels, and guardrails
184+
- [Startup Team sample](https://github.com/Atmosphere/atmosphere/tree/main/samples/spring-boot-multi-agent-startup-team) — 5-agent fleet with coordinator skill

0 commit comments

Comments
 (0)