Skip to content

Commit 9e14d6f

Browse files
ostermanclaudeaknysh
authored
feat: introduce Gists as community-contributed recipes (#2238)
* feat: introduce Gists as community-contributed recipes Add a "Gists" concept alongside Examples — community-contributed recipes that show creative combinations of Atmos features. Gists are shared as-is and may not be actively maintained. - Add GistDisclaimer component (purple/violet pill with lightbulb icon) - Extend file-browser plugin with `disclaimer` option for conditional rendering - Add second file-browser plugin instance at /gists route - Add "Gists" navbar link between Examples and Community - Create first gist: MCP with AWS (Custom Commands + Auth + Toolchain) - Add blog post announcing the Gists feature - Add gist-creator Claude agent for standardizing future gist creation Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * docs: replace ASCII flow diagram with Mermaid in MCP gist Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * docs: reframe MCP gist around FinOps use case The gist directory stays mcp-with-aws but the README and blog post now lead with the FinOps angle: giving AI assistants direct access to AWS cost data. Servers table is organized by category with FinOps servers highlighted. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * fix: breadcrumb shows "gists" not "examples", render Mermaid diagrams - BreadcrumbNav rootLabel now derived from plugin title instead of hardcoded "examples", so gist pages show "gists / mcp-with-aws" - FileViewer renders mermaid code blocks using Docusaurus Mermaid component instead of plain code blocks Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * fix: move disclaimer into index description, keep admonition on gist pages only Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * fix: address CodeRabbit review for gists PR - Add language tag to directory structure code fence in gist-creator agent - Add aria-hidden to decorative icon in GistDisclaimer component - Replace hardcoded author with placeholder in blog template - Fail fast on individual package install failure in mcp-with-aws gist - Remove unused server argument from test command Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * fix: address CodeRabbit review round 2 - Remove approximate line references from gist-creator agent (use symbol names only) - Inline package resolution in install-all loop to avoid recursive atmos re-entry - Add empty-argument guards to install and start commands Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com> Co-authored-by: Andriy Knysh <aknysh@users.noreply.github.com> Co-authored-by: aknysh <andriy.knysh@gmail.com>
1 parent e33692b commit 9e14d6f

File tree

16 files changed

+721
-8
lines changed

16 files changed

+721
-8
lines changed

‎.claude/agents/gist-creator.md‎

Lines changed: 141 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,141 @@
1+
---
2+
name: gist-creator
3+
description: >-
4+
Expert in creating Atmos gists with proper structure, README documentation,
5+
file-browser plugin integration, and blog post announcements.
6+
7+
**Invoke when:**
8+
- User wants to create a new gist
9+
- User asks about gist best practices
10+
- User wants to add a community recipe or pattern
11+
- User mentions "gist" in the context of documentation
12+
13+
tools: Read, Write, Edit, Grep, Glob, Bash, Task, TodoWrite
14+
model: sonnet
15+
color: purple
16+
---
17+
18+
# Gist Creator Agent
19+
20+
Expert in creating well-structured Atmos gists that demonstrate creative combinations of Atmos features.
21+
22+
## What Are Gists?
23+
24+
Gists are community-contributed recipes that show how to combine Atmos features in creative ways. Unlike maintained examples, gists are shared as-is and may not work with current versions of Atmos without adaptations.
25+
26+
## Core Responsibilities
27+
28+
1. Create new gists with proper directory structure
29+
2. Write comprehensive README documentation
30+
3. Add tags/docs mappings to the file-browser plugin
31+
4. Create blog post announcements for new gists
32+
33+
## Gist Directory Structure
34+
35+
Gists live in the `/gists/` directory at the repo root (alongside `/examples/`).
36+
37+
```text
38+
gists/{name}/
39+
├── README.md # Comprehensive guide (REQUIRED)
40+
├── atmos.yaml # Atmos configuration (REQUIRED)
41+
├── .atmos.d/ # Split config files (if applicable)
42+
│ ├── feature1.yaml
43+
│ └── feature2.yaml
44+
├── .mcp.json # MCP config (if applicable)
45+
└── stacks/ # Stack configs (if needed)
46+
```
47+
48+
## README Format
49+
50+
Every gist README.md MUST include:
51+
52+
1. **Title** — Clear, descriptive name as H1
53+
2. **Overview** — One paragraph explaining the problem and solution
54+
3. **The Problem** — What pain point this solves
55+
4. **The Solution** — How Atmos features combine to solve it
56+
5. **Features Used** — Bulleted list with links to relevant Atmos docs
57+
6. **How It Works** — Step-by-step explanation of the architecture/flow
58+
7. **Getting Started** — Prerequisites and setup steps
59+
8. **Configuration Files** — Table describing each file in the gist
60+
9. **Usage** — Concrete command examples
61+
10. **Customization** — How to adapt for different environments
62+
11. **The Key Insight** — The main takeaway or "aha moment"
63+
64+
## File-Browser Plugin Integration
65+
66+
After creating the gist directory, add entries to `website/plugins/file-browser/index.js`:
67+
68+
### TAGS_MAP
69+
Add tags for the new gist. Available tags: Quickstart, Stacks, Components, Automation, DX
70+
71+
```js
72+
'my-gist-name': ['DX', 'Automation'],
73+
```
74+
75+
### DOCS_MAP
76+
Add documentation links for the new gist:
77+
78+
```js
79+
'my-gist-name': [
80+
{ label: 'Feature Name', url: '/docs/url' },
81+
],
82+
```
83+
84+
## Blog Post Announcement
85+
86+
New gists MUST be announced with a blog post in `website/blog/YYYY-MM-DD-gist-slug.mdx`.
87+
88+
IMPORTANT: Only use tags from `website/blog/tags.yml` and authors from `website/blog/authors.yml`.
89+
90+
```mdx
91+
---
92+
slug: gist-slug
93+
title: "Gist: Descriptive Title"
94+
authors: [author-id] # Must exist in website/blog/authors.yml
95+
tags: [feature]
96+
---
97+
98+
Brief intro about the gist.
99+
100+
<!--truncate-->
101+
102+
## What This Gist Does
103+
[Description]
104+
105+
## Features Used
106+
[List of Atmos features combined]
107+
108+
## Try It Out
109+
[Link to /gists/name]
110+
111+
## Get Involved
112+
- Browse the [Gists collection](/gists)
113+
- [Join us on Slack](/community/slack)
114+
- [Attend Office Hours](/community/office-hours)
115+
```
116+
117+
## Key Differences from Examples
118+
119+
| | Examples | Gists |
120+
|---|---|---|
121+
| **Location** | `/examples/` | `/gists/` |
122+
| **Maintained** | Yes, tested each release | No, shared as-is |
123+
| **Scope** | Single feature | Multiple features combined |
124+
| **Disclaimer** | None | GistDisclaimer shown via file-browser plugin |
125+
| **Style** | Minimal config files | Rich README + config files |
126+
127+
## GistDisclaimer Component
128+
129+
The disclaimer is automatically shown on all gist pages by the file-browser plugin (configured via the `disclaimer` option in `website/docusaurus.config.js`). No manual inclusion needed in gist files.
130+
131+
The component is at `website/src/components/GistDisclaimer/` and accepts a `text` prop.
132+
133+
## Verification Checklist
134+
135+
After creating a gist:
136+
1. `gists/{name}/README.md` exists and is comprehensive
137+
2. `gists/{name}/atmos.yaml` exists
138+
3. Tags added to TAGS_MAP in `website/plugins/file-browser/index.js`
139+
4. Docs added to DOCS_MAP in `website/plugins/file-browser/index.js`
140+
5. Blog post created in `website/blog/`
141+
6. Website builds successfully: `cd website && npm run build`

‎gists/mcp-with-aws/.atmos.d/ai.yaml‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
ai:
2+
enabled: true
3+
tools:
4+
enabled: true

‎gists/mcp-with-aws/.atmos.d/mcp.yaml‎

Lines changed: 108 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,108 @@
1+
mcp:
2+
enabled: true
3+
4+
commands:
5+
- name: mcp
6+
description: Manage MCP servers
7+
commands:
8+
- name: aws
9+
description: Manage AWS MCP servers
10+
commands:
11+
- name: install
12+
description: Install one or all AWS MCP server packages
13+
arguments:
14+
- name: server
15+
description: "Server name (e.g. pricing, terraform) or 'all'"
16+
steps:
17+
- |
18+
SERVER="{{ .Arguments.server }}"
19+
if [ -z "$SERVER" ]; then
20+
echo "Missing required argument: server"
21+
exit 2
22+
fi
23+
24+
# Resolve package name from short name
25+
resolve_package() {
26+
local name="$1"
27+
AWS_PREFIXED="pricing serverless iac documentation support network"
28+
if echo "$AWS_PREFIXED" | grep -qw "$name"; then
29+
echo "awslabs.aws-${name}-mcp-server"
30+
else
31+
echo "awslabs.${name}-mcp-server"
32+
fi
33+
}
34+
35+
if [ "$SERVER" = "all" ]; then
36+
ALL_SERVERS=(
37+
billing-cost-management
38+
cost-explorer
39+
pricing
40+
terraform
41+
cfn
42+
cdk
43+
iac
44+
ecs
45+
eks
46+
serverless
47+
cloudwatch
48+
cloudtrail
49+
iam
50+
well-architected-security
51+
network
52+
dynamodb
53+
s3-tables
54+
documentation
55+
support
56+
lambda-tool
57+
stepfunctions-tool
58+
)
59+
for s in "${ALL_SERVERS[@]}"; do
60+
PACKAGE=$(resolve_package "$s")
61+
echo "Installing $PACKAGE..."
62+
if ! uv tool install "$PACKAGE" --force -q --python 3.13; then
63+
echo ""
64+
echo "Failed installing server package: $s"
65+
exit 1
66+
fi
67+
done
68+
echo ""
69+
echo "Done. All AWS MCP server packages are installed."
70+
else
71+
PACKAGE=$(resolve_package "$SERVER")
72+
echo "Installing $PACKAGE..."
73+
uv tool install "$PACKAGE" --force -q --python 3.13
74+
fi
75+
- name: start
76+
description: Start an AWS MCP server with authenticated credentials
77+
arguments:
78+
- name: server
79+
description: "Short server name (e.g. pricing, terraform, cloudwatch)"
80+
steps:
81+
- |
82+
SERVER="{{ .Arguments.server }}"
83+
if [ -z "$SERVER" ]; then
84+
echo "Missing required argument: server"
85+
exit 2
86+
fi
87+
AWS_PREFIXED="pricing serverless iac documentation support network"
88+
if echo "$AWS_PREFIXED" | grep -qw "$SERVER"; then
89+
PACKAGE="awslabs.aws-${SERVER}-mcp-server"
90+
else
91+
PACKAGE="awslabs.${SERVER}-mcp-server"
92+
fi
93+
exec env ATMOS_PROFILE=managers atmos auth exec -i core-root/terraform -- \
94+
uvx --python 3.13 "$PACKAGE@latest"
95+
- name: test
96+
description: Test that AWS MCP servers can authenticate
97+
steps:
98+
- |
99+
echo "Testing auth..."
100+
ATMOS_PROFILE=managers atmos auth exec -i core-root/terraform -- \
101+
aws sts get-caller-identity 2>&1
102+
if [ $? -ne 0 ]; then
103+
echo ""
104+
echo "Auth failed. Run: atmos auth login --identity core-root/terraform"
105+
exit 1
106+
fi
107+
echo ""
108+
echo "Auth OK. AWS MCP servers are ready."

‎gists/mcp-with-aws/.atmos.d/toolchain.yaml‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
toolchain:
2+
aliases:
3+
uv: astral-sh/uv

‎gists/mcp-with-aws/.mcp.json‎

Lines changed: 113 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,113 @@
1+
{
2+
"mcpServers": {
3+
"atmos": {
4+
"command": "atmos",
5+
"args": ["mcp", "start"]
6+
},
7+
"aws-billing-cost-management": {
8+
"command": "atmos",
9+
"args": ["mcp", "aws", "start", "billing-cost-management"],
10+
"env": { "AWS_REGION": "us-east-2" }
11+
},
12+
"aws-cost-explorer": {
13+
"command": "atmos",
14+
"args": ["mcp", "aws", "start", "cost-explorer"],
15+
"env": { "AWS_REGION": "us-east-2" }
16+
},
17+
"aws-pricing": {
18+
"command": "atmos",
19+
"args": ["mcp", "aws", "start", "pricing"],
20+
"env": { "AWS_REGION": "us-east-2" }
21+
},
22+
"aws-terraform": {
23+
"command": "atmos",
24+
"args": ["mcp", "aws", "start", "terraform"],
25+
"env": { "AWS_REGION": "us-east-2" }
26+
},
27+
"aws-cfn": {
28+
"command": "atmos",
29+
"args": ["mcp", "aws", "start", "cfn"],
30+
"env": { "AWS_REGION": "us-east-2" }
31+
},
32+
"aws-cdk": {
33+
"command": "atmos",
34+
"args": ["mcp", "aws", "start", "cdk"],
35+
"env": { "AWS_REGION": "us-east-2" }
36+
},
37+
"aws-iac": {
38+
"command": "atmos",
39+
"args": ["mcp", "aws", "start", "iac"],
40+
"env": { "AWS_REGION": "us-east-2" }
41+
},
42+
"aws-ecs": {
43+
"command": "atmos",
44+
"args": ["mcp", "aws", "start", "ecs"],
45+
"env": { "AWS_REGION": "us-east-2" }
46+
},
47+
"aws-eks": {
48+
"command": "atmos",
49+
"args": ["mcp", "aws", "start", "eks"],
50+
"env": { "AWS_REGION": "us-east-2" }
51+
},
52+
"aws-serverless": {
53+
"command": "atmos",
54+
"args": ["mcp", "aws", "start", "serverless"],
55+
"env": { "AWS_REGION": "us-east-2" }
56+
},
57+
"aws-cloudwatch": {
58+
"command": "atmos",
59+
"args": ["mcp", "aws", "start", "cloudwatch"],
60+
"env": { "AWS_REGION": "us-east-2" }
61+
},
62+
"aws-cloudtrail": {
63+
"command": "atmos",
64+
"args": ["mcp", "aws", "start", "cloudtrail"],
65+
"env": { "AWS_REGION": "us-east-2" }
66+
},
67+
"aws-iam": {
68+
"command": "atmos",
69+
"args": ["mcp", "aws", "start", "iam"],
70+
"env": { "AWS_REGION": "us-east-2" }
71+
},
72+
"aws-well-architected-security": {
73+
"command": "atmos",
74+
"args": ["mcp", "aws", "start", "well-architected-security"],
75+
"env": { "AWS_REGION": "us-east-2" }
76+
},
77+
"aws-network": {
78+
"command": "atmos",
79+
"args": ["mcp", "aws", "start", "network"],
80+
"env": { "AWS_REGION": "us-east-2" }
81+
},
82+
"aws-dynamodb": {
83+
"command": "atmos",
84+
"args": ["mcp", "aws", "start", "dynamodb"],
85+
"env": { "AWS_REGION": "us-east-2" }
86+
},
87+
"aws-s3-tables": {
88+
"command": "atmos",
89+
"args": ["mcp", "aws", "start", "s3-tables"],
90+
"env": { "AWS_REGION": "us-east-2" }
91+
},
92+
"aws-documentation": {
93+
"command": "atmos",
94+
"args": ["mcp", "aws", "start", "documentation"],
95+
"env": { "AWS_REGION": "us-east-2" }
96+
},
97+
"aws-support": {
98+
"command": "atmos",
99+
"args": ["mcp", "aws", "start", "support"],
100+
"env": { "AWS_REGION": "us-east-2" }
101+
},
102+
"aws-lambda-tool": {
103+
"command": "atmos",
104+
"args": ["mcp", "aws", "start", "lambda-tool"],
105+
"env": { "AWS_REGION": "us-east-2" }
106+
},
107+
"aws-stepfunctions-tool": {
108+
"command": "atmos",
109+
"args": ["mcp", "aws", "start", "stepfunctions-tool"],
110+
"env": { "AWS_REGION": "us-east-2" }
111+
}
112+
}
113+
}

0 commit comments

Comments
 (0)