This guide covers two things:
- Installing skills from the
agents_as_skills/directory so your AI agent can use them. - Installing the MCP tools (
ymir-commonandymir-tools) that the skills depend on, and configuring your agent to start both the privileged and unprivileged MCP gateways automatically.
The skills follow the Agent Skills standard and work with any compatible client, including Claude Code, opencode, and Cursor.
The skills in agents_as_skills/ follow the Agent Skills standard
and work with any compatible client. Consult your client's documentation for
where to place skill directories:
- Claude Code — Skills documentation
- opencode — Skills documentation
- Other clients — see the Agent Skills client list
The skills live in agents_as_skills/ in this repository. You can either clone
the repo and point your client at that directory, or download individual
SKILL.md files directly:
REPO_URL="https://raw.githubusercontent.com/packit/ai-workflows/main/agents_as_skills"
SKILLS_DIR=~/.claude/skills # adjust to your client's skills directory
for skill in preliminary-testing issue-verification errata-workflow reproducer; do
mkdir -p "$SKILLS_DIR/$skill"
curl -fsSL "$REPO_URL/$skill/SKILL.md" -o "$SKILLS_DIR/$skill/SKILL.md"
doneThe skills listed above require the Ymir MCP tools to be installed and running. The rest of this guide covers that setup.
| Gateway | Module | Tools |
|---|---|---|
| Privileged | ymir.tools.privileged.gateway |
GitLab, Jira, Copr, Koji/Kerberos, lookaside cache, dist-git branching |
| Unprivileged | ymir.tools.unprivileged.gateway |
Filesystem, shell, specfile, git operations, patches, upstream search, z-stream search |
Both gateways run as child processes (via stdio MCP transport) managed by
your agent client and are available simultaneously throughout the session.
- Python 3.13 (
python3.13package) -- the BeeAI framework used by the tools does not support Python >= 3.14 yet, and Fedora 43+ ships Python 3.14 as the default. Install Python 3.13 explicitly and create a virtual environment. - Kerberos client tools (
kinit,klist) -- required for Koji and dist-git operations - System RPM bindings (
rpmPython package) - A valid
rhel-config.jsonfile (template provided intemplates/rhel-config.json)
sudo dnf install python3.13 krb5-devel gcc python3.13-develCreate a dedicated virtual environment with Python 3.13.
python3.13 -m venv ~/.local/share/ymir-venvInstall ymir-common first because ymir-tools depends on it and the package
is not published on PyPI.
~/.local/share/ymir-venv/bin/pip install "git+https://github.com/packit/ai-workflows.git#subdirectory=ymir/common"
~/.local/share/ymir-venv/bin/pip install "git+https://github.com/packit/ai-workflows.git#subdirectory=ymir/tools"After installation, two console scripts are available inside the virtual environment:
~/.local/share/ymir-venv/bin/ymir-privileged-gateway
~/.local/share/ymir-venv/bin/ymir-unprivileged-gateway
Several tools (BuildPackageTool, CheckCveTriageEligibilityTool,
VersionMapperTool) load rhel-config.json from the current working
directory at runtime. Copy the template and fill in the real values:
cp templates/rhel-config.json ./rhel-config.json
# Edit ./rhel-config.json with actual RHEL stream dataSet the working directory in the MCP server configuration (see below) to the directory that contains this file.
| Variable | Required | Description |
|---|---|---|
MCP_TRANSPORT |
Yes | Set to stdio so the agent can communicate with the process. |
GITLAB_TOKEN |
Yes | GitLab API personal access token. |
JIRA_URL |
Yes | Base URL of the Jira instance (e.g. https://issues.redhat.com/). |
JIRA_EMAIL |
Yes | Email address for Jira Basic Auth. |
JIRA_TOKEN |
Yes | Jira API token for Basic Auth. |
GIT_REPO_BASEPATH |
No | Absolute path to a directory for git repository housekeeping. Only required if you use CloneRepositoryTool (it cleans up stale clones older than 7 days from this directory on every clone). |
KRB5CCNAME |
Yes | Kerberos credential cache location (e.g. FILE:/tmp/krb5cc_1000). |
KEYTAB_FILE |
No | Path to a Kerberos keytab for automated kinit. When unset, an existing ticket must be present. |
DRY_RUN |
No | Set to true to skip mutating Jira and lookaside operations. |
MOCK_JIRA |
No | Set to true to use a mock Jira client (for testing). |
JIRA_MOCK_FILES |
No | Directory with mock Jira JSON fixtures (only when MOCK_JIRA=true). |
SKIP_SETTING_JIRA_FIELDS |
No | Set to true to skip setting Jira custom fields. |
DEBUG_FILE |
No | Path to a log file. When set, gateway logs are written to this file in addition to stderr. Useful for debugging local installations. |
| Variable | Required | Description |
|---|---|---|
MCP_TRANSPORT |
Yes | Set to stdio so the agent can communicate with the process. |
UPSTREAM_SEARCH_API_URL |
Yes | Base URL of the upstream search service (provides /find_repository and /find_commit endpoints). |
MCP_GATEWAY_URL |
No | SSE URL of a running privileged gateway. When configured, GitHub PR and compare lookups use its authenticated tools; otherwise, the unprivileged gateway uses unauthenticated public GitHub API requests. |
DEBUG_FILE |
No | Path to a log file. When set, gateway logs are written to this file in addition to stderr. Useful for debugging local installations. |
REQUESTS_CA_BUNDLE |
No | Path to a Certificate Authority (CA) bundle, if additional or custom ones are required for workflow services. |
Add both servers using claude mcp add:
VENV="$HOME/.local/share/ymir-venv"
claude mcp add ymir-privileged \
--env MCP_TRANSPORT=stdio \
--env GITLAB_TOKEN=<your-gitlab-token> \
--env JIRA_URL=https://redhat.atlassian.net \
--env JIRA_EMAIL=you@redhat.com \
--env JIRA_TOKEN=your-jira-api-token \
--env KRB5CCNAME=FILE:/tmp/krb5cc_$(id -u) \
-- "$VENV/bin/ymir-privileged-gateway"
claude mcp add ymir-unprivileged \
--env MCP_TRANSPORT=stdio \
--env UPSTREAM_SEARCH_API_URL=http://upstream-search.hosted.upshift.rdu2.redhat.com:80/v1 \
--env REQUESTS_CA_BUNDLE=/etc/pki/ca-trust/extracted/pem/tls-ca-bundle.pem \
-- "$VENV/bin/ymir-unprivileged-gateway"Or edit ~/.claude.json directly, adding to the top-level mcpServers object
(replace <your-home> with the absolute path — ~ is not expanded in JSON):
{
"mcpServers": {
"ymir-privileged": {
"command": "<your-home>/.local/share/ymir-venv/bin/ymir-privileged-gateway",
"env": {
"MCP_TRANSPORT": "stdio",
"GITLAB_TOKEN": "<your-gitlab-token>",
"JIRA_URL": "https://redhat.atlassian.net",
"JIRA_EMAIL": "you@redhat.com",
"JIRA_TOKEN": "your-jira-api-token",
"KRB5CCNAME": "FILE:/tmp/krb5cc_1000"
}
},
"ymir-unprivileged": {
"command": "<your-home>/.local/share/ymir-venv/bin/ymir-unprivileged-gateway",
"env": {
"MCP_TRANSPORT": "stdio",
"UPSTREAM_SEARCH_API_URL": "http://upstream-search.hosted.upshift.rdu2.redhat.com:80/v1",
"REQUESTS_CA_BUNDLE": "/etc/pki/ca-trust/extracted/pem/tls-ca-bundle.pem"
}
}
}
}For project-scoped configuration, place the same mcpServers block in
.claude/settings.json inside your project directory instead. If that
does not work for you, use the .mcp.json at the root of your project.
Add both servers to ~/.config/opencode/opencode.json under the mcp key
(replace <your-home> with the absolute path):
{
"mcp": {
"ymir-privileged": {
"type": "local",
"command": ["<your-home>/.local/share/ymir-venv/bin/ymir-privileged-gateway"],
"env": {
"MCP_TRANSPORT": "stdio",
"GITLAB_TOKEN": "<your-gitlab-token>",
"JIRA_URL": "https://redhat.atlassian.net",
"JIRA_EMAIL": "you@redhat.com",
"JIRA_TOKEN": "your-jira-api-token",
"KRB5CCNAME": "FILE:/tmp/krb5cc_1000"
}
},
"ymir-unprivileged": {
"type": "local",
"command": ["<your-home>/.local/share/ymir-venv/bin/ymir-unprivileged-gateway"],
"env": {
"MCP_TRANSPORT": "stdio",
"UPSTREAM_SEARCH_API_URL": "http://upstream-search.hosted.upshift.rdu2.redhat.com:80/v1"
}
}
}
}Restart opencode after editing the config.
If you use a keytab for automated Kerberos authentication, add KEYTAB_FILE
to the privileged server's env:
"KEYTAB_FILE": "/path/to/your.keytab"Without a keytab, you must run kinit manually before launching your agent
so that a valid ticket exists in the cache pointed to by KRB5CCNAME.
If you are using KEYRING credential cache (used by Kerberos by default),
you do not need to set KRB5CCNAME. All you need is a successful kinit.
After starting your agent, confirm both MCP servers are connected. In Claude
Code run /mcp; in opencode the server list appears at startup. You should
see tools from both ymir-privileged and ymir-unprivileged.
Agent client
|
|-- stdio --> ymir-privileged (child process)
| |-- GitLab API (GITLAB_TOKEN)
| |-- Jira API (JIRA_EMAIL + JIRA_TOKEN)
| |-- Copr / Koji (Kerberos)
| |-- Lookaside cache
| |-- ZStreamSearchTool (uses Jira API internally)
|
|-- stdio --> ymir-unprivileged (child process)
|-- Local filesystem, shell, specfile, git
|-- UpstreamSearchTool --> UPSTREAM_SEARCH_API_URL