feat(skill-export): generate Claude Code SKILL.md bundles from a help corpus

[silversurfer562]

Summary

Phase one of the attune-help-as-skill opportunity from the 2026-05-08 enhancements briefing. The exporter walks an attune-help-compatible templates/ tree and writes one Claude Code `SKILL.md` per concept template — the bundled corpus becomes a generator for skills rather than a runtime competitor.

Public surface

```python
from attune_author.skill_export import export_skills

result = export_skills(template_dir, output_dir, overwrite=False)

result.written: list[SkillRecord(feature, skill_path, description, body_chars)]

result.skipped: list[(feature, reason)]

```

CLI:

```
attune-author export-skills [--source TEMPLATE_DIR] [--output ./skills] [--overwrite]
```

`--source` defaults to attune-help's bundled corpus (resolved via `attune_help.adapters.rag.AttuneHelpAdapter` from the 0.11.0 release) so the simplest invocation is `attune-author export-skills --output ./skills` and you get a directory of skills loadable by any Claude Code consumer.

Output shape

```
output_dir/
├── security-audit/
│ └── SKILL.md frontmatter: name + description; body: concept
├── audience-adaptation/
│ └── SKILL.md
└── ...
```

Three details worth pointing at in review

1. Canonical slug stripping. Concept files often carry organizational prefixes (`tool-security-audit.md`, `task-debugging-sessions.md`) that don't appear in `summaries.json`. The exporter strips `tool-`/`task-` so the SKILL.md `name` matches the canonical feature slug downstream consumers expect. ⊕ output dir is `security-audit/`, not `tool-security-audit/`.

2. Description resolution chain. `summaries.json[feature]` → `summaries.json[file_stem]` (legacy fallback) → frontmatter `description` → first-paragraph extraction → generic stub. Skill triggering quality depends on the description so the chain prefers human-curated text over extractive fallbacks. The bundled corpus exports cleanly today: 23 of 43 skills hit `summaries.json`, the rest get nice extractive descriptions from concept body intros.

3. Defensive defaults. Unsafe slugs, malformed frontmatter, empty bodies, and pre-existing SKILL.md files are skipped with a recorded reason; the CLI prints a one-line summary per skip rather than raising. `--overwrite` opts in to replacing existing files.

Test plan

• 18 new tests in `tests/test_skill_export.py`: canonical-slug stripping (3), first-paragraph extraction (4), happy-path export (4), description fallback chain (1), edge cases (5: missing concepts dir, empty body, unsafe slug, overwrite skip, overwrite replace), summaries.json absence (1).
• Smoke run against the bundled attune-help corpus: 43 skills written, 0 skipped, all with valid frontmatter and prose descriptions. `name: security-audit` and `description: Scans your code for security vulnerabilities — eval/exec, path traversal, hardcoded secrets, injection risks.` confirmed for the canonical case.
• Full attune-author suite green: 669 passed, 31 skipped locally (`test_mcp_server.py` ignored — local venv lacks `mcp`; CI runs the full matrix).
• `ruff check src/attune_author/skill_export.py src/attune_author/cli.py tests/test_skill_export.py` clean.

Versioning

• Bumps `attune-author` to 0.10.0 — additive feature in a stable, well-tested module.

Follow-up (out of scope, but flagged)

• Depth files. Today's export uses only the concept template. A v2 could add `task.md` and `reference.md` referenced from the SKILL.md so Claude Code's progressive disclosure surfaces them on demand. The infrastructure is straightforward; punted to keep this PR scoped.
• `pip install attune-author[skills]` marketplace listing helper (write a `marketplace.json` from the same input).

🤖 Generated with Claude Code