writing-skills · pedronauck — Claude Code skill: what it does, how to install
Walks the agent through writing, refactoring and debugging skills, and through finding out why a reference file never loaded.
npx skills add pedronauck/skills --skill writing-skills -a claude-codeWhat writing-skills 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.
What it helps with
- 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 for the agent
- 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-skillsskill withscripts/validate-metadata.py
How to install writing-skills
1Skills CLI (Vercel)
npx skills add pedronauck/skills --skill writing-skills -a claude-code2Manually: put the files in place
~/.claude/skills/writing-skills/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/writing-skills/
1Skills CLI (Vercel)
npx skills add pedronauck/skills --skill writing-skills -a codex2Manually: put the files in place
.agents/skills/writing-skills/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add pedronauck/skills --skill writing-skills -a cursor2Manually: put the files in place
.cursor/skills/writing-skills/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install pedronauck/skills writing-skills2Manually: put the files in place
.github/skills/writing-skills/SKILL.md1Skills CLI (Vercel)
npx skills add pedronauck/skills --skill writing-skills -a gemini-cli2Platform CLI
gemini skills install https://github.com/pedronauck/skills --path skills/mine/writing-skillsManually: put the files in place
.devin/skills/writing-skills/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add pedronauck/skills --skill writing-skills -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about writing-skills
How do I install writing-skills in Claude?
Run npx skills add pedronauck/skills --skill writing-skills -a claude-code. The file lands at ~/.claude/skills/writing-skills/SKILL.md.
What does writing-skills do?
It guides the agent through creating, refactoring and debugging skills: scope, the minimum contract in SKILL.md, links to references. It also diagnoses cases where a needed file did not load.
Does it cover AGENTS.md and README files?
No. The author points to writing-agents-md for AGENTS.md and CLAUDE.md, and general docs and READMEs are outside this skill's scope.
Similar skills
All skills for Agent setup: memory, context, orchestration →writing-skills by other authors comes first.
