“Becoming good at prompting” used to sound like learning secret words. Modern AI does not reward magic phrases nearly as much as it rewards a clear job, relevant context, useful examples, and a way to recognize a good result.

The important shift is this: a prompt does not have to live in a chat box. It can live in a Markdown file where it can be inspected, improved, reused, and handed to an agent.

The difference between a request and an instruction

This is a request:

This is an instruction:

# Company Research Brief

## Objective
Explain how this company makes money, what could change its growth,
and the strongest evidence for and against the current thesis.

## Required evidence
- Latest annual and quarterly filings
- Management guidance
- Competitor comparison
- Source links for every material claim

## Rules
- State the date of every time-sensitive figure.
- Separate facts from interpretation.
- Flag missing evidence; do not fill gaps with guesses.

## Deliverable
Return a concise brief with sections for business model, financial
position, catalysts, risks, and unanswered questions.

The second version does not make the AI magically smarter. It makes the work legible. It tells the AI what success looks like and gives you something concrete to improve when the output is weak.

The six parts of a useful prompt file

Not every prompt file needs all six. A small formatting task may need only a goal and an output format. A consequential research or build task usually needs more.

Research first; prompt second

The best prompt files are usually built from a conversation. You might use ChatGPT or Claude to explore an idea, look at competitors, challenge assumptions, and identify the questions that matter. That exploratory work can be messy. It should be.

But once you have learned something useful, do not leave it scattered across browser tabs and chat history. Distill it into the file.

Research and conversationDecisionsPrompt fileAgent does the jobInspect and improve

This is how a prompt gets better: not by adding dramatic adjectives, but by improving the research, rules, examples, and evaluation criteria.

Sonariq as a supporting example

Sonariq uses researched Markdown prompts to define different research jobs. The actual workflow includes files for research direction, qualitative company research, financial-data handoff, valuation, independent validation, critique, and final analysis.

Those files exist because “analyze this stock” is not one job. It hides many different jobs. The same is true in your work. “Build my website” may hide product definition, page architecture, copy, visual design, data structure, and testing.

When a prompt file becomes a skill

Not every Markdown prompt is a skill. A one-time prompt may be useful only for today’s task. A skill is a prompt file that has become a reusable capability: it has a defined job, a repeatable method, clear inputs and outputs, and rules that make it safe to use again.

Here is the distinction:

The difference is not the extension. They may all be Markdown files. The difference is the job the file has inside the system.

Skills in Codex and Claude

Codex and Claude can both work from Markdown instructions. The important concept is the same in both tools: give the agent a small, clear, reusable playbook for one kind of work instead of repeating the full method in every new conversation.

In Codex, project instruction files such as AGENTS.md can shape how the agent works across a repository, while a SKILL.md can describe a specialized capability. Official OpenAI guidance specifically notes that Codex can be sensitive to instructions in skills and files such as AGENTS.md. OpenAI’s Codex model guidance

Claude uses the same practical pattern: project-level instructions establish the shared rules; a skill gives Claude a focused procedure it can use when the task calls for it. The exact installation and discovery mechanics can vary by tool and version. The durable lesson is to write the file so a capable agent can understand when to use it, what to read, what to do, and how to know it is finished.

Do not put every instruction in one giant global file. That creates noise and conflicting rules. Use layers:

AGENTS.md
  Rules for every task in this project
      ↓
SKILL.md
  Repeatable method for one kind of task
      ↓
Task-specific brief
  The goal, files, and constraints for this one assignment

For example, your AGENTS.md might say, “Read the specification before changing product behavior. Do not expose secrets. Run the relevant check before calling work complete.” A SKILL.md for publishing an article might say exactly how to prepare the draft, create artwork, add metadata, test the page, and request approval.

What a good skill contains

A skill should be narrow enough that you can tell when it applies. “Build software” is not a skill. “Turn a recorded interview into a cited ByeBuy article draft” can be a skill. “Inspect a repository for exposed secrets and report findings without changing files” can be a skill.

Here is a complete starter skill. It is intentionally small enough to understand and improve.

---
name: competitor-research
description: Research direct competitors for a product idea and return a sourced comparison.
---

# Competitor Research Skill

## When to use this skill
Use when the project needs a current view of the alternatives a target user
already has. Do not use it for a general market essay or to invent a strategy
without evidence.

## Objective
Identify the most relevant direct competitors, explain the job each helps the
user do, and find evidence-supported gaps for a focused version one.

## Read first
- CONTEXT.md
- SPEC.md
- Any existing customer research in research/

## Required evidence
- Official product site and pricing page
- Public documentation or product pages
- Recent independent reviews where available
- A source link for every material claim

## Process
1. Define the target user's job from CONTEXT.md.
2. Find competitors serving that same job.
3. Record what each product does, who it serves, and how it is priced.
4. Separate observed facts from your interpretation.
5. Identify only gaps supported by the evidence.

## Rules
- Do not call a product weak without evidence.
- Do not invent pricing, features, customers, or reviews.
- Label missing information as unknown.
- Do not change product files; return research only.

## Output
Create research/competitors-[date].md containing:
- a sourced comparison table
- three evidence-supported observations
- open questions that still need customer research

## Verification
Before finishing, check that every competitor has an official URL and every
material claim has a source or is labelled as interpretation.

This is a skill because the next time the project needs competitor research, the agent does not have to reinvent the method. It reads the current project context, follows the same evidence rules, and creates a result in a known place.

Sonariq: a skill library in practice

Sonariq's Astra workflow demonstrates the idea at a larger scale. Its ten PROMPT.md files are specialized research playbooks: research director, company qualitative research, financial-data handoff, model building, independent validation, industry comparison, hypothesis work, critique, final company analysis, and final industry ranking.

Each is narrow. Each expects particular inputs. Each produces a known handoff. Shared standards apply across all of them. That is what turns a collection of prompts into an operating system for research.

The Sonariq pattern also shows an important rule for Codex and Claude: a skill should not erase project memory. The skill tells the agent how to perform a kind of work. CONTEXT.md, SPEC.md, handoffs, and task files tell it what is true about this specific project right now. An agent needs both.

Project memory: what is true nowAgentSkill: how to do this jobTask brief: what to do todayChecked result and updated memory

When should you create a skill?

Create one after you have done a job well at least once and expect to do it again. First, work through the task in a normal chat. Notice the information you repeatedly provide, the mistakes you repeatedly correct, and the checks that distinguish a useful result from a weak one. Those become the sections of the skill.

Do not create a skill just because a task has a name. A skill earns its place when it reduces repeated explanation and produces more consistent work.

Good early skills for a new builder include:

• research a competitor set
• turn a voice note into a structured article draft
• review a pull request against a specification
• prepare a page for publication
• check a project for exposed secrets
• summarize a customer interview without inventing findings

Write a reusable prompt file

Create prompts/competitor-research.md for a product idea. Use this starting point:

# Competitor Research

## Objective
Find the most relevant alternatives to [product idea] and identify
the gap our first version can own.

## Audience
[Who is the product for?]

## Research questions
1. What job does each competitor help the user do?
2. What do users praise or complain about?
3. What is missing, confusing, expensive, or overbuilt?

## Evidence
Use the company website, product pages, pricing, public reviews,
and recent independent coverage. Link every source.

## Deliverable
Create a comparison table, then recommend one focused version-one
opportunity. Label assumptions clearly.

Give it to an AI and review the result. Then improve the file. Did it research the wrong competitors? Add selection criteria. Did it give generic conclusions? Ask for evidence and quotes. Did it ignore your intended user? Put the user near the top.

Check your understanding

1. What information turns a vague request into a usable instruction? 2. Why is a prompt file easier to improve than a one-off chat message? 3. What would you add if an AI gave you an answer with no evidence? 4. Which recurring job in your work deserves its own prompt file?