Skip to content

Commit 29cf50a

Browse files
theletterfclaude
theletterf
and
claude
authored
Enhance {agent-skill} directive: poppy color, optional body, uniform font (#2898)
* Enhance {agent-skill} directive: poppy color, optional body, uniform font - Switch color scheme from teal to poppy so the callout is visually distinct from tip admonitions. - Allow optional body content to clarify the scope of a skill; falls back to default text when no body is provided. - Unify both text lines to text-base for consistent sizing. - Update tests, renderers, and documentation accordingly. Addresses #2897 Co-authored-by: Claude <noreply@anthropic.com> Made-with: Cursor * Switch to pink, responsive layout, supplementary body, updated learn-more - Use pink color scheme instead of poppy. - Make button bottom-aligned on desktop, full-width below text on mobile. - Body content is now supplementary: the default line always shows, and custom body text is rendered between it and the learn-more link. - Update learn-more text to "Learn more about agent skills for Elastic". Co-authored-by: Claude <noreply@anthropic.com> Made-with: Cursor * Use plain (grey) color scheme for agent-skill callout Co-authored-by: Claude <noreply@anthropic.com> Made-with: Cursor --------- Co-authored-by: Claude <noreply@anthropic.com>
1 parent 4aa4d7e commit 29cf50a

9 files changed

Lines changed: 116 additions & 14 deletions

File tree

‎docs/syntax/agent-skill.md‎

Lines changed: 31 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,15 +1,43 @@
11
# Agent skill
22

3-
The `{agent-skill}` directive renders a standardized callout that points readers to an [Elastic AI agent skill](https://github.com/elastic/agent-skills). It uses a fixed title and description, and includes a "Get the skill" button linking to the skill's URL.
3+
The `{agent-skill}` directive renders a standardized callout that points readers to an [Elastic AI agent skill](https://github.com/elastic/agent-skills). It includes a "Get the skill" button linking to the skill's URL.
44

55
## Usage
66

7+
By default, the directive renders a standard description:
8+
9+
:::::{tab-set}
10+
11+
::::{tab-item} Output
12+
13+
:::{agent-skill}
14+
:url: https://github.com/elastic/agent-skills@elasticsearch-esql
15+
:::
16+
17+
::::
18+
19+
::::{tab-item} Markdown
20+
21+
```markdown
22+
:::{agent-skill}
23+
:url: https://github.com/elastic/agent-skills@elasticsearch-esql
24+
:::
25+
```
26+
27+
::::
28+
29+
:::::
30+
31+
You can also provide custom body text to clarify the scope of the skill:
32+
733
:::::{tab-set}
834

935
::::{tab-item} Output
1036

1137
:::{agent-skill}
1238
:url: https://github.com/elastic/agent-skills@elasticsearch-esql
39+
40+
This skill helps agents write and optimize ES|QL queries.
1341
:::
1442

1543
::::
@@ -19,6 +47,8 @@ The `{agent-skill}` directive renders a standardized callout that points readers
1947
```markdown
2048
:::{agent-skill}
2149
:url: https://github.com/elastic/agent-skills@elasticsearch-esql
50+
51+
This skill helps agents write and optimize ES|QL queries.
2252
:::
2353
```
2454

‎src/Elastic.Documentation.Site/Assets/markdown/agent-skill.css‎

Lines changed: 4 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,31 +1,27 @@
11
@layer components {
22
.agent-skill {
3-
@apply border-teal-40 bg-teal-10 mt-4 rounded-sm border-1 pb-4;
3+
@apply border-grey-40 bg-grey-10 mt-4 rounded-sm border-1 pb-4;
44

55
.agent-skill-header {
6-
@apply bg-teal-20 text-teal-110 flex items-center gap-2 rounded-t-sm px-4 py-2 font-bold;
6+
@apply bg-grey-20 text-grey-110 flex items-center gap-2 rounded-t-sm px-4 py-2 font-bold;
77
}
88

99
.agent-skill-icon {
1010
@apply size-5 shrink-0;
1111
}
1212

1313
.agent-skill-content {
14-
@apply flex items-center justify-between gap-4 px-4 pt-3;
14+
@apply flex flex-col items-start gap-3 px-4 pt-3 md:flex-row md:items-end md:justify-between md:gap-4;
1515
}
1616

1717
.agent-skill-text {
1818
p {
1919
@apply m-0 text-base;
2020
}
21-
22-
.agent-skill-learn-more {
23-
@apply mt-1 text-sm;
24-
}
2521
}
2622

2723
.agent-skill-button {
28-
@apply bg-blue-elastic hover:bg-blue-elastic-110 focus:ring-blue-elastic-50 flex shrink-0 cursor-pointer items-center gap-1.5 rounded-sm px-6 py-2 font-sans text-sm font-semibold text-nowrap text-white! no-underline! select-none hover:text-white! focus:ring-4 focus:outline-none;
24+
@apply bg-blue-elastic hover:bg-blue-elastic-110 focus:ring-blue-elastic-50 flex w-full cursor-pointer items-center justify-center gap-1.5 rounded-sm px-6 py-2 font-sans text-sm font-semibold text-nowrap text-white! no-underline! select-none hover:text-white! focus:ring-4 focus:outline-none md:w-auto md:shrink-0;
2925
}
3026

3127
.agent-skill-button::after {

‎src/Elastic.Markdown/Myst/Directives/AgentSkill/AgentSkillView.cshtml‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,11 @@
99
<div class="agent-skill-content">
1010
<div class="agent-skill-text">
1111
<p>A skill is available to help AI agents with this topic.</p>
12-
<p class="agent-skill-learn-more">To learn more about Elastic agent skills, refer to the <a href="/explore-analyze/ai-features/agent-skills">documentation</a>.</p>
12+
@if (Model.HasBody)
13+
{
14+
@Model.RenderBlock()
15+
}
16+
<p><a href="/explore-analyze/ai-features/agent-skills">Learn more about agent skills for Elastic</a></p>
1317
</div>
1418
<a href="@Model.Url" target="_blank" rel="noopener noreferrer" class="agent-skill-button">
1519
Get the skill

‎src/Elastic.Markdown/Myst/Directives/AgentSkill/AgentSkillViewModel.cs‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,4 +7,5 @@ namespace Elastic.Markdown.Myst.Directives.AgentSkill;
77
public class AgentSkillViewModel : DirectiveViewModel
88
{
99
public required string Url { get; init; }
10+
public bool HasBody { get; init; }
1011
}

‎src/Elastic.Markdown/Myst/Directives/DirectiveHtmlRenderer.cs‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -232,7 +232,8 @@ private static void WriteAgentSkill(HtmlRenderer renderer, AgentSkillBlock block
232232
var slice = AgentSkillView.Create(new AgentSkillViewModel
233233
{
234234
DirectiveBlock = block,
235-
Url = block.Url
235+
Url = block.Url,
236+
HasBody = block.Count > 0
236237
});
237238
RenderRazorSlice(slice, renderer);
238239
}

‎src/Elastic.Markdown/Myst/Renderers/LlmMarkdown/LlmBlockRenderers.cs‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -767,6 +767,8 @@ private static void WriteAgentSkillBlock(LlmMarkdownRenderer renderer, AgentSkil
767767
renderer.Writer.Write($" url=\"{block.Url}\"");
768768
renderer.Writer.WriteLine(">");
769769
renderer.WriteLine(" A skill is available to help AI agents with this topic.");
770+
if (block.Count > 0)
771+
WriteChildrenWithIndentation(renderer, block, " ");
770772
renderer.Writer.WriteLine("</agent-skill>");
771773
renderer.EnsureLine();
772774
}

‎src/Elastic.Markdown/Myst/Renderers/PlainText/PlainTextBlockRenderers.cs‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -277,6 +277,8 @@ protected override void Write(PlainTextRenderer renderer, DirectiveBlock obj)
277277
renderer.EnsureBlockSpacing();
278278
renderer.WriteLine("Agent skill available");
279279
renderer.WriteLine("A skill is available to help AI agents with this topic.");
280+
if (agentSkillBlock.Count > 0)
281+
renderer.WriteChildren(agentSkillBlock);
280282
if (!string.IsNullOrEmpty(agentSkillBlock.Url))
281283
renderer.WriteLine(agentSkillBlock.Url);
282284
renderer.EnsureLine();

‎tests/Elastic.Markdown.Tests/Directives/AgentSkillTests.cs‎

Lines changed: 30 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -38,13 +38,13 @@ public void RendersTitle() =>
3838
Html.Should().Contain("Agent skill available");
3939

4040
[Fact]
41-
public void RendersFixedText() =>
41+
public void RendersDefaultText() =>
4242
Html.Should().Contain("A skill is available to help AI agents with this topic.");
4343

4444
[Fact]
4545
public void RendersLearnMoreLink()
4646
{
47-
Html.Should().Contain("refer to the");
47+
Html.Should().Contain("Learn more about agent skills for Elastic");
4848
Html.Should().Contain("href=\"/explore-analyze/ai-features/agent-skills\"");
4949
}
5050

@@ -59,6 +59,34 @@ public void RendersButton()
5959
}
6060
}
6161

62+
public class AgentSkillWithBodyTests(ITestOutputHelper output) : DirectiveTest<AgentSkillBlock>(output,
63+
"""
64+
:::{agent-skill}
65+
:url: https://github.com/elastic/agent-skills@elasticsearch-esql
66+
67+
This skill helps agents write and optimize ES|QL queries.
68+
:::
69+
A regular paragraph.
70+
"""
71+
)
72+
{
73+
[Fact]
74+
public void RendersCustomBody() =>
75+
Html.Should().Contain("This skill helps agents write and optimize ES|QL queries.");
76+
77+
[Fact]
78+
public void StillRendersDefaultText() =>
79+
Html.Should().Contain("A skill is available to help AI agents with this topic.");
80+
81+
[Fact]
82+
public void StillRendersLearnMoreLink() =>
83+
Html.Should().Contain("Learn more about agent skills for Elastic");
84+
85+
[Fact]
86+
public void StillRendersButton() =>
87+
Html.Should().Contain("Get the skill");
88+
}
89+
6290
public class AgentSkillMissingUrlTests(ITestOutputHelper output) : DirectiveTest<AgentSkillBlock>(output,
6391
"""
6492
:::{agent-skill}

‎tests/authoring/Blocks/AgentSkill.fs‎

Lines changed: 39 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -26,7 +26,45 @@ type ``agent skill with url`` () =
2626
<div class="agent-skill-content">
2727
<div class="agent-skill-text">
2828
<p>A skill is available to help AI agents with this topic.</p>
29-
<p class="agent-skill-learn-more">To learn more about Elastic agent skills, refer to the <a href="/explore-analyze/ai-features/agent-skills">documentation</a>.</p>
29+
<p><a href="/explore-analyze/ai-features/agent-skills">Learn more about agent skills for Elastic</a></p>
30+
</div>
31+
<a href="https://github.com/elastic/agent-skills@elasticsearch-esql" target="_blank" rel="noopener noreferrer" class="agent-skill-button">
32+
Get the skill
33+
<svg class="agent-skill-button-icon" xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke-width="2" stroke="currentColor">
34+
<path stroke-linecap="round" stroke-linejoin="round" d="M13.5 6H5.25A2.25 2.25 0 0 0 3 8.25v10.5A2.25 2.25 0 0 0 5.25 21h10.5A2.25 2.25 0 0 0 18 18.75V10.5m-10.5 6L21 3m0 0h-5.25M21 3v5.25"></path>
35+
</svg>
36+
</a>
37+
</div>
38+
</div>
39+
"""
40+
41+
[<Fact>]
42+
let ``has no errors`` () = markdown |> hasNoErrors
43+
44+
type ``agent skill with body content`` () =
45+
static let markdown = Setup.Markdown """
46+
:::{agent-skill}
47+
:url: https://github.com/elastic/agent-skills@elasticsearch-esql
48+
49+
This skill helps agents write and optimize ES|QL queries.
50+
:::
51+
"""
52+
53+
[<Fact>]
54+
let ``renders custom body`` () =
55+
markdown |> convertsToHtml """
56+
<div class="agent-skill">
57+
<div class="agent-skill-header">
58+
<svg class="agent-skill-icon" xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke-width="1.5" stroke="currentColor">
59+
<path stroke-linecap="round" stroke-linejoin="round" d="M9.813 15.904 9 18.75l-.813-2.846a4.5 4.5 0 0 0-3.09-3.09L2.25 12l2.846-.813a4.5 4.5 0 0 0 3.09-3.09L9 5.25l.813 2.846a4.5 4.5 0 0 0 3.09 3.09L15.75 12l-2.846.813a4.5 4.5 0 0 0-3.09 3.09ZM18.259 8.715 18 9.75l-.259-1.035a3.375 3.375 0 0 0-2.455-2.456L14.25 6l1.036-.259a3.375 3.375 0 0 0 2.455-2.456L18 2.25l.259 1.035a3.375 3.375 0 0 0 2.455 2.456L21.75 6l-1.036.259a3.375 3.375 0 0 0-2.455 2.456ZM16.894 20.567 16.5 21.75l-.394-1.183a2.25 2.25 0 0 0-1.423-1.423L13.5 18.75l1.183-.394a2.25 2.25 0 0 0 1.423-1.423l.394-1.183.394 1.183a2.25 2.25 0 0 0 1.423 1.423l1.183.394-1.183.394a2.25 2.25 0 0 0-1.423 1.423Z"></path>
60+
</svg>
61+
<span class="agent-skill-title">Agent skill available</span>
62+
</div>
63+
<div class="agent-skill-content">
64+
<div class="agent-skill-text">
65+
<p>A skill is available to help AI agents with this topic.</p>
66+
<p>This skill helps agents write and optimize ES|QL queries.</p>
67+
<p><a href="/explore-analyze/ai-features/agent-skills">Learn more about agent skills for Elastic</a></p>
3068
</div>
3169
<a href="https://github.com/elastic/agent-skills@elasticsearch-esql" target="_blank" rel="noopener noreferrer" class="agent-skill-button">
3270
Get the skill

0 commit comments

Comments
 (0)