markskill is a Markdown skill for AI agents and assistants working on code and product design. It helps them decide what to change, keep what works, and tie each result to the checks that actually ran.
The framework overview summarizes its scope and components.
Any AI agent or assistant that can read Markdown instructions can use it. Hosts that support the Agent Skills convention can load SKILL.md and its references directly; elsewhere, provide those files as instructions. It also works as a review guide for a human.
- Code: Trace the behavior to its owner and fix it without weakening safeguards or adding unnecessary complexity.
- Design: Work from real content and the existing product to improve hierarchy, copy, and interaction.
- Review: Prioritize concrete problems, make scoped changes, and report what was actually verified.
The claim is "everything the agent builds and ships." Check it against the files instead of trusting this README:
| claim | enforced by |
|---|---|
| No fluff in copy | references/writing-and-copy.md — semantic redundancy pass, pattern clusters, weak vocabulary |
| Nothing invented | SKILL.md priorities — fabricated claims, invented metrics, testimonials, and outcomes are P0 failures |
| Looks good, not decorated | references/visual-and-interaction.md — tell catalog, emphasis rules, squint test |
| Fits your product, not a template | references/design-restraint.md — grounding in real content and tokens, one committed direction |
| Survives real use | references/design-restraint.md — keyboard, focus, states, zoom, reduced motion |
| Honest about what was verified | references/evidence-and-testing.md — labeled evidence; never claim a render or test that did not happen |
| Iterates without thrashing | SKILL.md fast iteration mode, decision ledger, feedback handling in references/promotional-assets-and-feedback.md |
| Protects accumulated context | direct execution for context-heavy or tightly coordinated work; evidence-backed delegation only for bounded, independent tasks |
| Builds only what earns its keep | references/code-restraint.md — comprehension-first ownership, implementation ladder, dependency gate, safety floor, regression evidence |
With Node.js installed, run this in your terminal and choose the agents you use:
npx skills add thedevmark/markskill -gThis installs markskill for use across projects. Leave off -g to install it only in the current project. The installer supports Codex, Claude Code, and other agent hosts; select the targets it offers. Run npx skills update markskill later to fetch updates.
Prefer a manual install? Clone this repository into your agent's skills directory, such as ~/.codex/skills/markskill or ~/.claude/skills/markskill. If your agent has no skill loader, give it SKILL.md and the relevant reference files as context.
Ask your agent, in plain language:
- "Use markskill to critique the pricing page."
- "Revise the empty states on the dashboard. Distill, don't redesign."
- "Audit this store screenshot set for slop before I ship it."
- "Simplify this diff without moving the behavior or deleting its guards."
- "Fast iteration: make this one change, check the affected behavior, and report."
The skill also applies to over-engineering, YAGNI, dependency choice, refactoring, polish, hierarchy, taste, density, clarify, distill, harden, quieter, or bolder. A critique names the few highest-value findings and exact corrections. A revision reports what changed, what was preserved, and what was actually verified.
| file | job |
|---|---|
SKILL.md |
Shared rules, path routing, fast iteration, and reporting |
references/design-restraint.md |
Design modes and workflow for product surfaces |
references/writing-and-copy.md |
Copy rules, pattern-cluster table, editing tests, example corrections |
references/visual-and-interaction.md |
Visual tell catalog and verification matrix |
references/evidence-and-testing.md |
Evidence labeling and audit method |
references/promotional-assets-and-feedback.md |
Store art, thumbnails, social graphics, iterative feedback handling |
references/code-restraint.md |
Implementation ladder, root-cause ownership, dependency restraint, safety floor, and code-review method |
agents/openai.yaml |
Interface metadata for OpenAI-compatible agent hosts |
MIT