# Capstone Project Course: [Markdown](https://www.devtutorials.ai/learn/markdown) · Section: AI-Native Markdown Source: https://www.devtutorials.ai/learn/markdown/ai-native/capstone > 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. ## 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: | File | What it is for | Lesson | |---|---|---| | `README.md` | what the project is, for people | Docs as Code | | `AGENTS.md` | always-on rules for AI agents | AGENTS.md Files | | `CLAUDE.md`, `.cursor/rules/*.mdc` | thin tool-specific files | AGENTS.md Files | | `.claude/skills//SKILL.md` | one on-demand skill | Skills and Subagents | | `.claude/agents/code-reviewer.md` | a reviewer subagent | Skills and Subagents | | `specs/*.md`, `docs/plans/`, `docs/adr/` | a spec, a plan and a decision record | Specs and Plans | | `docs/index.md`, `llms.txt` | the docs start page, and the map for AI tools | LLM-Friendly Docs | | `.markdownlint.jsonc` | lint settings for every Markdown file | Docs as Code | **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. ```md runnable file="README.md" title="Audit your README" # Paste your README here Replace this text with your project's README, then open the Checks and Outline tabs. ``` ```md runnable file="AGENTS.md" title="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`. Whatever you paste stays in this page. Nothing is uploaded, saved or sent anywhere. Reload the page and it is gone. ## 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. ````md runnable clean file="README.md" title="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 . ## 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. ```md runnable clean file="CLAUDE.md" title="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. ```md runnable clean file=".claude/skills/refund-check/SKILL.md" probes="Why is my refund late?|A customer wants a refund for order A-1042|When will my order ship?|Track order A-1042" title="Skill template" dialect="docs" --- 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. The skill's folder name must match its `name`. If you rename the skill, rename the folder too, or the SKL003 check fails, and so will tools that follow the Agent Skills spec. ## 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. ```md runnable clean file="specs/refund-export.md" title="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. ```md runnable clean file="llms.txt" title="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: ```bash npx markdownlint-cli2 ``` `markdownlint-cli2` is the command-line runner for markdownlint. It reads `.markdownlint.jsonc` for the built-in rules and `.markdownlint-cli2.jsonc` for the custom ones. Add the command to your CI, so a pull request that breaks a rule fails before review. ## 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 | Symptom | Cause | Fix | |---|---|---| | The kit's files still talk about order-support | The templates were copied as they are | Replace every example with your own project's facts | | Claude Code ignores `AGENTS.md` | The repo also has a `CLAUDE.md` without the import | Keep `@AGENTS.md` as the first line of `CLAUDE.md` | | The skill is never used | Its folder was renamed, or its description was cut down | Keep the folder name equal to `name`; keep the "Use when" sentence | | `llms.txt` lists the wrong pages | It was written once and never updated | Rerun `scripts/llms-txt.mjs` whenever the docs change | | markdownlint reports hundreds of problems at once | It was turned on for an old repo all at once | Fix one rule at a time, or turn rules on one by one | ## 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](https://github.com/DavidAnson/markdownlint-cli2): run markdownlint on the command line and in CI. - [AGENTS.md](https://agents.md), [Agent Skills](https://agentskills.io/specification) and [llms.txt](https://llmstxt.org): the three open formats in the kit. - Next courses on this site: **Prompt Engineering**, **Harness Engineering**, **Agent Skills** and **Intent Engineering**.