skill-writer

Files (3)

• SKILL.md
• skill-quality-checklist.md · checklists/
• skill-validation.md · validation/

SKILL.md (first lines)

# Nexus Skill Writer

Produce a **complete, production-ready skill** every session — not a draft, not a skeleton.

---

## Required Directory Layout

```
skill-name/
├── SKILL.md                        ← entry point, <500 lines
├── checklists/
│   └── execution-checklist.md
├── anti-patterns/
│   └── common-mistakes.md
└── validation/
    └── output-validation.md
```

Every SKILL.md must have YAML frontmatter:

```yaml
---
name: skill-name                  # must exactly match the containing directory
description: >                    # THE TRIGGER MECHANISM — be explicit and dense
  Use this skill when ... [detailed trigger conditions].
  Trigger phrases include: "...", "...", "...".
  Also trigger when ... [edge cases].

---
```

The `description` is the single most important field. Claude selects skills based only on name + description. A vague description means the skill never triggers. Under-triggering is the #1 skill failure mode.

---

## Phase 0 — Skill Classification

Before writing anything, classify the request:

**New skill or extension?**
1. Scan `available_skills` in the system prompt.
2. If an existing skill covers 60%+ of the use case, offer to extend instead.
3. Present options as a table:

| Option | Best when | Risk |
|--------|-----------|------|
| Extend existing | Same domain, similar triggers | May bloat the existing skill |
| Create new | Distinct triggers, different output contract | Maintenance overhead |
| Merge two skills | Overlapping triggers, narrow scopes | Wider scope per skill |

Never decide for the user — present options and wait for direction.

**Category:**

| Category | Description |
|----------|-------------|
| engineering | Code generation, architecture, implementation |
| debugging | Failure investigation, root cause, regression |
| devops | CI/CD, infra, deployments |
| code-review | PR review, diff analysis, quality checks |
| testing | Test writing, coverage, test strategy |
| reliability | SLOs, on-call, incident management |
| observability | Logs, metrics, traces, dashboards |
| refactoring | Code transformation, technical debt |
| performance | Profiling, optimization, benchmarking |

**Primary or sub-skill?** Primary = own directory + full SKILL.md. Sub-skill = .md inside an existing skill directory (only for very narrow, truly subordinate scope).

---

## Phase 1 — Requirements Gathering (MANDATORY)

Ask conversationally — max 2 questions per turn. Extract answers from context first; only ask what you cannot infer. Do not proceed to Phase 2 without answers to Q1, Q2, Q3.

| # | Question | Why |
|---|----------|-----|
| 1 | What should this skill enable Claude to do? | Defines scope |
| 2 | What phrases/contexts should trigger it? | Shapes description |
| 3 | What is the expected output format? | Shapes Output Contract |
| 4 | Are there constraints? (tools, env, audience) | Shapes Compatibility |
| 5 | Example input + ideal output? | Becomes a production example |
| 6 | What does failure look like? What must never happen? | Shapes Failure Modes |
| 7 | What context must be gathered before acting? | Shapes Context Acquisition |
| 8 | What are the hallucination risks or dangerous assumptions? | Shapes Failure Modes |

Never assume answers to Q6, Q7, or Q8.

---

## Phase 2 — SKILL.md Writing

Use this exact section order. Adapt depth to domain; do not drop sections.

Required sections (in order):
1. **YAML frontmatter** — `name` + `description` (specific task triggers and exclusions)
2. **One-liner** — what this skill does and why it exists.
3. **Metadata table** — Category, Required Tools, Required Context, Expected Inputs, Expected Outputs.
4. **Skill Philosophy** — Problem, Why it matters, 2-3 Engineering principles.
5. **Context Acquisition** — Named signals with collection methods + explicit "stop and ask" rule for insufficient context.
6. **Execution Workflow** — Numbered steps, each with: What (specific verb), How (tool/command), Output, Failure signal.
7. **Engineering Heuristics** — IF/THEN/BECAUSE rules with thresholds. No descriptions — only decision rules.
8. **Failure Modes** — Table: Failure Mode | Trigger Condition | Mitigation (3+ rows).
9. **Validation** — Checkbox list of pass/fail criteria including a Confidence rating.
10. **Output Contract** — Table of every output field: name, required/optional, description. Fields: findings, evidence, confidence, risks, recommendations, next_actions.
11. **Anti-Patterns** — "Never X → Instead Y" rules (3+ rules).
12. **Examples** — At least 1 production-scale input → output reference.

---

## Phase 3 — Supporting Directory Creation

Create or update all supporting files for every skill. These are not optional.

### checklists/execution-checklist.md
- Pre-flight: what to verify before starting
- Execution: ordered step-by-step checklist
- Output review: what to check before delivering
- Post-delivery: follow-up actions for the user

From aayushostwal/nexus, MIT.

More from aayushostwal/nexus