Skills & AGENTS.md

Give your agents reusable instructions — on-demand or always-on

Slide supports two complementary ways to inject instructions into your agent’s system prompt:

• Skills — progressively disclosed on-demand via the activate_skill tool
• AGENTS.md — eagerly loaded into the system prompt at init time

Both follow open standards: Open Agent Skills and AGENTS.md.

Code Examples

Skills Example

Progressive skill disclosure in action

AGENTS.md Example

Project instructions in action

Skills

Skills let you package reusable instructions that agents load only when they need them. Instead of stuffing everything into the system prompt, skills keep the prompt small and focused — the agent sees a short menu of available skills and activates the ones relevant to the current task.

How skills work

1. You point the agent at one or more skill directories
2. At init time, only each skill’s name and description appear in the system prompt
3. When the agent decides it needs a skill, it calls the activate_skill tool
4. The skill root path and full instructions from SKILL.md are returned to the agent as a tool result

Creating a skill

A skill is a directory containing a SKILL.md file. The file has YAML frontmatter (name + description) followed by markdown instructions:

my-project/
└── skills/
    ├── code-review/
    │   └── SKILL.md
    └── testing/
        └── SKILL.md

Example SKILL.md:

---
name: code-review
description: Guidelines for performing thorough code reviews
---
# Code Review Skill

## What to look for
- Correctness: Does the code do what it's supposed to?
- Readability: Is the code easy to understand?
- Performance: Are there unnecessary allocations or O(n²) loops?
- Security: Are inputs validated? Are there injection risks?

## How to format feedback
- Use inline comments for specific issues
- Summarize overall impressions at the top
- Always mention what was done well

Frontmatter requirements

Field	Rules
name	Lowercase alphanumeric + hyphens, max 64 chars (e.g. code-review)
description	Plain text, max 1024 chars

Using skills with an agent

from tyler import Agent

agent = Agent(
    model_name="gpt-4.1",
    purpose="A helpful coding assistant",
    skills=[
        "./skills/code-review",
        "./skills/testing",
    ],
)

The agent’s system prompt will include something like:

# Available Skills
Use the `activate_skill` tool to load full instructions for any skill.

- **code-review**: Guidelines for performing thorough code reviews
- **testing**: Guidelines for writing comprehensive tests

When the agent encounters a task that matches a skill, it will call activate_skill with the skill name and receive the full instructions.

Using skills with config files

name: "MyAgent"
model_name: "gpt-4.1"
purpose: "A helpful assistant"
skills:
  - "./skills/code-review"
  - "./skills/testing"
  - "~/shared-skills/documentation"

Relative paths are resolved relative to the config file’s directory.

---

AGENTS.md

AGENTS.md files provide project-level instructions that are eagerly loaded into the agent’s system prompt at init time. Unlike skills (which are progressively disclosed), AGENTS.md content is always present — making it ideal for coding standards, API conventions, and other rules that should always apply.

How it works

1. Auto-discovery is enabled by default, or you point the agent at one or more AGENTS.md files
2. At init time, the file contents are loaded and placed in a <project_instructions> block in the system prompt
3. The agent sees these instructions on every interaction

Creating an AGENTS.md file

Create an AGENTS.md file in your project root (or any directory). No special frontmatter or formatting is required — it’s just markdown:

# Project Guidelines

## Code Style
- Use type hints for all function signatures
- Follow PEP 8 naming conventions
- Prefer `async`/`await` over threads for I/O-bound operations

## Error Handling
- Always use specific exception types (never bare `except:`)
- Include meaningful error messages with context
- Use `logging` instead of `print` for diagnostics

## API Conventions
- Use `httpx` for HTTP requests (async-native)
- Always set timeouts on external calls
- Return typed dataclasses or Pydantic models, not raw dicts

Using AGENTS.md with an agent

Default auto-discovery

By default, Tyler discovers AGENTS.md files by walking upward from the current working directory:

from tyler import Agent

agent = Agent(
    model_name="gpt-4.1",
    purpose="A helpful coding assistant",
)

Explicit path

from tyler import Agent

agent = Agent(
    model_name="gpt-4.1",
    purpose="A helpful coding assistant",
    agents_md="./AGENTS.md",
)

Auto-discovery

You can also set agents_md=True explicitly. Agent.from_config() starts discovery from the config file directory when agents_md is omitted or set to true:

agent = Agent(
    model_name="gpt-4.1",
    purpose="A helpful coding assistant",
    agents_md=True,
)

This is useful in monorepos where you might have:

project-root/AGENTS.md          # Company-wide rules
project-root/backend/AGENTS.md  # Backend-specific rules

Files are loaded root-first, so the closest file’s instructions appear last (taking natural precedence).

Disable loading

agent = Agent(
    model_name="gpt-4.1",
    purpose="A helpful coding assistant",
    agents_md=False,
)

Multiple files

agent = Agent(
    model_name="gpt-4.1",
    agents_md=["./AGENTS.md", "./docs/coding-standards.md"],
)

Multiple files are joined with --- separators.

Using AGENTS.md with config files

name: "MyAgent"
model_name: "gpt-4.1"
purpose: "A helpful assistant"

# Default: auto-discover from this config directory upward
# agents_md: true

# Disable loading
# agents_md: false

# Explicit path
# agents_md: "./AGENTS.md"

# Multiple files
# agents_md:
#   - "./AGENTS.md"
#   - "./docs/coding-standards.md"

# Keep "system" unless your provider supports developer messages
instruction_role: "system"

Relative paths are resolved relative to the config file’s directory.

Size limits

AGENTS.md content is guarded against oversized files:

• Individual files larger than 100,000 characters are skipped with a warning
• Combined content from multiple files is truncated at 100,000 characters

If your instructions exceed this limit, consider moving task-specific content into skills instead.

---

When to use which

	Skills	AGENTS.md
Loading	On-demand (progressive disclosure)	Eager (always in prompt)
Best for	Task-specific instructions the agent may or may not need	Project-wide rules that always apply
Prompt impact	Minimal — only name + description until activated	Full content always present
Format	SKILL.md with YAML frontmatter	Plain markdown

Use AGENTS.md for short, universal project rules that should always be in context. Use skills for detailed, task-specific instructions that only matter sometimes. You can use both together.

Next steps

Adding Tools

Give your agents more capabilities

MCP Integration

Connect to external tool servers