# skill-writing-guide

skill-writing-guide guides the creation and refinement of Claude Code skills. Turns repetitive chat workflows into reusable, properly structured instruction files.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf (Devin Desktop), Claude.ai · ★ 165 repo stars
- Author: aspi6246
- License: not stated · policy=link-only · description only; the file stays with the author
- Source: https://github.com/aspi6246/Claude-Code-Skills-for-Academics/tree/HEAD/skill-writing-guide/SKILL.md
- Updated: 2026-08-21
- Security check: automated, 2026-11-16 (text) — no signs of malicious code found.
- HTML: https://affpapa.org/en/nevibecode/skills/skill-writing-guide

## What it does

This skill acts as an authoring reference for Claude Code workflows. It triggers whenever you ask the agent to build, polish, or preserve an interaction pattern as a permanent capability. The guide outlines the required directory structure, centering on a kebab-case folder containing a `SKILL.md` file with YAML metadata.

The core focus is drafting reliable descriptions. Because agents often fail to invoke vague skills, the text teaches you to include explicit target tool names and edge-case activation phrases. It emphasizes negative constraints and concrete code samples over high-level advice.

When a `SKILL.md` exceeds roughly 200 lines, the instructions mandate moving extra documentation into a dedicated `references/` subfolder. Writing workflows and code review processes must also stay separated into distinct skills.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add aspi6246/Claude-Code-Skills-for-Academics --skill skill-writing-guide -a claude-code
```

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

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add aspi6246/Claude-Code-Skills-for-Academics --skill skill-writing-guide -a codex
```

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

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add aspi6246/Claude-Code-Skills-for-Academics --skill skill-writing-guide -a cursor
```

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

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install aspi6246/Claude-Code-Skills-for-Academics skill-writing-guide
```

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

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add aspi6246/Claude-Code-Skills-for-Academics --skill skill-writing-guide -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/aspi6246/Claude-Code-Skills-for-Academics --path skill-writing-guide
```

### Windsurf (Devin Desktop)

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

### 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/aspi6246/Claude-Code-Skills-for-Academics/tree/HEAD/skill-writing-guide/SKILL.md

## When to use it
- build a valid `SKILL.md` file with matching YAML frontmatter
- draft explicit descriptions that trigger reliably during agent sessions
- turn recurring corrections into strict negative constraints
- split oversized instruction files into modular subdirectories

## Example prompts
- Turn this conversation workflow into a reusable skill
- Make this a skill for panel regression analysis
- Help me improve the description and structure of my custom skill

## Similar
- [writing-skills](https://affpapa.org/en/nevibecode/skills/pedro-nauck-writing-skills.md) — skill · 338 installs
- [writing-agents-md](https://affpapa.org/en/nevibecode/skills/writing-agents-md.md) — skill · 305 installs
- [writing-principles](https://affpapa.org/en/nevibecode/skills/writing-principles.md) — skill · 1200 installs
- [om-spec-writing](https://affpapa.org/en/nevibecode/skills/om-spec-writing.md) — skill · 3900 installs
- [h3-prompt-writing](https://affpapa.org/en/nevibecode/skills/h3-prompt-writing.md) — skill · 13200 installs
- [writing-staffing](https://affpapa.org/en/nevibecode/skills/writing-staffing.md) — skill · 787 installs

From the same set: [aspi6246/claude-code-skills-for-academics](https://affpapa.org/en/nevibecode/by/aspi6246/claude-code-skills-for-academics.md) — 17 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
