How Do Skills Differ from Prompts in the Outputs Directory of AI Engineering From Scratch

Skills are structured, front-matter-enabled tools that agent runtimes can load and execute, while prompts are plain-text instructions meant for direct LLM consumption without runtime side effects.

The rohitg00/ai-engineering-from-scratch curriculum generates four distinct artifact types—prompts, skills, agents, and MCP servers—within each lesson's outputs/ directory. While both skills and prompts ship as Markdown files, they serve fundamentally different architectural roles in the AI engineering workflow. Understanding how skills differ from prompts in the outputs directory is essential for correctly implementing agent capabilities versus simple LLM guidance.

Core Purpose and Consumption Model

The primary distinction lies in who—or what—consumes the file and how the content is processed.

Prompts: Direct LLM Instructions

Prompts function as short textual instructions that you paste into any LLM-backed assistant to obtain expert help on a narrow task. According to the repository's README.md (lines 66-71), prompts are designed so you can "Paste into any AI assistant for expert-level help on a narrow task." They are read by humans or LLMs for immediate, on-the-fly guidance and produce no side effects in a runtime environment.

Skills: Executable Agent Capabilities

Skills act as reusable tool definitions that agents—including Claude, Cursor, Codex, OpenClaw, and Hermes—can load and invoke programmatically. The README.md describes skills as files you "Drop into Claude, Cursor, Codex, OpenClaw, Hermes, or any agent that reads SKILL.md." Unlike prompts, skills are parsed by an agent runtime as callable capabilities, enabling structured interaction loops and tool execution.

File Structure and Metadata Requirements

The files follow different naming conventions and structural requirements that reflect their distinct consumption patterns.

Filename Conventions

• Prompts: Use the pattern prompt-<name>.md (e.g., outputs/prompt-debug-agent.md)
• Skills: Use the pattern skill-<name>.md (e.g., outputs/skill-agent-loop.md)

Metadata and Front-Matter

Skills require YAML front-matter to register with agent frameworks. The front-matter block (delimited by ---) declares metadata such as name, description, phase, and lesson, enabling automatic discovery and loading.

In phases/14-agent-engineering/01-the-agent-loop/outputs/skill-agent-loop.md, the structure looks like this:

---
name: agent-loop
description: ReAct-style loop for any tool list
phase: 14
lesson: 01
---

Implement a minimal agent loop that:
* maintains a history of user queries,
* calls the LLM,
* executes tool calls when they appear,
* returns the final response.

Prompts contain no formal header. They consist of plain markdown text intended for direct consumption. For example, phases/14-agent-engineering/01-the-agent-loop/outputs/prompt-debug-agent.md contains only:

You are an agent debugger. Given the trace
of an agent run, identify the step where
the agent went wrong and explain why...

Runtime Behavior and Side Effects

The practical difference emerges when you integrate these files into code.

Using a Skill Programmatically

Skills are imported and executed as callable modules. The agent runtime parses the SKILL.md format and treats the skill as an invocable function that can maintain state and return structured results:

from skill_agent_loop import run  # loads skill-agent-loop.md

def my_tool(name, **kwargs):
    # implementation of a tool callable by the agent

    ...

result = run("Summarize the latest research on transformer scaling.", {"my_tool": my_tool})
print(result)        # ← skill-agent-loop drives the interaction

Using a Prompt with an LLM

Prompts are simply read as strings and passed to an LLM API. They steer the model's output but cannot be invoked as tools or maintain execution loops:

prompt = open("outputs/prompt-debug-agent.md").read()
response = llm_api.call(prompt + "\nTrace: ...")
print(response)      # ← prompt simply guides the model's output

The AGENTS.md file in the repository reinforces this distinction by documenting the operational contracts for contributors, specifying that skills function as agent-consumable artifacts while prompts serve as human-consumable guidance.

Summary

• Skills are executable tools with YAML front-matter (skill-<name>.md) that agent runtimes load and invoke programmatically.
• Prompts are plain-text instructions (prompt-<name>.md) pasted into LLMs for immediate guidance without side effects.
• Skills require structured metadata for agent discovery, while prompts require no formatting beyond markdown text.
• The outputs/ directory in rohitg00/ai-engineering-from-scratch contains both types, differentiated by filename prefix and presence of front-matter.

Frequently Asked Questions

Can I convert a prompt into a skill?

Yes, but you must add the required YAML front-matter block with fields like name, description, phase, and lesson, then refactor the content into a callable tool definition that the agent runtime can parse. According to the source structure in phases/14-agent-engineering/01-the-agent-loop/outputs/, the skill must follow the SKILL.md format to be discoverable by frameworks like Claude or Cursor.

Which agent frameworks support the SKILL.md format?

The repository explicitly lists Claude, Cursor, Codex, OpenClaw, and Hermes as compatible agents that can read and execute skills from the outputs/ directory. As noted in README.md (lines 66-71), these frameworks parse the front-matter and treat the skill as a loaded capability.

Do skills and prompts share the same outputs directory?

Yes, both file types coexist in the same outputs/ folder within each lesson directory. The curriculum distinguishes them by filename prefix (skill- versus prompt-) and file structure (front-matter versus plain text), allowing both human developers and automated agents to identify the correct artifact type quickly.

What happens if a skill file lacks front-matter?

The agent runtime will fail to register or load the skill. The front-matter block (---) containing metadata fields is mandatory for the discovery mechanism described in AGENTS.md. Without it, the file would be treated as plain text rather than an executable tool, similar to how prompts are processed.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}