Creating Agent Skills
The Fedora Agent Skills Library is a shared collection of reusable AI skills designed to assist with Fedora contributor workflows. Skills provide AI agents with specialized context, procedural steps, and reference materials for specific community tasks.
This guide provides the technical standards and conventions for authoring new Agent Skills for the Fedora Agent Skills Library.
Overview
The library follows the open Agent Skills specification. Skills in this library are tools for community members to run in their own local AI agent environments, such as Claude Code, OpenClaw, or pi-coding-agent.
This project follows an agentic-first development model:
-
AI coding agents can draft instructions, templates, and reference materials.
-
Human contributors establish intent, review outputs, test workflows, and retain accountability for all merged changes.
-
All skills in the library are licensed under CC BY-SA 4.0.
Skill Anatomy and Directory Structure
Every skill is maintained as a self-contained directory under skills/ in the ai-ml/skills-library repository.
A skill directory consists of a mandatory SKILL.md file and optional supporting subdirectories:
skills/
└── <skill-name>/
├── SKILL.md # Required: YAML frontmatter and instructions
├── references/ # Optional: on-demand reference documentation
└── assets/ # Optional: templates and static files
The directory name and the name field in the SKILL.md frontmatter must match exactly.
All files required by a skill must reside inside its own directory.
Skills must not reference or depend on files inside other skill directories.
Frontmatter and Metadata Tags
Every SKILL.md file begins with YAML frontmatter bounded by --- delimiters:
---
name: fedora-compose-triage
description: Triage Fedora compose-tracker issues - staged workflow for investigating FINISHED_INCOMPLETE and DOOMED composes.
license: CC BY-SA 4.0
metadata:
author: cverna
tags:
- contributor
- releng
- triage
---
The frontmatter fields are defined as follows:
name-
The canonical identifier for the skill. Must match the directory slug and adhere to the naming schema below.
description-
One or two sentences explaining what the skill accomplishes and when an agent should invoke it. Agents use this description to determine whether the skill is relevant to a user request.
license-
Must be set to
CC BY-SA 4.0or another Fedora Allowed License. metadata.author-
The Fedora Account System (FAS) username or maintainer handle of the author.
metadata.tags-
A list of classification tags that indicate the target audience and workstream. Audience and category distinctions belong in
metadata.tagsrather than embedded into the skill name. Common audience tags includecontributor,packager, anduser. Common category tags includereleng,triage,meetings,infrastructure, andpackaging.
Skill Naming Schema
Skill names serve as command-line identifiers when contributors interact with their AI agents (for example, /fedora-compose-triage).
A consistent naming schema ensures predictability across a growing library.
The Disambiguation Principle
Contributors routinely install skills from multiple upstream sources into a shared local directory.
Even if a fedora- prefix appears redundant within the Fedora repository, it prevents collisions and clarifies origin once skills are blended into a user’s local environment.
Canonical Pattern
All skills in the library must follow this naming pattern:
<domain>-<subject>[-<qualifier>]-<verb>
Naming Rules
-
Character Set: Use lowercase ASCII letters, numbers, and hyphens only. Do not use underscores, spaces, or camelCase.
-
Word Count: Use at most four hyphen-separated words. Aim for three words whenever practical.
-
Intent Verb: The final element must be an infinitive verb expressing the action taken by the skill (for example,
triage,search,record,summarize). Do not use gerunds ending in-ing(usesearch, notsearching). -
Qualifiers: An optional qualifier may be inserted between the subject and the verb when necessary to distinguish between related actions on the same subject.
Domain Prefix Guidelines
Select the domain prefix based on the integration scope and dependencies of the skill:
Fedora Infrastructure and Governance (fedora-*)
Use the fedora- prefix for skills that interact with Fedora-specific services, infrastructure, or governance bodies.
This includes workflows that query or modify:
-
Koji, Bodhi, Pagure, or Fedora Forge.
-
Dist-git, compose-tracker issues, or Release Engineering tooling.
-
Bugzilla instances for Fedora components (such as FTBFS tracking).
-
Formal Fedora governance bodies (Council, FESCo, Mindshare).
Examples: fedora-compose-triage, fedora-ftbfs-search.
Project and Upstream Tooling (e.g., packit-*)
Use a tool-specific prefix when the skill operates primarily on an upstream tool or service that integrates into Fedora workflows. If the workflow targets a specific external service that has its own identity, use that project’s name as the prefix.
Example: packit-pull-from-upstream.
Generic Workflow Names
Unprefixed, generic names (such as meeting-*) are permitted only for general productivity tasks that carry no Fedora-specific dependencies or assumptions.
If a skill targets generic meeting logs but formats output specifically for Fedora channels (such as Fedora Discussion tags or Fedora Forge ticket comments), it should use the fedora- prefix (for example, fedora-meeting-record).
Reference and Migration Examples
The following table illustrates how existing and proposed skills align with the naming schema:
| Current Name | Status | Rationale |
|---|---|---|
|
Conforming |
Follows |
|
Conforming |
Follows |
|
Legacy (to migrate) |
Noun-led and lacks an infinitive verb.
Target migration name: |
|
Legacy (to migrate) |
Exceeds recommended word count and ends with a noun state ( |
Author Workflow and Best Practices
Follow this workflow when developing and contributing a new Agent Skill:
-
Check Existing Skills: Review the skills directory to ensure the functionality does not duplicate an existing skill.
-
Open an Issue: For new skills, open an issue to discuss the proposed workflow with the community.
-
Create the Skill Directory: Create
skills/<skill-name>/matching the canonical naming pattern. -
Draft Instructions: Write clear, sequential, and deterministic instructions in
SKILL.md. Specify exact CLI commands, expected arguments, output structures, and error handling steps. -
Provide Templates and References: Place reusable output templates in
assets/and background documentation inreferences/. -
Test Locally: Load the skill into your local AI coding agent and test it against real-world scenarios to verify that the agent follows the instructions without hallucinating.
-
Security and Privacy: Never commit API keys, personal access tokens, or private credentials. Use environment variable placeholders (such as
$FEDORA_FORGE_TOKEN) in command examples. -
Submit a Pull Request: Submit your contribution to the ai-ml/skills-library repository on Fedora Forge.
Want to help? Learn how to contribute to Fedora Docs ›