Create a new agent skill, review an existing skill, or improve its clarity, context use, behavior, or fit to changed requirements. The workflow covers both discovery through the frontmatter description and execution through the instructions and supporting resources.

Usage

Install this skill from the repository:

npx skills add kusold/agent-skills --skill skill-writing

Example requests:

Write a skill for our release process using the examples in this repository.

Improve this skill: it activates for ordinary documentation edits,
but it should apply only to API migration guides.

Review skills/example/SKILL.md for unclear decisions and missing resources.
Report findings without changing files.

The agent reads local conventions and available evidence, identifies the intended outcome, and creates or revises the package. A review request produces findings; a request to improve the skill includes making the relevant edits. Existing working behavior and unrelated metadata are preserved.

What makes a useful skill

The skill applies these design criteria:

• Precise discovery: the name and description identify the actual capability and distinguish nearby requests. Different names alone do not resolve overlap with installed skills.
• Useful decisions: instructions supply specialized guidance instead of repeating generic advice.
• Progressive context: essential decisions stay in SKILL.md; conditional detail is linked and loaded when needed.
• Portable packaging: executable guidance travels with the skill, with external dependencies stated explicitly.
• Appropriate constraints: fixed steps protect real invariants, while routine choices remain adaptable.
• Observable outcomes: checks examine selection, artifacts, and effects, with regression cases for changes.
• Maintainability: improvements address a stated objective, including demonstrated failures, clarity, brevity, or changed requirements.

These are design criteria, not a numerical quality rubric. A format validator can detect structural errors but cannot prove that an agent will select or execute a skill correctly. Validation reports distinguish inspection, walkthroughs, and actual agent trials.

Packaging and Codex support

The entrypoint keeps shared authoring decisions independent of a particular host and routes format rules and package examples to the bundled specification. An optional Codex reference covers default installation paths, naming limits, agents/openai.yaml, invocation policy, and bundled initialization, metadata generation, and validation tools. It also explains how to proceed when those helpers are unavailable.

The reference is loaded only for Codex-specific work. Its commands use tools from the target installation; this package does not include copies of Codex’s authoring scripts. Existing YAML settings are edited in place when regenerating the file would discard unrelated policy or dependencies.

Agent Skills references

The format reference records portable requirements and links to official authoring guides, reviewed on 2026-10-22. It distinguishes the standard from host-specific extensions and validator limitations. The script checklist applies when adding executable helpers.

The format reference includes an isolated uvx command for the official validator when skills-ref is not installed. It states the fallback’s prerequisites and how to report inspection when automated validation is unavailable.

The full specification snapshot is bundled for offline checks of exact rules and examples. It was extracted with Defuddle 0.19.5 and checked against the site’s native Markdown on 2026-10-22. The file records its source, CC BY 4.0 attribution, and conversion changes. It loads only when detailed format guidance is needed; the short checklist remains the normal entry point. Refresh instructions in the format reference require reviewing the conversion before replacing the snapshot.

The official documentation informed additional guidance on grounding skills in actual project knowledge, choosing useful defaults, separating discovery from outcome checks, reviewing execution traces, and evaluating against a baseline. Sources: best practices, descriptions, evaluation, and scripts.

The specification is the format authority; local helpers can lag behind it. For example, the inspected Codex validator rejects the standard compatibility field. Such disagreements should be reported rather than resolved by silently discarding valid metadata.

Research basis and limits

This skill was informed by a wiki-query pass over the author’s llm-wiki on 2026-10-22, beginning with wiki/index.md and following the relevant concepts to source summaries and archived raw text. The wiki had no dedicated skill-authoring source or behavioral evaluation evidence at that time.

The following evidence informed the design:

The archived originals are OpenWiki’s release announcement and Karpathy’s post on understanding LLM outputs. This research used the local snapshots; it did not verify the live pages.

Discovery boundaries, portable packaging, scoped improvements, and behavioral checks also draw on the bundled skill-creator guidance consulted during authoring and this repository’s packaging conventions. They are implementation choices here, not findings established by the wiki. The wiki remains unchanged, and using this skill does not require access to it or to another authoring skill.

Full instructions

See the skill definition and its evaluation reference. The evaluation reference provides representative cases and a result-recording template; it does not require a particular test framework or delegation tool.