borghei/Claude-Skills / engineering/write-a-skill
write-a-skill
VerifiedAuthor, lint, and publish skill packages that satisfy the library authoring standard. Use when creating a new skill, reviewing a skill PR, or fixing one that never activates.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 16.5 KB |
| assets/sample_descriptions.json | config | 1.3 KB |
| assets/sample_lint_rules.json | config | 318 B |
| assets/sample_skill_spec.json | config | 1.2 KB |
| assets/skill-review-checklist.md | markdown | 2.7 KB |
| references/authoring-playbook.md | markdown | 13.3 KB |
| references/pattern-checklist.md | markdown | 10.4 KB |
| references/writing-for-agents.md | markdown | 8.1 KB |
| scripts/description_audit.py | script | 9.7 KB |
| scripts/lint_checks.py | script | 8.8 KB |
| scripts/skill_lint.py | script | 10.3 KB |
| scripts/skill_scaffold.py | script | 9.0 KB |
assets/skill-review-checklist.md
View on GitHub# Skill Publication Review Checklist
Copy this into the PR that adds the skill. Every box must be checked by someone
other than the author before merge. `skill_lint.py` covers the mechanical half;
the judgement half is yours.
**Skill:** `<domain>/<name>`
**Reviewer:** `<name>`
**Lint result:** `python3 engineering/write-a-skill/scripts/skill_lint.py --skill <path> --strict`
## Mechanical (the linter proves these)
- [ ] Frontmatter has `name`, `description`, `license`, and all six `metadata` fields
- [ ] `name` matches the folder name exactly
- [ ] Description is ≤ 240 characters and contains a `Use when ...` clause
- [ ] SKILL.md is under 500 lines; each reference is under 800
- [ ] Every script is 150-300 lines, has argparse, `--format`, and a `__main__` guard
- [ ] Every import resolves to the standard library
- [ ] Required sections present in order; at least 3 anti-patterns
- [ ] `assets/` ships at least one `sample_*.json`
## Judgement (only a human proves these)
- [ ] **Activation** — read only the description. Can you name three user
sentences that should activate it, and three near-miss sentences that
should not? If the near-misses also match, the triggers are too broad.
- [ ] **Opinion** — every recommendation states a position, a reason, and an
escape hatch. No section presents a menu of equal options.
- [ ] **Thresholds** — decision tables contain real numbers, not "it depends"
or "as appropriate."
- [ ] **Anti-patterns are real** — each one describes a mistake the author has
actually seen, with a root cause that sounds reasonable on the surface.
- [ ] **Scripts earn their place** — each does analysis a human would otherwise
do by hand for 15+ minutes. No script is a formatter around user input.
- [ ] **Runnable** — every bash block in Workflows was executed verbatim against
the shipped sample data, and its output was pasted into the PR.
- [ ] **Self-contained** — copy the folder to an empty directory. SKILL.md still
reads, scripts still run, no path breaks. `standards/` is the only
permitted outbound reference.
- [ ] **Quality bar** — write one sentence estimating the time saved versus
doing the task unaided. If it is under 40%, do not publish.
## Reject reasons (write one if you decline)
| Reason | What it means |
|--------|---------------|
| Thin wrapper | The skill restates a generic process with no thresholds or tools |
| Duplicate | An existing skill in the library already owns this trigger space |
| Unrunnable | A workflow's bash block errors against the shipped samples |
| Menu writing | The skill lists options without recommending one |
| Reference dump | Content that belongs in `references/` is inflating SKILL.md |
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |