write-a-skill

name	write-a-skill
description	Authoring guide for CLI-native skill files and meta skills in agent-infra. Use when creating or updating grouped markdown skills, ref pages, reorganizing skill trees, or onboarding contributors.
metadata	{"version":"2.0","category":"meta-tooling","output_artifacts":["skill_file.md"],"skills":["domain-discovery","tree-generator"]}

Writing Skills for agent-infra

This repo is skills-only. Skills are the single source of guidance. They must be short, concrete, and optimized for agent use.

Module Types

Type	Directory	Purpose
Skill	skills/	Task playbooks and reference knowledge
Agent	agents/	Heuristics for what “good” looks like (optional)
Meta	meta/	Tooling for generating and maintaining skills

Avoid duplicating guidance across files. Each skill owns one concern.

---

Internal Skills (skills/)

Internal skills use grouped markdown files that the ladybluenotes CLI discovers. Do not create SKILL.md router pages for this repo; use names, descriptions, aliases, tags, depth, and ref/ pages so the CLI can choose the right file.

File Tree

skills/
  tooling/
    vitest/
      basics.md
      config.md
      ref/
        mocking.md
        environments.md
  preferences/
    tooling.md
    ref/
      package-manager.md

Use ref/ for deep material that should load only when a prompt needs it. Use ordinary .md files for primary task pages.

Frontmatter

---
name: skills/[category]/[skill-name]
description: >
  Dense, 1–2 sentence routing key. What this skill covers.
type: [skill | sub-skill | reference]
category: [general | typescript | javascript | docs | debug | review | performance | seo | research | tooling | preferences | frameworks]
library: [optional]
library_version: [optional]
depth: [primary | reference]
aliases:
  - [optional short lookup name]
tags:
  - [optional search terms]
references:
  - skills/[category]/[path/to/ref]

   [ ]

Body Structure

# [Skill Name]

## Setup
[Minimum working example. Real imports. No placeholders.]

## Core Patterns
[2–4 patterns by default. Add as many as needed to make the guidance unambiguous. Each pattern has a code block and 1–2 lines of explanation.]

## Common Mistakes

### [PRIORITY] [Short problem name]

```ts
// Wrong

// Correct

[1 sentence: what fails and why. Add more examples if a single wrong/correct pair is not enough.]

Tensions (optional)

• [Tradeoff statement]

References (optional)

• @skills/[category]/[reference-skill].md

Include this section whenever you add any ref/ files.

## Library Skills (generated)

Library-specific skills generated for external npm distribution may still follow
the tree-generator `SKILL.md` format when the package ecosystem requires it.
For this repo's own skills, prefer the grouped markdown format above.

```yaml
---
name: [lib]/[domain]
description: >
  Dense routing key for this domain.
type: [core | sub-skill | framework | lifecycle | composition | security]
library: [lib]
library_version: "[version]"
sources:
  - [repo:path]
requires:            # only for framework/composition skills
  - [lib]-core
---

# [Library] — [Domain]

## Setup
[Complete, copy-pasteable example]

## Core Patterns
[2–4 patterns with code]

## Common Mistakes
[3+ mistakes with wrong/correct and short explanation]

## References (optional)
- ref/[topic].md

Include this section whenever you add any `ref/` files.

Use meta/domain-discovery and meta/tree-generator to build these.

---

Agents (optional)

Agents capture heuristics, not workflows. Keep them short and concrete.

---
name: agents/[domain]
description: >
  Heuristics for what good looks like in [domain].
type: agent
category: [language | framework | task]
---

# [Domain]

## Heuristics
- [What to optimize for]
- [Common pitfalls]
- [Preferred patterns]

---

Registration

1. Add skill paths to registry.yaml under the correct category when the registry structure requires it.
2. Ensure the skill is discoverable via ladybluenotes skills list.
3. Update category metadata such as domain_map.yaml when the category uses generated discovery data.

---

Validation Checklist

Check	Rule
Frontmatter present	name, description, type, category present
Name matches path	name matches file path without .md
Code blocks complete	Real imports, copy-pasteable
No Apply/Do/Don’t	Use Setup/Core Patterns/Common Mistakes
One concern per skill	Split to sub-skills if too broad
References lean	Use ref/ for overflow or deeper optional detail; include References section when ref/ exists
Registered	registry.yaml updated