# How Do Skills Differ from Prompts in the Outputs Directory of AI Engineering From Scratch > Understand the difference between AI engineering skills and prompts. Skills are structured tools for agent runtimes, while prompts are plain text instructions for LLMs. - Repository: [Rohit Ghumare/ai-engineering-from-scratch](https://github.com/rohitg00/ai-engineering-from-scratch) - Tags: deep-dive - Published: 2026-06-13 --- **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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/README.md) describes skills as files you "*Drop into Claude, Cursor, Codex, OpenClaw, Hermes, or any agent that reads [`SKILL.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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-.md` (e.g., [`outputs/prompt-debug-agent.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/outputs/prompt-debug-agent.md)) - **Skills**: Use the pattern `skill-.md` (e.g., [`outputs/skill-agent-loop.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/phases/14-agent-engineering/01-the-agent-loop/outputs/skill-agent-loop.md), the structure looks like this: ```markdown --- 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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/phases/14-agent-engineering/01-the-agent-loop/outputs/prompt-debug-agent.md) contains only: ```markdown 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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/SKILL.md) format and treats the skill as an invocable function that can maintain state and return structured results: ```python 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: ```python 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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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-.md`) that agent runtimes load and invoke programmatically. - **Prompts** are plain-text instructions (`prompt-.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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/AGENTS.md). Without it, the file would be treated as plain text rather than an executable tool, similar to how prompts are processed.