DEV Community: Dan

Skills: teaching AI agents to act consistently

Dan — Mon, 09 Feb 2026 19:03:54 +0000

If you are an avid follower of the latest advancements in the AI ecosystem, you may have come across the term Skills or Agent Skills. In this post we'll explore the concept of Skills and how they can be used to enhance the capabilities of AI agents.

Before we get started, we need to clarify something. The term “skill” is used ambiguously and can mean different things depending on the context. Anthropic originally introduced Skills as a concept. This later expanded into the Agent Skills project and then into a broader distribution layer for a fragmented ecosystem: you build once, publish to GitHub (and to skills.sh), and it works across Claude, Cursor, Copilot, and similar tools.

Now that we have that out of the way, let's dive into the concept of Skills.

What are Skills?

Skills teach AI agents how to do specific tasks consistently. Instead of explaining what you want every time, you write the instructions once and the agent follows them automatically*. (More on this bit later.)

Think of it like this: You could tell a new colleague how to format meeting notes every single time, or you could give them a one-page guide they reference whenever they need it. Skills are that guide, but for AI agents.

A simple example

Say you want Claude to always format your meeting notes a certain way: attendees at the top, key decisions in bold, action items as a checklist. Without a skill, you'd need to include these instructions in every prompt or via the system prompt.

With a skill, you write those instructions once:

---
name: meeting-notes
description: "Format meeting notes with attendees, decisions, and action items."
---

# Meeting Notes Formatting

## Structure

1. List attendees at the top
2. Summarise the discussion in 2-3 paragraphs
3. Bold all key decisions
4. End with action items as a checklist, each assigned to a person

Now whenever you ask the agent to format meeting notes, it automatically follows your style.

What's inside a skill?

A skill is really just a folder containing a SKILL.md file, where the file has two parts:

Metadata (name and description as frontmatter): tells the agent what the skill does
Instructions: tells the agent the specifics of the skill

The metadata is called progressive disclosure in Anthropic's resources, as it provides just enough information that allows agents to know when skills should be loaded without having to load all of them into context.

Of course there could be situations when you want to give more complex tasks for agents and for such cases you can add supporting files:

my-skill/
├── SKILL.md
├── scripts/      # code the agent can run
├── references/   # additional documentation
└── assets/       # example files or formats

Let's take a look at what files would go into these folders, starting with scripts/.

Files in the scripts folder should contain code that the agent can run during the task. Continuing with our meeting notes example, the skill could include a script that fetches attendee info from a calendar API or the status of a project:

scripts/
├── fetchAttendees.ts
└── fetchProjectStatus.ts

There are a couple of important things to keep in mind regarding the scripts folder:

Keep scripts self-contained: either bundle dependencies or document what needs to be installed.
Include clear error messages so the agent (and you) can troubleshoot when something goes wrong.

In terms of programming language, TypeScript, JavaScript, Python, and Bash are commonly supported.

Next, the references/ folder. This should contain additional documentation the agent can read when it needs more detail. For example, the meeting notes skill might have different formatting guidelines depending on the meeting type:

references/
├── standup-format.md
├── client-call-format.md
└── board-meeting-format.md

As a rule of thumb, keep each file focused on one topic. Agents load these on demand, so smaller files mean faster responses and less context used.

Last but not least, the assets/ folder. As the name suggests, this folder is for static files like templates, images, or additional data. For our meeting notes skill, we could include reference data such as project codes so the meeting notes can reference those:

assets/
├── team-roster.json
└── project-codes.json

How agents use skills

Agents don't load every skill into memory at once, as that would be slow. Instead they use a three-step process:

Scan: On startup, the agent reads only the name and description of each skill. This is lightweight, just enough to know what's available.
Match: When you make a request, the agent checks if any skill descriptions match what you're asking for.
Load: If there's a match, the agent reads the full instructions and follows them. It only loads additional files (scripts, templates) if the instructions reference them.

We have to take a sidestep here. One organisation found that in 56% of cases, skills weren't triggered reliably.

Turns out, LLMs are "lazy" and they don't always follow instructions. They might skip steps or make assumptions that aren't correct. This is why it's important to be explicit and detailed in your instructions. The best way to do that, and to reliably invoke skills, is to make an AGENTS.md file available as well for the agent, with this important instruction:

IMPORTANT: Prefer retrieval-led reasoning over pre-training-led reasoning

The only question that remains: what should AGENTS.md contain? Because LLMs can be "lazy" they don't always use skills reliably, therefore a viable solution is to combine skills with appropriate instructions for the agent.

Now assuming that we have ended up with a skill called meeting-notes that would look like this:

meeting-notes/
├── SKILL.md
├── AGENTS.md
├── scripts/
│   ├── fetchAttendees.ts
│   └── extractActionItems.ts
├── references/
│   ├── standup-format.md
│   ├── client-call-format.md
│   └── board-meeting-format.md
└── assets/
    ├── notes-template.md
    ├── team-roster.json
    └── project-codes.json

We can combine this with the AGENTS.md file using the following structure:

# AGENTS.md

## Meeting Notes

Structure: Prefer retrieval-led reasoning over pre-training-led reasoning

Available in `meeting-notes/` skill:

- scripts/{fetchAttendees.ts, extractActionItems.ts}
- references/{standup-format.md, client-call-format.md, board-meeting-format.md}
- assets/{notes-template.md, team-roster.json, project-codes.json}

Installing skills

Based on what we saw earlier, you can go ahead and create skills yourself by following the structure outlined above. However, a slightly better way is to install them. Some service providers, including Trigger, have created specific packages that you can install using npm. There are also organisations that maintain a directory of skills from various service providers.

The only question that remains is: what is the difference between AGENTS.md and SKILL.md?

Simply put, AGENTS.md is global. It provides persistent, global context that gets loaded every time by the agent. SKILL.md is called on-demand, loaded only when needed for specific tasks. Think about it this way: AGENTS.md is the sticky note on your monitor (which I hope you don't use to store your password), always visible. SKILL.md is a manual in your drawer which you only reach for when you actually need it.

Conclusion

Skills are not just a convenience feature for agents; they are an architectural primitive for building reliable, repeatable behaviour in systems powered by LLMs. They allow you to move intent and process out of fragile, one-off prompts into artefacts that agents can discover and apply when appropriate.

The key insight is that skills work best when paired with clear agent-level guidance. SKILL.md defines what an agent can do and how to do it, while AGENTS.md shapes when and why those skills should be used. Together, they shift away from ad-hoc reasoning toward retrieval-led execution, improving consistency and reducing missed steps or silent failures.

If you care about agents that behave predictably, evolve safely, and improve over time, skills are no longer optional but they are foundational.

Trigger anything from a database change using Supabase with Trigger.dev ⚡️

Dan — Mon, 21 Oct 2024 15:29:00 +0000

Introduction

In this article we'll be learning how to use Trigger.dev with Supabase:

What are the benefits of using Trigger.dev with Supabase?
Unlocking the power of Supabase and Trigger.dev
- Triggering tasks from Supabase Edge Functions
- Performing database operations
- Interacting with Supabase storage
- Triggering tasks from database events: creating an advanced video processing pipeline
Next steps

What are the benefits of using Trigger.dev with Supabase?

Supabase is an open-source Firebase alternative, providing a backend-as-a-service with a full suite of tools you can use in your projects, including a Postgres-compatible relational database, Database Webhooks, Edge Functions, authentication, instant APIs, realtime and storage.

Used in conjunction with Trigger.dev, you can trigger tasks from database events, and then offload the execution to Trigger.dev’s elastic infrastructure.

This makes it easy to build event-driven workflows, written in normal code, that interact with your application, database and external services.

// Add a new user subscription
export const createUserSubscription = task({
  id: "create-user-subscription",
  run: async (payload: { userId: string; plan: string }) => {
    const { userId, plan } = payload;

    logger.log(`Inserting new user ${userId} to user_subscriptions table`);

    const { error } = await supabase.from("user_subscriptions").insert({
      user_id: userId,
      plan: plan,
    });

    if (error) throw new Error(`Failed to insert new user: ${error.message}`);

    logger.log(`New user added successfully: ${userId} on ${plan} plan`);

    return { userId, plan };
  },
});

Every run is observable in the Trigger.dev dashboard, giving you live trace views and detailed logs to help with development and debugging.

Unlocking the power of Supabase and Trigger.dev

We have created a series of examples and guides which cover a range of common use cases. They can be extended and modified to get the best out of Supabase and Trigger.dev.

Triggering tasks from Supabase Edge Functions

Supabase Edge functions run close to your users for faster response times. They are executed in a secure environment and have access to the same APIs as your application. They can be used to trigger a task from an external event such as a webhook, or from a database event with the payload passed through to the task.

This very basic implementation demonstrates how to trigger a 'Hello World' task from a Supabase Edge Function when the Edge Function URL is visited.

Deno.serve(async () => {
  await tasks.trigger<typeof helloWorldTask>(
    // Your task id
    "hello-world",
    // Your task payload
    "Hello from a Supabase Edge Function!"
  );
  return new Response("OK");
});

To learn how to build this example yourself, check out our Triggering tasks from Supabase Edge Functions guide.

Performing database operations

You can also run CRUD operations directly from your tasks. This is useful for updating your database in response to an event, e.g. a user signing up, or adding data to a database on a repeating schedule, e.g. every day at 10am, etc.

The task below demonstrates updating a user's subscription in a table by either inserting a new row or updating an existing one with the new plan, depending on whether the user already has a subscription.

It takes a payload with a userId and newPlan, and updates the user_subscriptions table in Supabase with the new plan.

export const supabaseUpdateUserSubscription = task({
  id: "update-user-subscription",
  run: async (payload: { userId: string; newPlan: PlanType }) => {
    const { userId, newPlan } = payload;

    // Abort the task run without retrying if the new plan type is invalid
    if (!["hobby", "pro", "enterprise"].includes(newPlan)) {
      throw new AbortTaskRunError(
        `Invalid plan type: ${newPlan}. Allowed types are 'hobby', 'pro', or 'enterprise'.`
      );
    }

    // Query the user_subscriptions table to check if the user already has a subscription
    const { data: existingSubscriptions } = await supabase
      .from("user_subscriptions")
      .select("user_id")
      .eq("user_id", userId);

    if (!existingSubscriptions || existingSubscriptions.length === 0) {
      // If there are no existing users with the provided userId and plan, insert a new row
      const { error: insertError } = await supabase
        .from("user_subscriptions")
        .insert({
          user_id: userId,
          plan: newPlan,
          updated_at: new Date().toISOString(),
        });

      // If there was an error inserting the new subscription, throw an error
      if (insertError) {
        throw new Error(
          `Failed to insert user subscription: ${insertError.message}`
        );
      }
    } else {
      // If the user already has a subscription, update their existing row
      const { error: updateError } = await supabase
        .from("user_subscriptions")
        // Set the plan to the new plan and update the timestamp
        .update({ plan: newPlan, updated_at: new Date().toISOString() })
        .eq("user_id", userId);

      // If there was an error updating the subscription, throw an error
      if (updateError) {
        throw new Error(
          `Failed to update user subscription: ${updateError.message}`
        );
      }
    }

    // Return an object with the userId and newPlan
    return { userId, newPlan };
  },
});

To learn more, check out our Supabase database operations guide in our docs.

Interacting with Supabase storage

Supabase Storage can be used to store images, videos, or any other type of file.

Tasks using Supabase Storage can be useful for media processing, such as transcoding videos, resizing images, AI manipulations, etc.

This task demonstrates uploading a video from a videoUrl to a storage bucket using the Supabase client:

export const supabaseStorageUpload = task({
  id: "supabase-storage-upload",
  run: async (payload: { videoUrl: string }) => {
    const { videoUrl } = payload;

    const bucket = "my_bucket";
    const objectKey = `video_${Date.now()}.mp4`;

    // Download video data as a buffer
    const response = await fetch(videoUrl);
    const videoBuffer = await response.buffer();

    // Upload the video directly to Supabase Storage
    const { error } = await supabase.storage
      .from(bucket)
      .upload(objectKey, videoBuffer, {
        contentType: "video/mp4",
        upsert: true,
      });

    // Return the video object key and bucket
    return {
      objectKey,
      bucket: bucket,
    };
  },
});

To learn more, check out our Supabase storage upload examples in our docs.

Creating an advanced video processing pipeline

You can also trigger tasks from database events, such as a new row being inserted into a table. This adds realtime functionality to your tasks, allowing you to build workflows that respond to changes in your database.

In this more advanced example, we'll show you how to trigger a task when a row is added to a table in a Supabase database, using a Database Webhook and Edge Function.

This task will download a video from a URL, extract the audio using FFmpeg, transcribe the video using Deepgram and then update the table with the new transcription.

Triggering a task from a database event

In Supabase, a database webhook has been created which triggers an Edge Function called video-processing-handler when a new row containing a video_url is inserted into the video_transcriptions table. The webhook will pass the new row data to the Edge Function as a payload.

This Edge Function triggers a videoProcessAndUpdate task:

Deno.serve(async (req) => {
  const payload = await req.json();

  // This payload will contain the video url and id from the new row in the table
  const videoUrl = payload.record.video_url;
  const id = payload.record.id;

  // Trigger the videoProcessAndUpdate task with the videoUrl payload
  await tasks.trigger<typeof videoProcessAndUpdate>(
    "video-process-and-update",
    { videoUrl, id }
  );
  console.log(payload ?? "No name provided");

  return new Response("ok");
});

Creating the video processing task

The videoProcessAndUpdate task takes the payload from the Edge Function, and uses it to download the video as a temporary file from the URL, then transcribes the video using Deepgram AI and then updates the video_uploads table in Supabase with the new transcription.

export const videoProcessAndUpdate = task({
  id: "video-process-and-update",
  run: async (payload: { videoUrl: string; id: number }) => {
    const { videoUrl, id } = payload;

    const outputPath = path.join(os.tmpdir(), `audio_${Date.now()}.wav`);
    const response = await fetch(videoUrl);

    // Extract the audio using FFmpeg
    await new Promise((resolve, reject) => {
      if (!response.body) {
        return reject(new Error("Failed to fetch video"));
      }

      ffmpeg(Readable.from(response.body))
        .outputOptions([
          "-vn", // Disable video output
          "-acodec pcm_s16le", // Use PCM 16-bit little-endian encoding
          "-ar 44100", // Set audio sample rate to 44.1 kHz
          "-ac 2", // Set audio channels to stereo
        ])
        .output(outputPath)
        .on("end", resolve)
        .on("error", reject)
        .run();
    });

    logger.log(`Audio extracted from video`, { outputPath });

    // Transcribe the audio using Deepgram
    const { result, error } = await deepgram.listen.prerecorded.transcribeFile(
      fs.readFileSync(outputPath),
      {
        model: "nova-2", // Use the Nova 2 model
        smart_format: true, // Automatically format the transcription
        diarize: true, // Enable speaker diarization
      }
    );

    if (error) throw error;

    // Extract the transcription from the result
    const transcription =
      result.results.channels[0].alternatives[0].paragraphs?.transcript;

    fs.unlinkSync(outputPath); // Delete the temporary audio file
    logger.log(`Temporary audio file deleted`, { outputPath });

    const { error: updateError } = await supabase
      .from("video_transcriptions")
      // Update the transcription and video_url columns
      .update({ transcription: transcription, video_url: videoUrl })
      // Find the row by its ID
      .eq("id", id);

    if (updateError) {
      throw new Error(`Failed to update transcription: ${updateError.message}`);
    }

    return {
      message: `Summary of the audio: ${transcription}`,
      result,
    };
  },
});

To build this example yourself, check out our Triggering tasks from database events guide in our docs.

Next steps

In this article we've covered how to trigger tasks from Supabase Edge Functions, perform database operations and interact with Supabase Storage. We've also shown you how to trigger tasks from database events, and build a more complex workflow that interacts with your database and external services.

To follow along with the examples in this article, all our guides and examples can be found in our docs.

If you found this article useful, please consider sharing it with anyone you think would be interested in using Supabase with Trigger.dev.