Writing Skills

Objective

Produce professional-grade skills: high-signal, safe, portable, and reliably triggerable. This skill:

Writes or updates a skill directory (
```
SKILL.md
```
+ optional
```
scripts/
```
,
```
references/
```
,
```
assets/
```
)
Generates
```
agents/openai.yaml
```
UI metadata
Runs validation (
```
skillcheck
```
)
Runs a critic review using
```
$reviewing-skills
```
and iterates until the bar is met

When to use / When not to use

Use when:

The user asks to create a new skill (
```
SKILL.md
```
+ optional
```
scripts/
```
,
```
references/
```
,
```
assets/
```
).
The user asks to refactor, tighten, or “upgrade” an existing skill for trigger precision and token efficiency.

Do not use when:

The user only wants a rubric-based review/grade of an existing skill (use
```
$reviewing-skills
```
).
The request is not about a skill directory containing
```
SKILL.md
```
.

Quality Bar (default)

Target outcome:

No spec violations, and
Weighted score ≥ 4.5/5.0 (A- or better), and
No P1 findings

The rubric is owned by:

$reviewing-skills

→

reviewing-skills/references/skills-rubric.md

(single source of truth).

Safety / Constraints (non-negotiable)

Never read, request, or paste secrets (
```
.env
```
, API keys, tokens, private keys, credentials).
Only write inside the user-specified skill directory. If the target path is unclear, ask.
Do not run commands that modify the repo unless the user explicitly asked for those changes.
Do not browse the web or call external systems unless the user explicitly requests it.
Do not execute untrusted code in the target repo (scripts/binaries/tests) unless the user explicitly asks and you can justify the risk.
If the skill being written can perform destructive actions, add explicit confirmation gates and “never do” rules.

Portability Requirement (Codex + Claude Code/Desktop + OpenCode)

Write skill instructions in capability language (search/read/edit/run commands) and avoid hard-coding one vendor’s tool names. If mentioning a product-specific tool, provide a short adapter note (“if unavailable, use shell + rg/sed”). For portability guidance, use references/portability.md.

Workflow (decision-complete)

Update mode (keep diffs small)

If the user asked to update an existing skill (not create a new one):

Change only the requested parts; do not rewrite unrelated sections for style.
Preserve existing behavior unless it is a spec violation or causes mis-triggering.
Prioritize: trigger precision (description “when to use”), safety/guardrails, validation loop, then token efficiency.

0) Intake (ask only what matters)

Collect:

Skill name (hyphen-case)
What it does (1 sentence)
When to use (concrete triggers: file types, paths, scenarios)
Inputs/outputs (artifacts produced)
Safety constraints (read-only? destructive ops? secrets? web browsing?)
Resources needed:
```
scripts/
```
vs
```
references/
```
vs
```
assets/
```

1) Skill Split Proposal (prevent mega-skills)

Before writing anything, produce a short proposal:

Should this be one skill or multiple?
Recommend companion skills when appropriate, e.g.:
- reviewer/critic skill (grading, audits)
- installer skill (wiring tools or repo integration)
- domain-reference skill (big schemas or policies)

Rule of thumb:

If the request spans multiple disjoint workflows, split.
If the skill needs deterministic, repeatable logic, add a
```
scripts/
```
helper.

2) Scaffold the skill directory

Create the skill directory under the user-specified path:

```
<skill-name>/SKILL.md
```
— use references/skill-skeleton.md as the template

<skill-name>/agents/openai.yaml

— include

interface.display_name

short_description

(25–64 chars), and

default_prompt

(must mention

$<skill-name>

)

Resource subdirs (
```
scripts/
```
,
```
references/
```
,
```
assets/
```
) — only create the ones you will use

Prefer minimal resources. Validation is expected to fail until you fill in the TODOs in Step 3.

3) Write

SKILL.md

(core)

Use references/skill-skeleton.md as the canonical outline.

Hard requirements:

Frontmatter
```
description
```
must include what + when to use.
Include guardrails and explicit “do not do” rules when relevant.
Include validation loops (what to check after writing/running).
Keep SKILL.md lean; move bulk examples/specs to
```
references/
```
.

4) Add resources (only if they buy reliability)

Use references/resource-patterns.md:

Put deterministic logic in
```
scripts/
```
with a stable CLI.
Put large but needed knowledge in
```
references/
```
(loaded on demand).
Put templates/boilerplate in
```
assets/
```
.

5) Validate (hard gate)

Run both linters — both must pass before proceeding.

skillcheck (project rules):

Inside this repo with

packages/skillcheck/dist/

present:

node packages/skillcheck/bin/skillcheck.js <skill-dir>

Inside this repo without

dist/

cd packages/skillcheck && npm install && npm run build

, then run the above.

Outside this repo:
```
npx skillcheck <skill-dir>
```

agnix (specification rules):

npx agnix <skill-dir>

Fix all reported errors before proceeding. Each linter collects every violation in a single run.

Quality Gate

Two-phase review after validation. Target: Quality Bar (score >= 4.5, no P1 findings).

Phase 1: Self-critic review

Grade the skill against

$reviewing-skills

→

reviewing-skills/references/skills-rubric.md

. Re-read

SKILL.md

as if encountering it for the first time and score each rubric dimension (spec compliance, trigger precision, workflow quality, token efficiency, safety, robustness, portability).

Check for:

Vague or missing "when to use" triggers
Missing guardrails for destructive/network actions
Bloated prose that should be bullets or moved to
```
references/
```
Workflow steps that leave key decisions ambiguous

Actions:

Fixable without re-analysis -> fix inline.
Requires re-analysis or user input -> flag and continue.
If score < 4.5 or P1 findings remain, fix before proceeding to Phase 2.

Phase 2: Fresh-context subagent review

Run a fresh-context critic pass using

$reviewing-skills

If your environment supports subagents, spawn a fresh-context subagent and give it the skill path.
Otherwise, invoke
```
$reviewing-skills
```
directly and provide the path.
If
```
$reviewing-skills
```
is not available, self-review against the 7 rubric dimensions and note the gap in the deliverable.
If the skill is git-tracked and you changed it, require the critic to cite the relevant diff hunk or commit short-hash for any change-driven P1/P2 findings.
Apply P1 + P2 fixes (P3 last).
Re-run validation.
Repeat up to 3 loops, stop early when the Quality Bar is met or two consecutive iterations show no score improvement (plateau).

7) Finalize

Deliver:

The final skill folder path(s)
Any suggested follow-on skills (from the split proposal)
A short note explaining why the skill will trigger correctly (tie to description “when to use”)

Edge Cases

User provides no skill name or path: ask before proceeding; do not guess.
Target directory already has a SKILL.md: enter update mode; do not overwrite without confirmation.
Linters not available (no Node.js / npx): warn the user; skip validation but note it was skipped in the deliverable.

Output Rules

No placeholders (
```
TODO
```
,
```
TBD
```
) in the final skill.
Avoid deep reference chains: SKILL.md links directly to every resource it expects to be read.
Prefer minimal, directive prose over explanations of common concepts.

writing-skills

NPX Install

Tags

SKILL.md Content