# Writing Skills

> Author and pressure-test agent skills—triggers, thin SKILL.md, references, validation. Use when creating or revising skills in this repo.

- Skill: `charlieviettq/writing-skills` (Agent Skill)
- Install (CLI): `npx skillmds@latest add charlieviettq/writing-skills`
- Raw SKILL.md: https://api.skillmd.com/api/skills/charlieviettq/writing-skills/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: charlieviettq (https://skillmd.com/u/charlieviettq)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/charlieviettq/writing-skills

---


# Writing skills

## When to use

- Adding a skill under `.cursor/skills/<domain>/<name>/`
- Fixing discovery issues (agent never invokes the skill)
- Splitting an oversized skill into SKILL.md + reference.md

## When not to use

- One-off project instructions (use README or rules)
- Copying entire third-party skill trees without audit

## Workflow

1. Read [`docs/skill-writing-guide.md`](../../../../docs/skill-writing-guide.md) and [`docs/review-rubric.md`](../../../../docs/review-rubric.md)
2. Run `skill-supply-chain-audit` if source is external
3. Draft frontmatter: `name` matches folder; description includes **Triggers:**
4. Keep SKILL.md thin; move long examples to `reference.md`
5. Pressure-test: list 3 user phrases that should trigger and 2 that should not
6. Run `python3 scripts/validate-skills.py`
7. Regenerate Claude skills if editing Cursor source

## Description quality

- **Good:** concrete workflow + quoted trigger phrases
- **Bad:** broad "use for everything" or "MUST run before any action"

## Checklist before PR

- [ ] Public-safe (no secrets, no auto-push scripts in skill body)
- [ ] No duplicate of existing skill in `SKILL_INVENTORY.md`
- [ ] Entry in `EXTERNAL_SKILLS.md` if adapted from upstream
- [ ] `CHANGELOG.md` updated under Unreleased

## Related

`skill-supply-chain-audit`, `reflect-yourself`, `core-workflow/planning-and-task-breakdown`

*Authoring practices inspired by [obra/superpowers](https://github.com/obra/superpowers) (MIT).*