Write your Real Skills
These are the areas where you want a model to slow down, show work, and keep you in the loop.
The personal file for working with models
No more making experts babysit their strengths.
skillissue.md is a tiny Markdown file that tells a model two things before work starts: what you want to stay involved in and what you want it to own without bothering you.
Real Skills
Loop me in. Ask for confirmation. Show me the work.
Skill Issues
Handle it autonomously. Do not ping me unless blocked.
---
name: "Andre"
version: "1.0"
updated: "2026-03-23"
---
# Real Skills
- Product strategy -> loop me in early, I want to steer direction
- Writing voice -> show me final wording before it goes out
# Skill Issues
- CSS edge cases -> just fix them
- Calendar wrangling -> handle scheduling without involving me
# Preferences
- Tone: sharp, clear, a little too online
- Escalate only when: money, brand, or blockers are involvedHow it works
One file. Three sections. Much less nonsense.
Confess your Skill Issues
These are the things you want handled autonomously because you would genuinely rather not deal with them.
Hand the file to the model
Put it in your home folder, repo, docs, or paste it into custom instructions so the model reads your rules first.
Project Handoff
Tell your project instructions where to find the user map.
If a project already uses AGENTS.md, add a short note telling the
agent to read skillissue.md to understand the user's competence zones:
where to loop them in and where to just handle it.
Read `skillissue.md` before starting work to understand the user's competence zones:
- Real Skills: loop the user in, ask for confirmation, and show work
- Skill Issues: handle autonomously unless blockedGenerator
Build your `skillissue.md` in the browser.
Fill the form, steal a preset, tweak the details, and copy the Markdown when it looks right.
Spec
A lightweight format with just enough structure.
File name
Use skillissue.md.
Frontmatter
Optional YAML frontmatter with
name, version, and updated.
Canonical sections
Use # Real Skills, # Skill Issues, and
# Preferences.
Real Skills
The model should loop you in, ask for confirmation, and keep you involved in these areas.
Skill Issues
The model should take over and handle these areas without bothering you unless it is blocked.
Preferences
Use this section for tone, escalation rules, review thresholds, and output formatting.
Examples
Steal a format. Tell the truth. Ship a better workflow.
Developer
Keeps control over architecture and code review taste. Delegates CSS, release notes, and dependency cleanup.
Founder
Stays involved in messaging and big bets. Hands off spreadsheet cleanup, vendor compare tables, and scheduling chaos.
Creator
Owns voice, taste, and final cuts. Delegates captions, metadata, repetitive outreach, and admin sludge.
FAQ
Short answers for the obvious questions.
Where should I put it?
Anywhere the model will see it before work starts: home folder, repo root, docs folder, gist, or pasted directly into setup instructions.
Is frontmatter required?
No. It is useful metadata, not the soul of the format. The section headings matter more than the extra keys.
Will every model support it?
Not automatically. This is a portable convention. You still need to point the model at the file or paste it into the context.
How detailed should entries be?
Enough to change behavior. Short topic plus a clear instruction is usually perfect.