Skip to main content
skill CX Codex

write-skill — Claude Code skill: what it does, how to install

write-skill — a Claude Code skill that creates and edits agent documents with behavioral verification. Activated when writing system prompts, CLAUDE.md, AGENTS.md, or repeating agent corrections.

MIT 1,000 installs ★ 10 updated 2026-10-16

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add pwguler/skills --skill write-skill -a claude-code
Open on GitHub

What write-skill does

Writing instructions for agents follows a test-first development loop applied to text. The baseline scenario runs on an agent without the target document to record exact failures. Then the minimum text correcting those failures is written and verified in a rerun.

Repeated user corrections turn into structural lessons at the highest holding level. The process skips one-off tasks or cases where a linter or hook handles the rule enforcement.

To use it in Claude Code, run npx skills add pwguler/skills --skill write-skill -a claude-code.

What it helps with

  • create a system prompt for an AI agent
  • verify agent behavior before and after document updates
  • encode repeated agent mistakes into structural lessons
  • write minimal text to fix specific agent failures

Example prompts for the agent

  • write rules for AGENTS.md using write-skill
  • verify agent behavior against a scenario with write-skill
  • fix the agent mistake by encoding the lesson in structure

How to install write-skill

1Skills CLI (Vercel)

npx skills add pwguler/skills --skill write-skill -a claude-code

2Manually: put the files in place

~/.claude/skills/write-skill/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/write-skill/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about write-skill

How to install write-skill in Claude Code?

Run npx skills add pwguler/skills --skill write-skill -a claude-code and check ~/.claude/skills/write-skill/SKILL.md.

What does write-skill do?

It helps create and edit agent documents by running baseline scenarios and verifying behavioral changes.

When should you use this skill?

Use it before writing or editing skills, AGENTS.md, CLAUDE.md, or system prompts, and when the user corrects the same agent mistake twice.

Source text

SKILL.md · MIT
---
name: write-skill
description: Create or edit a document that an agent reads, and prove that it changes behavior. Put a lesson that agents keep learning again into structure. Read this skill before you write or edit a skill, AGENTS.md, CLAUDE.md, a system prompt, or other text for agents. Use it to verify such a document before it ships. Use it also when the user corrects the same agent mistake a second time.
---

Writing for agents is test-first development, applied to text. The same loop ships every document that an agent reads: skills, AGENTS.md, CLAUDE.md, and system prompts.

1. Run the baseline first. Run the scenario that the document targets on an agent WITHOUT the document. Record exactly how it fails, or what excuse it gives. Run the baseline in a fresh subagent that loads no skills and no context files, such as `AGENTS.md`. It keeps the base system prompt of your agent. When your agent cannot start such a subagent, use a new session without skills and context files. When you observe no failure, the document has nothing to teach.
2. Write the minimum text that fixes those specific failures. Do not write a manual. Write the shortest process that changes the behavior.
3. Run the scenario again with the document loaded. It passes, or the document is wrong.
4. Close loopholes. When a new run shows a new excuse, block it in the text, and verify again.

Rules:

- An eval script changes the mechanics, not the loop. When one exists, it runs the baseline and the second run.
- A correction that the user makes a second time is a lesson that did not hold. Read [encode lessons in structure](references/encode-lessons-in-structure.md). Fix its class at the highest level that holds: a mechanism before any text. Only what no mechanism can hold goes through steps 1 to 4.
- When the document is a skill in this repo, follow the [conventions for skills in this repo](references/conventions.md).
- Skip this skill for work done once, or when standard practice is already well documented. Skip it also when a linter or hook could enforce the rule. In that case, build the linter or hook instead, as [encode lessons in structure](references/encode-lessons-in-structure.md) says.

© pwguler · MIT · pwguler/skills

Similar skills

All skills for Agent setup: memory, context, orchestration →

From the same set15

The whole set →
parallel This Claude Code skill runs independent tasks through subagents in parallel. It activates only when asked to parallelize work, compare attempts, or split a job into parts. CX Codex +1 1,000installs core-interview core-interview — a skill for Claude Code that runs an interview loop through decision trees until every branch is settled. CX Codex +1 1,000installs research The research Claude Code skill traces library and API behavior to primary sources, or investigates why code took its current shape. It activates for lookups and questions about the history of a setting or constant. CX Codex +1 1,000installs debug debug is a Claude Code and Cursor skill that traces bug root causes step by step and verifies regression tests. CX Codex +1 1,000installs verify verify — a skill for Claude Code checks claims about completed or fixed work against fresh command output. It runs before a commit or PR, after changes, and before reporting that work is done or tested. CX Codex +1 1,000installs land land is a Claude Code skill that finishes a development branch through merge, PR, keep, or discard. It runs after implementation is complete. CX Codex +1 1,000installs drill A skill for Claude Code interviews the user about a plan or design until its decisions are settled. It runs for new features, unresolved designs, or a request to “drill this.” CX Codex +1 1,000installs implement implement — a skill for Claude Code and Codex that executes settled plans in thin test-driven slices. Runs when prompted to build code from a spec or slice plan. CX Codex +1 1,000installs

Project sponsors

Companies that keep this analytics open