# writing-skills

Walks the agent through writing, refactoring and debugging skills, and through finding out why a reference file never loaded.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode · 314 installs · ★ 643
- Author: Pedro Nauck
- License: not stated · policy=link-only · description only; the file stays with the author
- Source: https://github.com/pedronauck/skills/tree/HEAD/skills/mine/writing-skills/SKILL.md
- Updated: 2026-10-20
- HTML: https://affpapa.org/en/nevibecode/skills/pedro-nauck-writing-skills

## What it does

This skill hands the agent a procedure for working on skills themselves: how to pick the scope, what stays in `SKILL.md`, what moves into linked references. Author is Pedro Nauck, repository `pedronauck/skills`. The doctrine is adapted from `writing-great-skills` (mattpocock/skills).

Inside is a step-by-step pass over creating and revising: identify the outcome, the owning files and the known failure, keep the minimum common contract in `SKILL.md`, push branch-specific material into links that carry a condition. A separate branch covers loading diagnosis. When a reference was missed, it separates a bad trigger from an inaccessible path, a conflicting rule, stale content and plain model error. For a new package it points at `references/authoring-procedure.md`; `assets/SKILL.template.md` is an optional skeleton.

There is a metadata check: `python3 <writing-skills-dir>/scripts/validate-metadata.py --name "[name]" --description "[description]"`. It only reads. For a small prose edit a static review is enough, but the skill is explicit that you should not claim measured improvement without comparative runs on the same tasks. It also stays out of `AGENTS.md` and `CLAUDE.md` — those belong to `writing-agents-md` — and out of general docs and READMEs. Install runs through `npx skills add` or `gh skill install`, depending on the platform.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add pedronauck/skills --skill writing-skills -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/writing-skills/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/writing-skills/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add pedronauck/skills --skill writing-skills -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/writing-skills/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add pedronauck/skills --skill writing-skills -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/writing-skills/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install pedronauck/skills writing-skills
```

2. **Manually: put the files in place**
- File: `.github/skills/writing-skills/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add pedronauck/skills --skill writing-skills -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/pedronauck/skills --path skills/mine/writing-skills
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/writing-skills/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add pedronauck/skills --skill writing-skills -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/pedronauck/skills/tree/HEAD/skills/mine/writing-skills/SKILL.md

## When to use it
- write a new skill that fires on the right trigger
- find out why a skill's reference file never loaded
- strip generic advice and duplicated rules out of `SKILL.md`
- separate shared guidance from repository-specific policy
- validate skill metadata before publishing

## Example prompts
- Help me write a skill that builds a changelog from commits, start with `SKILL.md`
- My skill doesn't pick up `references/checklist.md` — work out why
- Validate the metadata for the `writing-skills` skill with `scripts/validate-metadata.py`

## Similar
- [writing-principles](https://affpapa.org/en/nevibecode/skills/writing-principles.md) — skill · 1000 installs
- [h3-prompt-writing](https://affpapa.org/en/nevibecode/skills/h3-prompt-writing.md) — skill · 11600 installs
- [writing-plans](https://affpapa.org/en/nevibecode/skills/writing-plans.md) — skill · 282859 installs
- [writing-runbooks](https://affpapa.org/en/nevibecode/skills/writing-runbooks.md) — skill · 18100 installs
- [changelog-writing](https://affpapa.org/en/nevibecode/skills/changelog-writing.md) — skill · 10300 installs
- [om-spec-writing](https://affpapa.org/en/nevibecode/skills/om-spec-writing.md) — skill · 2900 installs

## Other versions with the same name
- [writing-skills · obra](https://affpapa.org/en/nevibecode/skills/writing-skills.md) — 217894 installs

From the same set: [pedronauck/skills](https://affpapa.org/en/nevibecode/by/pedronauck/skills.md) — 6 cards

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md