Skills Template

This repository serves as a standardized example that showcases the functional capabilities and best practices to follow for creating agent skills.

What are Skills?

Agent skills are modular packages that extend an AI’s capabilities with task-specific instructions, resources, and logic. They allow agents to follow multi-step workflows reliably by bundling all necessary components into a single, reusable unit. These standardized modules are designed to be shared across teams to ensure consistent and scalable performance. Among this the capabilities of a skill we find:

• Instructional Logic: Providing the agent with specific "How-To" steps for a specialized task.

• Asset Management: Giving the agent access to fixed templates, brand guidelines, or structural schemas.

• Deterministic Execution: Running local scripts to perform calculations, file manipulations, or data formatting that an LLM cannot do reliably on its own.

• Stateful Workflows: Allowing an agent to track progress through a multi-stage process, ensuring no steps are skipped.

This repository provides a concrete implementation of an agent skill designed to generate standardized README files based on a predefined structure.

When to use them?

Skills should be used for repeatable, multi-step procedures where consistent execution is critical.

Use cases

• Standardized Workflows: Tasks that follow a rigid, step-by-step set of instructions to ensure the result is the same every single time. (Example: Generating a repository structure)

• Deterministic Logic: Use skills when a task requires executing local scripts or code to ensure the output matches a strict template or schema.

• Portable Capabilities: Use skills when a capability needs to be shared across multiple agents, teams, or projects without rewriting the underlying logic.

• Strict Compliance: Use skills for tasks where deviation is a bug rather than an advantage (Example: Generating an API scaffold where folder structure, naming conventions, and middleware setup must match the team's standard every time.)

When NOT to use them?

Skills should be avoided for general behavioral guidance, simple one-off interactions, or tasks that require real-time data retrieval. They are not intended to replace an agent's core reasoning or its ability to access dynamic external environments.

Avoid skills when the goal is to adapt to a situation rather than follow a set pattern. If the 'right answer' depends on unique circumstances, a rigid skill will only get in the way of the agent’s reasoning.

Differences with MCP Tools

While skills manage the logic and workflow, Model Context Protocol (MCP) tools are used for data acquisition. (Example: Fetching raw data from a database should be handled by an MCP tool, whereas a skill would take that raw data and process it into a standardized report.)

Skill Focus

A skill should be designed to perform a single, focused task. If a skill is overloaded with an extended or complex set of tasks, the agent's performance may degrade, potentially leading to incomplete execution or "hallucinated" shortcuts. Keeping tasks trivial and specific ensures high reliability and predictable outcomes.

Skill composition

Skills can invoke other skills. A wrapper skill can orchestrate multiple focused skills in sequence, keeping itself simple by letting each focused skill handle the specialized task.

Here is a decomposed ETL skill example:

• skill-layer-1 — raw ingestion conventions
• skill-layer-2 — transformation logic pattern
• skill-layer-3 — output/serving layer structure
• skill-etl-pipeline — wrapper that orchestrates the three in order

General Structure

.agents/
    └── skills/
        └── my-skill/
            ├── SKILL.md             # Required: Core instructions and metadata.
            ├── scripts/             # Optional: Local executable code or logic wrappers.
            ├── references/          # Optional: Technical documentation and context.
            └── assets/              # Optional: Templates (e.g., README structures) and resources.
AGENTS.md                            # Optional: General intructions applied to the behaviour of the agents.

YAML file or headers

To ensure that agents can discover and trigger skills correctly, metadata (skill name, description, and activation keywords) must be provided. The location of this metadata depends on the provider:

• Anthropic Claude & Google Gemini: The metadata is placed directly at the top of the SKILL.md file using a YAML header.

  ---
  name: readme-generator
  description: A skill for creating standardized project READMEs.
  ---
  # Instructions
  1. Access the /assets folder...
  

• OpenAI Codex: The name and description also resides in the SKILL.md file. Optional metadata like dependencies, policy or interface can be provided in a separate folder and file agents/openai.yaml.

  .agents/
      └── skills/
          └── my-skill/
              ├── SKILL.md             # Required: YAML Metadata + Skill Instructions.
              ├── scripts/             # Optional: Local executable logic.
              ├── references/          # Optional: Background context/docs.
              ├── assets/              # Optional: Templates and resources.
              └── agents/              
                  └── openai.yaml      # Optional: OpenAI-specific UI and Tool config.
  AGENTS.md                            # Optional: General intructions applied to the behaviour of the agents.
  

AGENTS.md

AGENTS.md is used to add instructions for the general behavior of the agent in a repository.

Unlike skills, which are meant for focused and repeatable workflows, AGENTS.md applies more broadly and can guide the agent during both skill execution and normal repository queries.

In this repository, AGENTS.md also instructs the agent to use the specific Python interpreter intended for the project, whether that is managed through uv or a local virtual environment.

This matters because the skills in this repository require script execution, so the agent should use the project environment instead of relying on a global Python installation.

Provider documentation

Please check the specific provider's documentation for exact additional YAML fields.

• OpenAI Codex Skills

• Claude Code Skills

• Gemini CLI Skills