docs: add README.md documentation for all skills

[janhesters]

Summary

• Create human-readable README.md files for the 25 skills that only had SKILL.md, documenting usage, commands, and options
• Update the main README Skills section to link all 28 skills to README.md consistently (previously only aidd-churn, aidd-fix, and aidd-namespace had READMEs; the rest linked to SKILL.md)
• Fix the broken aidd-fix link that pointed to a non-existent README.md

Test plan

• Verify all 28 skill README.md links resolve correctly
• Confirm README content accurately reflects each skill's SKILL.md
• Verify no references to removed skills (aidd-redux-example, aidd-timing-safe-vulnerabilities)

[ianwhitedeveloper]

One fix is needed before merge:

aidd-fix has a broken link

The existing entry links to ai/skills/aidd-fix/README.md, but that file doesn't exist — only SKILL.md and index.md are present in that directory. Since this file is already open, this is a good opportunity to fix
it:

  - - **[/aidd-fix](ai/skills/aidd-fix/README.md)** — Fix a bug...
  + - **[/aidd-fix](ai/skills/aidd-fix/SKILL.md)** — Fix a bug...

Suggestion (optional): standardise all links to SKILL.md

The Agent Skills spec defines SKILL.md as the canonical entry point for every skill — README.md is not part of the spec's directory structure. aidd-churn and aidd-namespace both have README.md files, but they sit
alongside SKILL.md, not instead of it. Linking some skills to README.md and others to SKILL.md adds inconsistency without a clear reason.

Worth either standardising all 30 to SKILL.md, or adding a note in the README explaining why those two are treated differently.

[ericelliott]

No, we should NOT link to SKILL.md - that is code, NOT documentation. What we need to do is DOCUMENT all the skills and link to READMEs.

[ericelliott]

Please make sure all skills have proper documentation listing usage, commands, command usage, options, etc. Link to READMEs, NOT SKILL.md

[ianwhitedeveloper]

Looks good from my side — the requested documentation pass appears addressed, including adding README coverage and fixing skill README links.

I think @ericelliott should probably have final sign-off here since the direction shifted to README-first docs and this aligns with his requested changes.

Additional Findings - considered optional/exploratory

• Medium — Reviewer requirement may still be only partially satisfied (usage/commands/options not consistently documented):
  The requested change explicitly asked for “proper documentation listing usage, commands, command usage, options, etc.” on all skills. The PR adds README coverage and fixes linking, but many skill READMEs are still narrative-only and do not include explicit command usage/options sections.
  Example (aidd-ui):

# aidd-ui — UI/UX Design Reference

`/aidd-ui` guides the design and implementation of beautiful, friendly user
interfaces with attention to aesthetics, accessibility, motion design, and
responsive layouts.

## Skills
...
## Approach
...
## When to use `/aidd-ui`
...

Example (aidd-react):

# aidd-react — React Component Authoring Reference
...
## useDatabase — single context
...
## Binding component vs presentation
...
## When to use `/aidd-react`
...

What Looks Resolved

• README.md now links skills to README.md (not SKILL.md), including aidd-fix.
• I verified link integrity locally on the PR head: all linked skill README targets exist.
• I verified skill doc coverage on this branch: every skill directory has a README.md (28/28 in current repo state).
• Hotspot/churn check shows no overlap with risky high-churn runtime code (this PR is documentation-only).

Open Question

• Do maintainers want a standard README template for every skill (e.g., required sections: Usage, Commands, Command usage, Options) to fully satisfy the requested review language, or is the current free-form style acceptable?

Residual Risk / Gaps

• No automated docs schema/check enforces section consistency, so future skill docs may drift in format.

Reference: PR #151

[janhesters]

@ianwhitedeveloper Good points on the consistency question. The reason some READMEs are narrative-only is that not every skill exposes user-invocable commands or options — skills like aidd-ui, aidd-javascript, aidd-layout, and aidd-structure are guidance/enforcement skills that activate contextually rather than via explicit commands.

The skills that do have commands (aidd-please, aidd-product-manager, aidd-autodux, aidd-task-creator, aidd-log, etc.) already document them with tables in their READMEs.

A mandated template with required Commands/Options sections would result in empty or N/A sections for roughly half the skills. The current approach documents what each skill actually offers — commands and options where they exist, usage guidance and conventions where that's the substance.

Happy to standardize further if Eric feels differently, but this seemed like the right balance.

[ericelliott]

Oops, looks like I made a useless mess of our file system with the indexer.

Let's edit that index generator to make one bullet point per skill - list only the SKILL, no readmes, etc.:

## Skills Index

"- $skillname - $description"

If no description is available, the skill needs fixing.

This should reduce index clutter.

We also need to import the main skill index file into AGENTS.md with import @skills/index.md

In other words, when we are done, there is only 1 index.md per skill folder, and those get directly imported into AGENTS.md:

ai/skills/index.md
aidd-custom/skills/index.md (this should get generated even if there are no skills here - the folder should exist as a scaffold base)

[ericelliott]

@janhesters did you know you can invoke the JS skill like a command, and AI will review the code to ensure that it follows the skill guidelines? We explicitly call that out with a Commands {} block in the skill.