Markdown Capstone Project

By the Syncfusion DevTutorials team · Last updated October 19, 2026

Build a Markdown kit for your own repo: README, AGENTS.md and tool files, a skill and a subagent, a spec, plan and ADR, docs and llms.txt, and lint settings. Audit your existing files, pass the graded checks and download the kit as a zip.

What you will learn

• Audit an existing README and AGENTS.md
• Adapt each kit template to your own project
• Pass the graded checks for README, AGENTS.md, a skill and a spec
• Download the full kit as a zip
• Plan how to adopt the kit in a real repo

One Kit for Your Repo

You have now met every Markdown file that people, renderers and AI agents read in a modern repo. In this capstone, you put them together into one Markdown kit for your own project, check each file, and download the whole kit as a zip.

The kit has the files this course taught:

In simple words: the kit is a set of starter files. You change them to fit your project, check them here, and copy them into your repo.

TL;DR

• Build the kit one file at a time, starting with README.md and AGENTS.md.
• Each file has its own checks, from the lessons that taught it.
• New repo: download the full kit and edit it. Existing repo: paste your current files into the audit boxes first.
• The exercises check the four files that matter most. The kit at the end holds all of them.
• Nothing you paste or write here leaves your browser. The zip is built in the page.

Two Ways to Start

A New Repo

Start from the templates in this lesson. They are written for the order-support project used throughout the course. Replace its details with yours: the name, the commands, the conventions, the docs addresses.

An Existing Repo

Most projects already have a README, and some have an AGENTS.md. Before you write anything new, audit what you have. Paste your current files into the boxes below. The Checks tab lists every problem the course's rules can find.

Audit your README

# Paste your README here

Replace this text with your project's README, then open the Checks and Outline tabs.

Audit your AGENTS.md

# Paste your AGENTS.md here

Replace this text with your project's AGENTS.md, or delete it and start from the template below.

Look at three things: the Checks tab for rule problems, the Outline tab for headings that name their topics, and the Agent view for the size of your AGENTS.md.

Step 1: The README

The README answers the first five questions: what it is, why use it, how to install it, how to use it, and where to get help. Write it for a person who has never seen the project.

README template

# Order Support

Order Support answers customer questions about orders, refunds and shipping.

## Why use it

Support staff find the refund and shipping rules in one place, and the rules match the code.

## Install

```bash
npm ci
```

## Usage

```bash
npm run dev
```

Then open <http://localhost:3000>.

## Get help

Read the [docs](docs/index.md) or open an issue.

Step 2: AGENTS.md and the Tool Files

AGENTS.md holds only what the code cannot say: commands, hidden conventions, gotchas, and the checks to run before finishing. Keep it well under 150 lines.

Then add thin files for the tools your team uses. CLAUDE.md imports AGENTS.md with one line. A Cursor rule covers one folder.

CLAUDE.md shim

@AGENTS.md

## Claude Code only

- Use plan mode for any change to `src/refunds/`.

If your team uses only one tool, you only need that tool's file. If you use none, AGENTS.md alone is the neutral choice.

Step 3: One Skill and One Subagent

Pick one task your team repeats, which only matters some of the time. That is your first skill. Write its description so it is picked for that task and skipped for others.

Skill template

---
name: refund-check
description: "Checks a refund request against the refund policy: the 30-day window, the approval limit and damaged items. Use when a refund is requested or late, or when someone wants money back for a damaged parcel. Do not use for shipping, delivery dates or tracking."
---

# Refund check

## Steps

1. Find the order by its number or the customer's email.
2. Check the refund window: 30 days from delivery. After that, offer a voucher.
3. If the amount is over ₹5,000, ask for a manager's approval.
4. If the item is damaged, ask for a photo before you refund.

## Output

Reply with one line: **approve**, **voucher**, **needs approval** or **needs photo**, then the reason.

Open the Agent view: two refund prompts picked, two shipping prompts skipped. The kit also includes a reviewer subagent, ready to adapt.

Step 4: A Spec, a Plan and a Decision Record

Take the next feature on your list and write its spec: goal, non-goals, requirements and checkable acceptance criteria. The kit adds a plan template and a first decision record.

Spec template

# Refund export

## Goal

Support leads need last month's refunds in a spreadsheet for the monthly finance report.

## Non-goals

- No PDF export.
- No changes to the refunds page layout.

## Requirements

1. Add a **Download CSV** button to the refunds page.
2. The CSV has the columns `order_id`, `refund_date`, `amount_inr` and `reason`.

## Acceptance criteria

- `GET /refunds/export.csv?month=2026-09` returns status 200 and a header row.
- The file has exactly one row for each refund in the chosen month.
- For 5,000 refunds, the download starts in under 3 seconds.

## Open questions

None.

Step 5: Docs for People and AI Tools

Give the docs a start page that links to every page, with headings that name their topics. Then add llms.txt, the map for AI tools. The kit includes a small script, scripts/llms-txt.mjs, that rebuilds llms.txt from your docs/ folder.

llms.txt template

# Order Support

> Order Support answers customer questions about orders, refunds and shipping. These docs are for support staff and the AI tools that help them.

## Docs

- [Docs start page](https://docs.example.com/index.md): every page, grouped by topic
- [Refund policy](https://docs.example.com/refunds.md): refund window, damaged items, approval limit and refund times

## Optional

- [Decision records](https://docs.example.com/adr/0001-record-decisions.md): why the code is the way it is

Step 6: Lint Settings

The kit's .markdownlint.jsonc turns on markdownlint's rules for every Markdown file, turns off the line-length rule (because you write one sentence per line), and allows the few HTML tags this course uses on purpose.

The kit also ships the course's own checks (AGT, SKL, SUB, SPC, LLM and STY) as markdownlint custom rules, in .markdownlint-rules/ai-native-rules.cjs. The file .markdownlint-cli2.jsonc switches them on. Run one command in your repo, and every Markdown file gets the same checks you used in this course:

npx markdownlint-cli2

Graded Exercises

Each exercise checks one of the four most important files, with the same rules the lessons used. Start from the template, change it to your project, and press Check.

Download Your Kit

Answer the three questions first: your project name, install command and test command fill in every file. The files and paths follow the tool and role you chose at the start of the course (change them in the profile box). You get every file from this lesson, plus a plan template, a first ADR, a docs start page, the llms.txt script and an optional README checklist. Pick a file to edit it. The checks run as you type. When every file passes, download the kit and copy it into your repo.

After You Copy the Kit

1. Replace the order-support details with your project's: names, commands, conventions and addresses.
2. Delete the files you do not need. If your team uses one tool, keep only that tool's files.
3. Run npx markdownlint-cli2 "**/*.md" once, and fix what it reports.
4. Ask your coding agent to read AGENTS.md and summarise the rules back to you. If the summary is wrong, the file is unclear.
5. Review changes to AGENTS.md, skills and specs like code. They change how every future agent session behaves.

Common mistakes

What to Remember

• Every Markdown file has three readers: a person, a renderer and an AI agent.
• README.md is for people. AGENTS.md is for agents, and holds only what the code cannot say.
• Skills hold task-only rules, and are found by their descriptions.
• Specs say what to build, what not to build and how to check it.
• llms.txt and well-headed pages make your docs findable by AI tools.
• A linter keeps every file in the same shape, without anyone having to remember the rules.
• Review these files like code: they are instructions, not just documentation.

Further Reading

• markdownlint-cli2: run markdownlint on the command line and in CI.
• AGENTS.md, Agent Skills and llms.txt: the three open formats in the kit.
• Next courses on this site: Prompt Engineering, Harness Engineering, Agent Skills and Intent Engineering.