免费 ChatGPT GPTs Claude Code Cursor

writing-skills

Use when creating new skills, editing existing skills, or verifying skills work before deployment

0 次下载 0 次浏览更新于 Oct 31, 2026 v1.0.0

下方技能配置(提示词、变量、安装步骤)保留英文原文。.aiskill 文件直接面向 AI 智能体,统一使用英文以确保跨平台行为一致。

概述

Use when creating new skills, editing existing skills, or verifying skills work before deployment

系统提示词

定义智能体角色、规则与输出格式的指令块。

system-prompt.txt

# Writing Skills

## Overview

**Writing skills IS Test-Driven Development applied to process documentation.**

**Personal skills live in your runtime's skills directory** (`~/.claude/skills/` on Claude Code) — see [codex-tools.md](../using-superpowers/references/codex-tools.md) or [gemini-tools.md](../using-superpowers/references/gemini-tools.md) for the path on those runtimes. Codex, Copilot CLI, and Gemini CLI all also recognize `~/.agents/skills/` as a cross-runtime alias.

You write test cases (pressure scenarios with subagents), watch them fail (baseline behavior), write the skill (documentation), watch tests pass (agents comply), and refactor (close loopholes).

**Core principle:** If you didn't watch an agent fail without the skill, you don't know if the skill teaches the right thing.

**REQUIRED BACKGROUND:** You MUST understand superpowers:test-driven-development before using this skill. That skill defines the fundamental RED-GREEN-REFACTOR cycle. This skill adapts TDD to documentation.

**Official guidance:** For Anthropic's official skill authoring best practices, see references/anthropic-best-practices.md. This document provides additional patterns and guidelines that complement the TDD-focused approach in this skill.

## What is a Skill?

A **skill** is a reference guide for proven techniques, patterns, or tools. Skills help future agents find and apply effective approaches.

**Skills are:** Reusable techniques, patterns, tools, reference guides

**Skills are NOT:** Narratives about how you solved a problem once

## TDD Mapping for Skills

| TDD Concept | Skill Creation |
|-------------|----------------|
| **Test case** | Pressure scenario with subagent |
| **Production code** | Skill document (SKILL.md) |
| **Test fails (RED)** | Agent violates rule without skill (baseline) |
| **Test passes (GREEN)** | Agent complies with skill present |
| **Refactor** | Close loopholes while maintaining compliance |
| **Write test first** | Run baseline scenario BEFORE writing skill |
| **Watch it fail** | Document exact rationalizations agent uses |
| **Minimal code** | Write skill addressing those specific violations |
| **Watch it pass** | Verify agent now complies |
| **Refactor cycle** | Find new rationalizations → plug → re-verify |

The entire skill creation process follows RED-GREEN-REFACTOR.

## When to Create a Skill

**Create when:**
- Technique wasn't intuitively obvious to you
- You'd reference this again across projects
- Pattern applies broadly (not project-specific)
- Others would benefit

**Don't create for:**
- One-off solutions
- Standard practices well-documented elsewhere
- Project-specific conventions (put in your instructions file)
- Mechanical constraints (if it's enforceable with regex/validation, automate it—save documentation for judgment calls)

## Skill Types

### Technique
Concrete method with steps to follow (condition-based-waiting, root-cause-tracing)

### Pattern
Way of thinking about problems (flatten-with-flags, test-invariants)

### Reference
API docs, syntax guides, tool documentation (office docs)

## Directory Structure


```
skills/
  skill-name/
    SKILL.md              # Main reference (required)
    supporting-file.*     # Only if needed
```

**Flat namespace** - all skills in one searchable namespace

**Separate files for:**
1. **Heavy reference** (100+ lines) - API docs, comprehensive syntax
2. **Reusable tools** - Scripts, utilities, templates

**Keep inline:**
- Principles and concepts
- Code patterns (< 50 lines)
- Everything else

## Writing SKILL.md

A skill's `description` says only when to use it: triggering conditions and
symptoms, starting with "Use when...". It never summarizes the skill's
workflow, because an agent that reads a workflow summary follows it instead
of reading the skill.

When you write or change a skill's frontmatter, name or description, or
need to cut its size, read [references/discovery.md](references/discovery.md):
the SKILL.md template, description and keyword guidance, naming, token
budgets, and cross-referencing other skills.

## Flowcharts

When you add or change a flowchart in a skill, read
[references/flowcharts.md](references/flowcharts.md) first: when a flowchart
earns its place, the graphviz conventions, and how to render one.

## Code Examples

**One excellent example beats many mediocre ones**

Choose most relevant language:
- Testing techniques → TypeScript/JavaScript
- System debugging → Shell/Python
- Data processing → Python

**Good example:**
- Complete and runnable
- Well-commented explaining WHY
- From real scenario
- Shows pattern clearly
- Ready to adapt (not generic template)

**Don't:**
- Implement in 5+ languages
- Create fill-in-the-blank templates
- Write contrived examples

You're good at porting - one great example is enough.

## File Organization

### Self-Contained Skill
```
defense-in-depth/
  SKILL.md    # Everything inline
```
When: All content fits, no heavy reference needed

### Skill with Reusable Tool
```
condition-based-waiting/
  SKILL.md    # Overview + patterns
  example.ts  # Working helpers to adapt
```
When: Tool is reusable code, not just narrative

### Skill with Heavy Reference
```
pptx/
  SKILL.md       # Overview + workflows
  pptxgenjs.md   # 600 lines API reference
  ooxml.md       # 500 lines XML structure
  scripts/       # Executable tools
```
When: Reference material too large for inline

Invoke bundled scripts through their interpreter in the prose (`bash scripts/tool.sh`, `node scripts/tool.js`), never by bare path: some harness plugin packagers strip executable bits, and a bare `scripts/tool.sh` fails there with `Permission denied`.

## The Iron Law (Same as TDD)

```
NO SKILL WITHOUT A FAILING TEST FIRST
```

This applies to NEW skills AND EDITS to existing skills.

Write skill before testing? Delete it. Start over.
Edit skill without testing? Same violation.

**No exceptions:**
- Not for "simple additions"
- Not for "just adding a section"
- Not for "documentation updates"
- Don't keep untested changes as "reference"
- Don't "adapt" while running tests
- Delete means delete

**REQUIRED BACKGROUND:** The superpowers:test-driven-development skill explains why this matters. Same principles apply to documentation.

## Testing All Skill Types

Different skill types need different test approaches:

### Discipline-Enforcing Skills (rules/requirements)

**Examples:** TDD, verification-before-completion, designing-before-coding

**Test with:**
- Academic questions: Do they understand the rules?
- Pressure scenarios: Do they comply under stress?
- Multiple pressures combined: time + sunk cost + exhaustion
- Identify rationalizations and add explicit counters

**Success criteria:** Agent follows rule under maximum pressure

### Technique Skills (how-to guides)

**Examples:** condition-based-waiting, root-cause-tracing, defensive-programming

**Test with:**
- Application scenarios: Can they apply the technique correctly?
- Variation scenarios: Do they handle edge cases?
- Missing information tests: Do instructions have gaps?

**Success criteria:** Agent successfully applies technique to new scenario

### Pattern Skills (mental models)

**Examples:** reducing-complexity, information-hiding concepts

**Test with:**
- Recognition scenarios: Do they recognize when pattern applies?
- Application scenarios: Can they use the mental model?
- Counter-examples: Do they know when NOT to apply?

**Success criteria:** Agent correctly identifies when/how to apply pattern

### Reference Skills (documentation/APIs)

**Examples:** API documentation, command references, library guides

**Test with:**
- Retrieval scenarios: Can they find the right information?
- Application scenarios: Can they use what they found correctly?
- Gap testing: Are common use cases covered?

**Success criteria:** Agent finds and correctly applies reference information

## Common Rationalizations for Skipping Testing

| Excuse | Reality |
|--------|---------|
| "Skill is obviously clear" | Clear to you ≠ clear to other agents. Test it. |
| "It's just a reference" | References can have gaps, unclear sections. Test retrieval. |
| "Testing is overkill" | Untested skills have issues. Always. 15 min testing saves hours. |
| "I'll test if problems emerge" | Problems = agents can't use skill. Test BEFORE deploying. |
| "Too tedious to test" | Testing is less tedious than debugging bad skill in production. |
| "I'm confident it's good" | Overconfidence guarantees issues. Test anyway. |
| "Academic review is enough" | Reading ≠ using. Test application scenarios. |
| "No time to test" | Deploying untested skill wastes more time fixing it later. |

**All of these mean: Test before deploying. No exceptions.**

## Match the Form to the Failure

Before writing guidance, classify the baseline failure. The form that bulletproofs one failure type measurably backfires on another.

| Baseline failure | Right form | Wrong form |
|---|---|---|
| Skips/violates a rule under pressure (knows better, does it anyway) | Prohibition + rationalization table + red flags (see references/bulletproofing.md) | Soft guidance ("prefer...", "consider...") |
| Complies, but output has the wrong shape (bloated prompt, buried verdict, restated spec) | Positive recipe or contract: state what the output IS — its parts, in order | Prohibition list ("don't restate", "never narrate") |
| Omits a required element from something they already produce | Structural: REQUIRED field or slot in the template they fill in | Prose reminders near the template |
| Behavior should depend on a condition | Conditional keyed to an observable predicate ("if the brief exists, reference it") | Unconditional rule + exemption clauses |

**Why prohibitions backfire on shaping problems:** under a competing incentive ("make the prompt self-contained"), agents negotiate with "don't X". In head-to-head wording tests on dispatch-prompt guidance, the prohibition arm produced clearly more of the unwanted content than the recipe arm (fully separated distributions), and trended worse than even the no-guidance control — micro-test your own case rather than assuming, but never reach for the prohibition by default. A recipe leaves nothing to negotiate: the output matches the stated shape or it doesn't.

**Rules for whichever form you pick:**
- **No nuance clauses.** "Don't X unless it matters" reopens the negotiation — appending a single nuance clause to a winning recipe degraded it from consistent to noisy in the same wording tests. Express a real exception as its own conditional on an observable predicate.
- **Exemption clauses don't scope.** "This limit doesn't apply to code blocks" still suppresses code blocks. If part of the output must be exempt, restructure so the rule can't reach it.

## Bulletproofing Against Rationalization

When the baseline failure is a discipline failure, read
[references/bulletproofing.md](references/bulletproofing.md) before you write
the guidance: closing loopholes, the spirit-vs-letter line, the
rationalization table, and the red-flags list.

## RED-GREEN-REFACTOR for Skills

Follow the TDD cycle:

### RED: Write Failing Test (Baseline)

Run pressure scenario with subagent WITHOUT the skill. Document exact behavior:
- What choices did they make?
- What rationalizations did they use (verbatim)?
- Which pressures triggered violations?

This is "watch the test fail" - you must see what agents naturally do before writing the skill.

### GREEN: Write Minimal Skill

Write skill that addresses those specific rationalizations. Don't add extra content for hypothetical cases.

Run same scenarios WITH skill. Agent should now comply.

### REFACTOR: Close Loopholes

Agent found new rationalization? Add explicit counter. Re-test until bulletproof.

### Micro-Test Wording Before Full Scenarios

Full pressure-scenario runs are the final gate, but they are slow and expensive per iteration. Verify the wording itself first with micro-tests:

1. **One fresh-context sample per call** — a raw API call, or a single-shot subagent if you don't have API access. System prompt = the realistic context the guidance will live in (the full skill or prompt template, not the guidance in isolation); user message = a task that tempts the failure.
2. **Always include a no-guidance control.** If the control doesn't exhibit the failure, there is nothing to fix — stop, don't author the guidance.
3. **5+ reps per variant.** Single samples lie.
4. **Manually read every flagged match.** Score programmatically if you like, but template echoes and quoted counter-examples masquerade as hits; automated counts alone overstate both failure and success.
5. **Variance is a metric.** When guidance lands, reps converge on the same shape. Five different interpretations across five reps means the wording isn't binding — tighten the form before adding words.

Micro-tests verify wording; they do not replace pressure scenarios for discipline skills.

**Testing methodology:** See [references/testing-skills-with-subagents.md](references/testing-skills-with-subagents.md) for the complete testing methodology:
- How to write pressure scenarios
- Pressure types (time, sunk cost, authority, exhaustion)
- Plugging holes systematically
- Meta-testing techniques

## Anti-Patterns

### ❌ Narrative Example
"In session 2025-10-03, we found empty projectDir caused..."
**Why bad:** Too specific, not reusable

### ❌ Multi-Language Dilution
example-js.js, example-py.py, example-go.go
**Why bad:** Mediocre quality, maintenance burden

### ❌ Code in Flowcharts
```dot
step1 [label="import fs"];
step2 [label="read file"];
```
**Why bad:** Can't copy-paste, hard to read

### ❌ Generic Labels
helper1, helper2, step3, pattern4
**Why bad:** Labels should have semantic meaning

## STOP: Before Moving to Next Skill

**After writing ANY skill, you MUST STOP and complete the deployment process.**

**Do NOT:**
- Create multiple skills in batch without testing each
- Move to next skill before current one is verified
- Skip testing because "batching is more efficient"

**The deployment checklist below is MANDATORY for EACH skill.**

Deploying untested skills = deploying untested code. It's a violation of quality standards.

## Skill Creation Checklist (TDD Adapted)

**IMPORTANT: Create a todo for EACH checklist item below.**

**RED Phase - Write Failing Test:**
- [ ] Create pressure scenarios (3+ combined pressures for discipline skills)
- [ ] Run scenarios WITHOUT skill - document baseline behavior verbatim
- [ ] Identify patterns in rationalizations/failures

**GREEN Phase - Write Minimal Skill:**
- [ ] Name uses only letters, numbers, hyphens (no parentheses/special chars)
- [ ] YAML frontmatter with required `name` and `description` fields (max 1024 chars; see [spec](https://agentskills.io/specification))
- [ ] Description starts with "Use when..." and includes specific triggers/symptoms
- [ ] Description written in third person
- [ ] Keywords throughout for search (errors, symptoms, tools)
- [ ] Clear overview with core principle
- [ ] Address specific baseline failures identified in RED
- [ ] Guidance form matches the failure type (see Match the Form to the Failure)
- [ ] For behavior-shaping guidance: wording micro-tested against a no-guidance control (5+ reps, every flagged match read manually) — N/A for pure reference skills
- [ ] Code inline OR link to separate file
- [ ] One excellent example (not multi-language)
- [ ] Run scenarios WITH skill - verify agents now comply

**REFACTOR Phase - Close Loopholes:**
- [ ] Identify NEW rationalizations from testing
- [ ] Add explicit counters (if discipline skill)
- [ ] Build rationalization table from all test iterations
- [ ] Create red flags list
- [ ] Re-test until bulletproof

**Quality Checks:**
- [ ] Small flowchart only if decision non-obvious
- [ ] Quick reference table
- [ ] Common mistakes section
- [ ] No narrative storytelling
- [ ] Supporting files only for tools or heavy reference

**Deployment:**
- [ ] Commit skill to git and push to your fork (if configured)
- [ ] Consider contributing back via PR (if broadly useful)

## Discovery Workflow

How future agents find your skill:

1. **Encounters problem** ("tests are flaky")
2. **Searches skills** (greps descriptions, browses categories)
3. **Finds SKILL** (description matches)
4. **Scans overview** (is this relevant?)
5. **Reads patterns** (quick reference table)
6. **Loads example** (only when implementing)

**Optimize for this flow** - put searchable terms early and often.

用户提示词模板

填充变量后发送,即可运行该技能: {{variables}}

user-template.txt

变量

名称	必填	说明	示例

完整技能配置

标准 .aiskill 文件,提供 JSON 与 YAML 两种格式。

writing-skills.aiskill (JSON)

{
  "format": "aiskill/v1",
  "skill": {
    "name": "writing-skills",
    "slug": "writing-skills",
    "version": "1.0.0",
    "description": "Use when creating new skills, editing existing skills, or verifying skills work before deployment",
    "category": "Development",
    "tags": [
      "dev-workflow",
      "content"
    ],
    "platforms": [
      "chatgpt",
      "claude-code",
      "cursor"
    ],
    "tested_environment": "Agent Skills convention (SKILL.md) — works with Claude Code, Cursor, ChatGPT/Codex and compatible agents",
    "license": "MIT"
  },
  "prompts": {
    "system": "# Writing Skills\n\n## Overview\n\n**Writing skills IS Test-Driven Development applied to process documentation.**\n\n**Personal skills live in your runtime's skills directory** (`~/.claude/skills/` on Claude Code) — see [codex-tools.md](../using-superpowers/references/codex-tools.md) or [gemini-tools.md](../using-superpowers/references/gemini-tools.md) for the path on those runtimes. Codex, Copilot CLI, and Gemini CLI all also recognize `~/.agents/skills/` as a cross-runtime alias.\n\nYou write test cases (pressure scenarios with subagents), watch them fail (baseline behavior), write the skill (documentation), watch tests pass (agents comply), and refactor (close loopholes).\n\n**Core principle:** If you didn't watch an agent fail without the skill, you don't know if the skill teaches the right thing.\n\n**REQUIRED BACKGROUND:** You MUST understand superpowers:test-driven-development before using this skill. That skill defines the fundamental RED-GREEN-REFACTOR cycle. This skill adapts TDD to documentation.\n\n**Official guidance:** For Anthropic's official skill authoring best practices, see references/anthropic-best-practices.md. This document provides additional patterns and guidelines that complement the TDD-focused approach in this skill.\n\n## What is a Skill?\n\nA **skill** is a reference guide for proven techniques, patterns, or tools. Skills help future agents find and apply effective approaches.\n\n**Skills are:** Reusable techniques, patterns, tools, reference guides\n\n**Skills are NOT:** Narratives about how you solved a problem once\n\n## TDD Mapping for Skills\n\n| TDD Concept | Skill Creation |\n|-------------|----------------|\n| **Test case** | Pressure scenario with subagent |\n| **Production code** | Skill document (SKILL.md) |\n| **Test fails (RED)** | Agent violates rule without skill (baseline) |\n| **Test passes (GREEN)** | Agent complies with skill present |\n| **Refactor** | Close loopholes while maintaining compliance |\n| **Write test first** | Run baseline scenario BEFORE writing skill |\n| **Watch it fail** | Document exact rationalizations agent uses |\n| **Minimal code** | Write skill addressing those specific violations |\n| **Watch it pass** | Verify agent now complies |\n| **Refactor cycle** | Find new rationalizations → plug → re-verify |\n\nThe entire skill creation process follows RED-GREEN-REFACTOR.\n\n## When to Create a Skill\n\n**Create when:**\n- Technique wasn't intuitively obvious to you\n- You'd reference this again across projects\n- Pattern applies broadly (not project-specific)\n- Others would benefit\n\n**Don't create for:**\n- One-off solutions\n- Standard practices well-documented elsewhere\n- Project-specific conventions (put in your instructions file)\n- Mechanical constraints (if it's enforceable with regex/validation, automate it—save documentation for judgment calls)\n\n## Skill Types\n\n### Technique\nConcrete method with steps to follow (condition-based-waiting, root-cause-tracing)\n\n### Pattern\nWay of thinking about problems (flatten-with-flags, test-invariants)\n\n### Reference\nAPI docs, syntax guides, tool documentation (office docs)\n\n## Directory Structure\n\n\n```\nskills/\n  skill-name/\n    SKILL.md              # Main reference (required)\n    supporting-file.*     # Only if needed\n```\n\n**Flat namespace** - all skills in one searchable namespace\n\n**Separate files for:**\n1. **Heavy reference** (100+ lines) - API docs, comprehensive syntax\n2. **Reusable tools** - Scripts, utilities, templates\n\n**Keep inline:**\n- Principles and concepts\n- Code patterns (< 50 lines)\n- Everything else\n\n## Writing SKILL.md\n\nA skill's `description` says only when to use it: triggering conditions and\nsymptoms, starting with \"Use when...\". It never summarizes the skill's\nworkflow, because an agent that reads a workflow summary follows it instead\nof reading the skill.\n\nWhen you write or change a skill's frontmatter, name or description, or\nneed to cut its size, read [references/discovery.md](references/discovery.md):\nthe SKILL.md template, description and keyword guidance, naming, token\nbudgets, and cross-referencing other skills.\n\n## Flowcharts\n\nWhen you add or change a flowchart in a skill, read\n[references/flowcharts.md](references/flowcharts.md) first: when a flowchart\nearns its place, the graphviz conventions, and how to render one.\n\n## Code Examples\n\n**One excellent example beats many mediocre ones**\n\nChoose most relevant language:\n- Testing techniques → TypeScript/JavaScript\n- System debugging → Shell/Python\n- Data processing → Python\n\n**Good example:**\n- Complete and runnable\n- Well-commented explaining WHY\n- From real scenario\n- Shows pattern clearly\n- Ready to adapt (not generic template)\n\n**Don't:**\n- Implement in 5+ languages\n- Create fill-in-the-blank templates\n- Write contrived examples\n\nYou're good at porting - one great example is enough.\n\n## File Organization\n\n### Self-Contained Skill\n```\ndefense-in-depth/\n  SKILL.md    # Everything inline\n```\nWhen: All content fits, no heavy reference needed\n\n### Skill with Reusable Tool\n```\ncondition-based-waiting/\n  SKILL.md    # Overview + patterns\n  example.ts  # Working helpers to adapt\n```\nWhen: Tool is reusable code, not just narrative\n\n### Skill with Heavy Reference\n```\npptx/\n  SKILL.md       # Overview + workflows\n  pptxgenjs.md   # 600 lines API reference\n  ooxml.md       # 500 lines XML structure\n  scripts/       # Executable tools\n```\nWhen: Reference material too large for inline\n\nInvoke bundled scripts through their interpreter in the prose (`bash scripts/tool.sh`, `node scripts/tool.js`), never by bare path: some harness plugin packagers strip executable bits, and a bare `scripts/tool.sh` fails there with `Permission denied`.\n\n## The Iron Law (Same as TDD)\n\n```\nNO SKILL WITHOUT A FAILING TEST FIRST\n```\n\nThis applies to NEW skills AND EDITS to existing skills.\n\nWrite skill before testing? Delete it. Start over.\nEdit skill without testing? Same violation.\n\n**No exceptions:**\n- Not for \"simple additions\"\n- Not for \"just adding a section\"\n- Not for \"documentation updates\"\n- Don't keep untested changes as \"reference\"\n- Don't \"adapt\" while running tests\n- Delete means delete\n\n**REQUIRED BACKGROUND:** The superpowers:test-driven-development skill explains why this matters. Same principles apply to documentation.\n\n## Testing All Skill Types\n\nDifferent skill types need different test approaches:\n\n### Discipline-Enforcing Skills (rules/requirements)\n\n**Examples:** TDD, verification-before-completion, designing-before-coding\n\n**Test with:**\n- Academic questions: Do they understand the rules?\n- Pressure scenarios: Do they comply under stress?\n- Multiple pressures combined: time + sunk cost + exhaustion\n- Identify rationalizations and add explicit counters\n\n**Success criteria:** Agent follows rule under maximum pressure\n\n### Technique Skills (how-to guides)\n\n**Examples:** condition-based-waiting, root-cause-tracing, defensive-programming\n\n**Test with:**\n- Application scenarios: Can they apply the technique correctly?\n- Variation scenarios: Do they handle edge cases?\n- Missing information tests: Do instructions have gaps?\n\n**Success criteria:** Agent successfully applies technique to new scenario\n\n### Pattern Skills (mental models)\n\n**Examples:** reducing-complexity, information-hiding concepts\n\n**Test with:**\n- Recognition scenarios: Do they recognize when pattern applies?\n- Application scenarios: Can they use the mental model?\n- Counter-examples: Do they know when NOT to apply?\n\n**Success criteria:** Agent correctly identifies when/how to apply pattern\n\n### Reference Skills (documentation/APIs)\n\n**Examples:** API documentation, command references, library guides\n\n**Test with:**\n- Retrieval scenarios: Can they find the right information?\n- Application scenarios: Can they use what they found correctly?\n- Gap testing: Are common use cases covered?\n\n**Success criteria:** Agent finds and correctly applies reference information\n\n## Common Rationalizations for Skipping Testing\n\n| Excuse | Reality |\n|--------|---------|\n| \"Skill is obviously clear\" | Clear to you ≠ clear to other agents. Test it. |\n| \"It's just a reference\" | References can have gaps, unclear sections. Test retrieval. |\n| \"Testing is overkill\" | Untested skills have issues. Always. 15 min testing saves hours. |\n| \"I'll test if problems emerge\" | Problems = agents can't use skill. Test BEFORE deploying. |\n| \"Too tedious to test\" | Testing is less tedious than debugging bad skill in production. |\n| \"I'm confident it's good\" | Overconfidence guarantees issues. Test anyway. |\n| \"Academic review is enough\" | Reading ≠ using. Test application scenarios. |\n| \"No time to test\" | Deploying untested skill wastes more time fixing it later. |\n\n**All of these mean: Test before deploying. No exceptions.**\n\n## Match the Form to the Failure\n\nBefore writing guidance, classify the baseline failure. The form that bulletproofs one failure type measurably backfires on another.\n\n| Baseline failure | Right form | Wrong form |\n|---|---|---|\n| Skips/violates a rule under pressure (knows better, does it anyway) | Prohibition + rationalization table + red flags (see references/bulletproofing.md) | Soft guidance (\"prefer...\", \"consider...\") |\n| Complies, but output has the wrong shape (bloated prompt, buried verdict, restated spec) | Positive recipe or contract: state what the output IS — its parts, in order | Prohibition list (\"don't restate\", \"never narrate\") |\n| Omits a required element from something they already produce | Structural: REQUIRED field or slot in the template they fill in | Prose reminders near the template |\n| Behavior should depend on a condition | Conditional keyed to an observable predicate (\"if the brief exists, reference it\") | Unconditional rule + exemption clauses |\n\n**Why prohibitions backfire on shaping problems:** under a competing incentive (\"make the prompt self-contained\"), agents negotiate with \"don't X\". In head-to-head wording tests on dispatch-prompt guidance, the prohibition arm produced clearly more of the unwanted content than the recipe arm (fully separated distributions), and trended worse than even the no-guidance control — micro-test your own case rather than assuming, but never reach for the prohibition by default. A recipe leaves nothing to negotiate: the output matches the stated shape or it doesn't.\n\n**Rules for whichever form you pick:**\n- **No nuance clauses.** \"Don't X unless it matters\" reopens the negotiation — appending a single nuance clause to a winning recipe degraded it from consistent to noisy in the same wording tests. Express a real exception as its own conditional on an observable predicate.\n- **Exemption clauses don't scope.** \"This limit doesn't apply to code blocks\" still suppresses code blocks. If part of the output must be exempt, restructure so the rule can't reach it.\n\n## Bulletproofing Against Rationalization\n\nWhen the baseline failure is a discipline failure, read\n[references/bulletproofing.md](references/bulletproofing.md) before you write\nthe guidance: closing loopholes, the spirit-vs-letter line, the\nrationalization table, and the red-flags list.\n\n## RED-GREEN-REFACTOR for Skills\n\nFollow the TDD cycle:\n\n### RED: Write Failing Test (Baseline)\n\nRun pressure scenario with subagent WITHOUT the skill. Document exact behavior:\n- What choices did they make?\n- What rationalizations did they use (verbatim)?\n- Which pressures triggered violations?\n\nThis is \"watch the test fail\" - you must see what agents naturally do before writing the skill.\n\n### GREEN: Write Minimal Skill\n\nWrite skill that addresses those specific rationalizations. Don't add extra content for hypothetical cases.\n\nRun same scenarios WITH skill. Agent should now comply.\n\n### REFACTOR: Close Loopholes\n\nAgent found new rationalization? Add explicit counter. Re-test until bulletproof.\n\n### Micro-Test Wording Before Full Scenarios\n\nFull pressure-scenario runs are the final gate, but they are slow and expensive per iteration. Verify the wording itself first with micro-tests:\n\n1. **One fresh-context sample per call** — a raw API call, or a single-shot subagent if you don't have API access. System prompt = the realistic context the guidance will live in (the full skill or prompt template, not the guidance in isolation); user message = a task that tempts the failure.\n2. **Always include a no-guidance control.** If the control doesn't exhibit the failure, there is nothing to fix — stop, don't author the guidance.\n3. **5+ reps per variant.** Single samples lie.\n4. **Manually read every flagged match.** Score programmatically if you like, but template echoes and quoted counter-examples masquerade as hits; automated counts alone overstate both failure and success.\n5. **Variance is a metric.** When guidance lands, reps converge on the same shape. Five different interpretations across five reps means the wording isn't binding — tighten the form before adding words.\n\nMicro-tests verify wording; they do not replace pressure scenarios for discipline skills.\n\n**Testing methodology:** See [references/testing-skills-with-subagents.md](references/testing-skills-with-subagents.md) for the complete testing methodology:\n- How to write pressure scenarios\n- Pressure types (time, sunk cost, authority, exhaustion)\n- Plugging holes systematically\n- Meta-testing techniques\n\n## Anti-Patterns\n\n### ❌ Narrative Example\n\"In session 2025-10-03, we found empty projectDir caused...\"\n**Why bad:** Too specific, not reusable\n\n### ❌ Multi-Language Dilution\nexample-js.js, example-py.py, example-go.go\n**Why bad:** Mediocre quality, maintenance burden\n\n### ❌ Code in Flowcharts\n```dot\nstep1 [label=\"import fs\"];\nstep2 [label=\"read file\"];\n```\n**Why bad:** Can't copy-paste, hard to read\n\n### ❌ Generic Labels\nhelper1, helper2, step3, pattern4\n**Why bad:** Labels should have semantic meaning\n\n## STOP: Before Moving to Next Skill\n\n**After writing ANY skill, you MUST STOP and complete the deployment process.**\n\n**Do NOT:**\n- Create multiple skills in batch without testing each\n- Move to next skill before current one is verified\n- Skip testing because \"batching is more efficient\"\n\n**The deployment checklist below is MANDATORY for EACH skill.**\n\nDeploying untested skills = deploying untested code. It's a violation of quality standards.\n\n## Skill Creation Checklist (TDD Adapted)\n\n**IMPORTANT: Create a todo for EACH checklist item below.**\n\n**RED Phase - Write Failing Test:**\n- [ ] Create pressure scenarios (3+ combined pressures for discipline skills)\n- [ ] Run scenarios WITHOUT skill - document baseline behavior verbatim\n- [ ] Identify patterns in rationalizations/failures\n\n**GREEN Phase - Write Minimal Skill:**\n- [ ] Name uses only letters, numbers, hyphens (no parentheses/special chars)\n- [ ] YAML frontmatter with required `name` and `description` fields (max 1024 chars; see [spec](https://agentskills.io/specification))\n- [ ] Description starts with \"Use when...\" and includes specific triggers/symptoms\n- [ ] Description written in third person\n- [ ] Keywords throughout for search (errors, symptoms, tools)\n- [ ] Clear overview with core principle\n- [ ] Address specific baseline failures identified in RED\n- [ ] Guidance form matches the failure type (see Match the Form to the Failure)\n- [ ] For behavior-shaping guidance: wording micro-tested against a no-guidance control (5+ reps, every flagged match read manually) — N/A for pure reference skills\n- [ ] Code inline OR link to separate file\n- [ ] One excellent example (not multi-language)\n- [ ] Run scenarios WITH skill - verify agents now comply\n\n**REFACTOR Phase - Close Loopholes:**\n- [ ] Identify NEW rationalizations from testing\n- [ ] Add explicit counters (if discipline skill)\n- [ ] Build rationalization table from all test iterations\n- [ ] Create red flags list\n- [ ] Re-test until bulletproof\n\n**Quality Checks:**\n- [ ] Small flowchart only if decision non-obvious\n- [ ] Quick reference table\n- [ ] Common mistakes section\n- [ ] No narrative storytelling\n- [ ] Supporting files only for tools or heavy reference\n\n**Deployment:**\n- [ ] Commit skill to git and push to your fork (if configured)\n- [ ] Consider contributing back via PR (if broadly useful)\n\n## Discovery Workflow\n\nHow future agents find your skill:\n\n1. **Encounters problem** (\"tests are flaky\")\n2. **Searches skills** (greps descriptions, browses categories)\n3. **Finds SKILL** (description matches)\n4. **Scans overview** (is this relevant?)\n5. **Reads patterns** (quick reference table)\n6. **Loads example** (only when implementing)\n\n**Optimize for this flow** - put searchable terms early and often.",
    "user_template": ""
  },
  "variables": [],
  "install": {
    "steps": [
      {
        "title": "Download & unzip",
        "detail": "Download the .zip package from SkillVault and unzip it. The writing-skills/ folder contains SKILL.md plus any companion scripts, references and assets."
      },
      {
        "title": "Copy into your agent skills directory",
        "detail": "Move the folder into your agent's skills directory — e.g. ~/.claude/skills/ (Claude Code), .codex/skills/, .cursor/skills/ or your project's .claude/skills/ folder — then restart or reload the session."
      },
      {
        "title": "Use it",
        "detail": "Describe the task in natural language; the agent loads the skill automatically when the request matches the skill description."
      }
    ]
  },
  "usage": {
    "steps": []
  },
  "metadata": {
    "author": "SkillVault",
    "source": "https://skillvault.top/skills/writing-skills",
    "exported_at": "2026-11-03T07:45:18.545Z"
  }
}

writing-skills.aiskill (YAML)

format: aiskill/v1
skill:
  name: writing-skills
  slug: writing-skills
  version: 1.0.0
  description: >-
    Use when creating new skills, editing existing skills, or verifying skills work before
    deployment
  category: Development
  tags:
    - dev-workflow
    - content
  platforms:
    - chatgpt
    - claude-code
    - cursor
  tested_environment: >-
    Agent Skills convention (SKILL.md) — works with Claude Code, Cursor, ChatGPT/Codex and
    compatible agents
  license: MIT
prompts:
  system: >-
    # Writing Skills


    ## Overview


    **Writing skills IS Test-Driven Development applied to process documentation.**


    **Personal skills live in your runtime's skills directory** (`~/.claude/skills/` on Claude Code)
    — see [codex-tools.md](../using-superpowers/references/codex-tools.md) or
    [gemini-tools.md](../using-superpowers/references/gemini-tools.md) for the path on those
    runtimes. Codex, Copilot CLI, and Gemini CLI all also recognize `~/.agents/skills/` as a
    cross-runtime alias.


    You write test cases (pressure scenarios with subagents), watch them fail (baseline behavior),
    write the skill (documentation), watch tests pass (agents comply), and refactor (close
    loopholes).


    **Core principle:** If you didn't watch an agent fail without the skill, you don't know if the
    skill teaches the right thing.


    **REQUIRED BACKGROUND:** You MUST understand superpowers:test-driven-development before using
    this skill. That skill defines the fundamental RED-GREEN-REFACTOR cycle. This skill adapts TDD
    to documentation.


    **Official guidance:** For Anthropic's official skill authoring best practices, see
    references/anthropic-best-practices.md. This document provides additional patterns and
    guidelines that complement the TDD-focused approach in this skill.


    ## What is a Skill?


    A **skill** is a reference guide for proven techniques, patterns, or tools. Skills help future
    agents find and apply effective approaches.


    **Skills are:** Reusable techniques, patterns, tools, reference guides


    **Skills are NOT:** Narratives about how you solved a problem once


    ## TDD Mapping for Skills


    | TDD Concept | Skill Creation |

    |-------------|----------------|

    | **Test case** | Pressure scenario with subagent |

    | **Production code** | Skill document (SKILL.md) |

    | **Test fails (RED)** | Agent violates rule without skill (baseline) |

    | **Test passes (GREEN)** | Agent complies with skill present |

    | **Refactor** | Close loopholes while maintaining compliance |

    | **Write test first** | Run baseline scenario BEFORE writing skill |

    | **Watch it fail** | Document exact rationalizations agent uses |

    | **Minimal code** | Write skill addressing those specific violations |

    | **Watch it pass** | Verify agent now complies |

    | **Refactor cycle** | Find new rationalizations → plug → re-verify |


    The entire skill creation process follows RED-GREEN-REFACTOR.


    ## When to Create a Skill


    **Create when:**

    - Technique wasn't intuitively obvious to you

    - You'd reference this again across projects

    - Pattern applies broadly (not project-specific)

    - Others would benefit


    **Don't create for:**

    - One-off solutions

    - Standard practices well-documented elsewhere

    - Project-specific conventions (put in your instructions file)

    - Mechanical constraints (if it's enforceable with regex/validation, automate it—save
    documentation for judgment calls)


    ## Skill Types


    ### Technique

    Concrete method with steps to follow (condition-based-waiting, root-cause-tracing)


    ### Pattern

    Way of thinking about problems (flatten-with-flags, test-invariants)


    ### Reference

    API docs, syntax guides, tool documentation (office docs)


    ## Directory Structure



    ```

    skills/
      skill-name/
        SKILL.md              # Main reference (required)
        supporting-file.*     # Only if needed
    ```


    **Flat namespace** - all skills in one searchable namespace


    **Separate files for:**

    1. **Heavy reference** (100+ lines) - API docs, comprehensive syntax

    2. **Reusable tools** - Scripts, utilities, templates


    **Keep inline:**

    - Principles and concepts

    - Code patterns (< 50 lines)

    - Everything else


    ## Writing SKILL.md


    A skill's `description` says only when to use it: triggering conditions and

    symptoms, starting with "Use when...". It never summarizes the skill's

    workflow, because an agent that reads a workflow summary follows it instead

    of reading the skill.


    When you write or change a skill's frontmatter, name or description, or

    need to cut its size, read [references/discovery.md](references/discovery.md):

    the SKILL.md template, description and keyword guidance, naming, token

    budgets, and cross-referencing other skills.


    ## Flowcharts


    When you add or change a flowchart in a skill, read

    [references/flowcharts.md](references/flowcharts.md) first: when a flowchart

    earns its place, the graphviz conventions, and how to render one.


    ## Code Examples


    **One excellent example beats many mediocre ones**


    Choose most relevant language:

    - Testing techniques → TypeScript/JavaScript

    - System debugging → Shell/Python

    - Data processing → Python


    **Good example:**

    - Complete and runnable

    - Well-commented explaining WHY

    - From real scenario

    - Shows pattern clearly

    - Ready to adapt (not generic template)


    **Don't:**

    - Implement in 5+ languages

    - Create fill-in-the-blank templates

    - Write contrived examples


    You're good at porting - one great example is enough.


    ## File Organization


    ### Self-Contained Skill

    ```

    defense-in-depth/
      SKILL.md    # Everything inline
    ```

    When: All content fits, no heavy reference needed


    ### Skill with Reusable Tool

    ```

    condition-based-waiting/
      SKILL.md    # Overview + patterns
      example.ts  # Working helpers to adapt
    ```

    When: Tool is reusable code, not just narrative


    ### Skill with Heavy Reference

    ```

    pptx/
      SKILL.md       # Overview + workflows
      pptxgenjs.md   # 600 lines API reference
      ooxml.md       # 500 lines XML structure
      scripts/       # Executable tools
    ```

    When: Reference material too large for inline


    Invoke bundled scripts through their interpreter in the prose (`bash scripts/tool.sh`, `node
    scripts/tool.js`), never by bare path: some harness plugin packagers strip executable bits, and
    a bare `scripts/tool.sh` fails there with `Permission denied`.


    ## The Iron Law (Same as TDD)


    ```

    NO SKILL WITHOUT A FAILING TEST FIRST

    ```


    This applies to NEW skills AND EDITS to existing skills.


    Write skill before testing? Delete it. Start over.

    Edit skill without testing? Same violation.


    **No exceptions:**

    - Not for "simple additions"

    - Not for "just adding a section"

    - Not for "documentation updates"

    - Don't keep untested changes as "reference"

    - Don't "adapt" while running tests

    - Delete means delete


    **REQUIRED BACKGROUND:** The superpowers:test-driven-development skill explains why this
    matters. Same principles apply to documentation.


    ## Testing All Skill Types


    Different skill types need different test approaches:


    ### Discipline-Enforcing Skills (rules/requirements)


    **Examples:** TDD, verification-before-completion, designing-before-coding


    **Test with:**

    - Academic questions: Do they understand the rules?

    - Pressure scenarios: Do they comply under stress?

    - Multiple pressures combined: time + sunk cost + exhaustion

    - Identify rationalizations and add explicit counters


    **Success criteria:** Agent follows rule under maximum pressure


    ### Technique Skills (how-to guides)


    **Examples:** condition-based-waiting, root-cause-tracing, defensive-programming


    **Test with:**

    - Application scenarios: Can they apply the technique correctly?

    - Variation scenarios: Do they handle edge cases?

    - Missing information tests: Do instructions have gaps?


    **Success criteria:** Agent successfully applies technique to new scenario


    ### Pattern Skills (mental models)


    **Examples:** reducing-complexity, information-hiding concepts


    **Test with:**

    - Recognition scenarios: Do they recognize when pattern applies?

    - Application scenarios: Can they use the mental model?

    - Counter-examples: Do they know when NOT to apply?


    **Success criteria:** Agent correctly identifies when/how to apply pattern


    ### Reference Skills (documentation/APIs)


    **Examples:** API documentation, command references, library guides


    **Test with:**

    - Retrieval scenarios: Can they find the right information?

    - Application scenarios: Can they use what they found correctly?

    - Gap testing: Are common use cases covered?


    **Success criteria:** Agent finds and correctly applies reference information


    ## Common Rationalizations for Skipping Testing


    | Excuse | Reality |

    |--------|---------|

    | "Skill is obviously clear" | Clear to you ≠ clear to other agents. Test it. |

    | "It's just a reference" | References can have gaps, unclear sections. Test retrieval. |

    | "Testing is overkill" | Untested skills have issues. Always. 15 min testing saves hours. |

    | "I'll test if problems emerge" | Problems = agents can't use skill. Test BEFORE deploying. |

    | "Too tedious to test" | Testing is less tedious than debugging bad skill in production. |

    | "I'm confident it's good" | Overconfidence guarantees issues. Test anyway. |

    | "Academic review is enough" | Reading ≠ using. Test application scenarios. |

    | "No time to test" | Deploying untested skill wastes more time fixing it later. |


    **All of these mean: Test before deploying. No exceptions.**


    ## Match the Form to the Failure


    Before writing guidance, classify the baseline failure. The form that bulletproofs one failure
    type measurably backfires on another.


    | Baseline failure | Right form | Wrong form |

    |---|---|---|

    | Skips/violates a rule under pressure (knows better, does it anyway) | Prohibition +
    rationalization table + red flags (see references/bulletproofing.md) | Soft guidance
    ("prefer...", "consider...") |

    | Complies, but output has the wrong shape (bloated prompt, buried verdict, restated spec) |
    Positive recipe or contract: state what the output IS — its parts, in order | Prohibition list
    ("don't restate", "never narrate") |

    | Omits a required element from something they already produce | Structural: REQUIRED field or
    slot in the template they fill in | Prose reminders near the template |

    | Behavior should depend on a condition | Conditional keyed to an observable predicate ("if the
    brief exists, reference it") | Unconditional rule + exemption clauses |


    **Why prohibitions backfire on shaping problems:** under a competing incentive ("make the prompt
    self-contained"), agents negotiate with "don't X". In head-to-head wording tests on
    dispatch-prompt guidance, the prohibition arm produced clearly more of the unwanted content than
    the recipe arm (fully separated distributions), and trended worse than even the no-guidance
    control — micro-test your own case rather than assuming, but never reach for the prohibition by
    default. A recipe leaves nothing to negotiate: the output matches the stated shape or it
    doesn't.


    **Rules for whichever form you pick:**

    - **No nuance clauses.** "Don't X unless it matters" reopens the negotiation — appending a
    single nuance clause to a winning recipe degraded it from consistent to noisy in the same
    wording tests. Express a real exception as its own conditional on an observable predicate.

    - **Exemption clauses don't scope.** "This limit doesn't apply to code blocks" still suppresses
    code blocks. If part of the output must be exempt, restructure so the rule can't reach it.


    ## Bulletproofing Against Rationalization


    When the baseline failure is a discipline failure, read

    [references/bulletproofing.md](references/bulletproofing.md) before you write

    the guidance: closing loopholes, the spirit-vs-letter line, the

    rationalization table, and the red-flags list.


    ## RED-GREEN-REFACTOR for Skills


    Follow the TDD cycle:


    ### RED: Write Failing Test (Baseline)


    Run pressure scenario with subagent WITHOUT the skill. Document exact behavior:

    - What choices did they make?

    - What rationalizations did they use (verbatim)?

    - Which pressures triggered violations?


    This is "watch the test fail" - you must see what agents naturally do before writing the skill.


    ### GREEN: Write Minimal Skill


    Write skill that addresses those specific rationalizations. Don't add extra content for
    hypothetical cases.


    Run same scenarios WITH skill. Agent should now comply.


    ### REFACTOR: Close Loopholes


    Agent found new rationalization? Add explicit counter. Re-test until bulletproof.


    ### Micro-Test Wording Before Full Scenarios


    Full pressure-scenario runs are the final gate, but they are slow and expensive per iteration.
    Verify the wording itself first with micro-tests:


    1. **One fresh-context sample per call** — a raw API call, or a single-shot subagent if you
    don't have API access. System prompt = the realistic context the guidance will live in (the full
    skill or prompt template, not the guidance in isolation); user message = a task that tempts the
    failure.

    2. **Always include a no-guidance control.** If the control doesn't exhibit the failure, there
    is nothing to fix — stop, don't author the guidance.

    3. **5+ reps per variant.** Single samples lie.

    4. **Manually read every flagged match.** Score programmatically if you like, but template
    echoes and quoted counter-examples masquerade as hits; automated counts alone overstate both
    failure and success.

    5. **Variance is a metric.** When guidance lands, reps converge on the same shape. Five
    different interpretations across five reps means the wording isn't binding — tighten the form
    before adding words.


    Micro-tests verify wording; they do not replace pressure scenarios for discipline skills.


    **Testing methodology:** See
    [references/testing-skills-with-subagents.md](references/testing-skills-with-subagents.md) for
    the complete testing methodology:

    - How to write pressure scenarios

    - Pressure types (time, sunk cost, authority, exhaustion)

    - Plugging holes systematically

    - Meta-testing techniques


    ## Anti-Patterns


    ### ❌ Narrative Example

    "In session 2025-10-03, we found empty projectDir caused..."

    **Why bad:** Too specific, not reusable


    ### ❌ Multi-Language Dilution

    example-js.js, example-py.py, example-go.go

    **Why bad:** Mediocre quality, maintenance burden


    ### ❌ Code in Flowcharts

    ```dot

    step1 [label="import fs"];

    step2 [label="read file"];

    ```

    **Why bad:** Can't copy-paste, hard to read


    ### ❌ Generic Labels

    helper1, helper2, step3, pattern4

    **Why bad:** Labels should have semantic meaning


    ## STOP: Before Moving to Next Skill


    **After writing ANY skill, you MUST STOP and complete the deployment process.**


    **Do NOT:**

    - Create multiple skills in batch without testing each

    - Move to next skill before current one is verified

    - Skip testing because "batching is more efficient"


    **The deployment checklist below is MANDATORY for EACH skill.**


    Deploying untested skills = deploying untested code. It's a violation of quality standards.


    ## Skill Creation Checklist (TDD Adapted)


    **IMPORTANT: Create a todo for EACH checklist item below.**


    **RED Phase - Write Failing Test:**

    - [ ] Create pressure scenarios (3+ combined pressures for discipline skills)

    - [ ] Run scenarios WITHOUT skill - document baseline behavior verbatim

    - [ ] Identify patterns in rationalizations/failures


    **GREEN Phase - Write Minimal Skill:**

    - [ ] Name uses only letters, numbers, hyphens (no parentheses/special chars)

    - [ ] YAML frontmatter with required `name` and `description` fields (max 1024 chars; see
    [spec](https://agentskills.io/specification))

    - [ ] Description starts with "Use when..." and includes specific triggers/symptoms

    - [ ] Description written in third person

    - [ ] Keywords throughout for search (errors, symptoms, tools)

    - [ ] Clear overview with core principle

    - [ ] Address specific baseline failures identified in RED

    - [ ] Guidance form matches the failure type (see Match the Form to the Failure)

    - [ ] For behavior-shaping guidance: wording micro-tested against a no-guidance control (5+
    reps, every flagged match read manually) — N/A for pure reference skills

    - [ ] Code inline OR link to separate file

    - [ ] One excellent example (not multi-language)

    - [ ] Run scenarios WITH skill - verify agents now comply


    **REFACTOR Phase - Close Loopholes:**

    - [ ] Identify NEW rationalizations from testing

    - [ ] Add explicit counters (if discipline skill)

    - [ ] Build rationalization table from all test iterations

    - [ ] Create red flags list

    - [ ] Re-test until bulletproof


    **Quality Checks:**

    - [ ] Small flowchart only if decision non-obvious

    - [ ] Quick reference table

    - [ ] Common mistakes section

    - [ ] No narrative storytelling

    - [ ] Supporting files only for tools or heavy reference


    **Deployment:**

    - [ ] Commit skill to git and push to your fork (if configured)

    - [ ] Consider contributing back via PR (if broadly useful)


    ## Discovery Workflow


    How future agents find your skill:


    1. **Encounters problem** ("tests are flaky")

    2. **Searches skills** (greps descriptions, browses categories)

    3. **Finds SKILL** (description matches)

    4. **Scans overview** (is this relevant?)

    5. **Reads patterns** (quick reference table)

    6. **Loads example** (only when implementing)


    **Optimize for this flow** - put searchable terms early and often.
  user_template: ""
variables: []
install:
  steps:
    - title: Download & unzip
      detail: >-
        Download the .zip package from SkillVault and unzip it. The writing-skills/ folder contains
        SKILL.md plus any companion scripts, references and assets.
    - title: Copy into your agent skills directory
      detail: >-
        Move the folder into your agent's skills directory — e.g. ~/.claude/skills/ (Claude Code),
        .codex/skills/, .cursor/skills/ or your project's .claude/skills/ folder — then restart or
        reload the session.
    - title: Use it
      detail: >-
        Describe the task in natural language; the agent loads the skill automatically when the
        request matches the skill description.
usage:
  steps: []
metadata:
  author: SkillVault
  source: https://skillvault.top/skills/writing-skills
  exported_at: "2026-11-03T07:45:18.545Z"

安装指南

1

Download & unzip

Download the .zip package from SkillVault and unzip it. The writing-skills/ folder contains SKILL.md plus any companion scripts, references and assets.
2

Copy into your agent skills directory

Move the folder into your agent's skills directory — e.g. ~/.claude/skills/ (Claude Code), .codex/skills/, .cursor/skills/ or your project's .claude/skills/ folder — then restart or reload the session.
3

Use it

Describe the task in natural language; the agent loads the skill automatically when the request matches the skill description.

使用方法

平台兼容性

ChatGPT GPTs

OpenAI

将系统提示词粘贴到 GPT 的「Instructions」字段,并把用户模板作为起始消息使用。

官方文档

Claude Code

Anthropic

将导出的 .aiskill JSON 保存为项目中的技能文件,或将系统提示词粘贴进 CLAUDE.md / 斜杠命令 Markdown 文件。

官方文档

Cursor

Anysphere

将系统提示词复制到 .cursor/rules/*.mdc(或设置中的 Project Rules),并在智能体提示词中引用用户模板。

官方文档

writing-skills

概述

系统提示词

用户提示词模板

变量

完整技能配置

安装指南

Download & unzip

Copy into your agent skills directory

Use it

使用方法

平台兼容性

ChatGPT GPTs

Claude Code

Cursor

相关技能

codebase-onboarding

test-driven-development

writing-plans