Add Doorstop Agent Skill package for AI coding agents

[aelaguiz]

Summary

Adds skills/doorstop/, a comprehensive Agent Skill that teaches any compatible AI coding agent (Claude Code, Cursor, Gemini CLI, Codex CLI, Antigravity) how to drive Doorstop end to end. No Doorstop source, tests, or docs are modified — this is a pure addition under a new top-level skills/ directory.

An Agent Skill is a progressively-disclosed knowledge package: a compact always-on SKILL.md routes the agent into deeper references only when the task needs them, so the always-on context stays small.

What's in the skill

• SKILL.md — entry point with a workflow map, core concepts, and non-negotiables. Always-on description is ~200 chars.
• references/ — 10 lazy-loaded deep references:
  • cli-commands.md — every doorstop subcommand and every flag
  • python-api.md — Tree / Document / Item, build, find_document, find_item, exceptions, hooks
  • file-formats.md — .doorstop.yml, item YAML, Markdown-frontmatter, references:, extended attrs, !include
  • workflows.md — bootstrap, link, review, publish, XLSX round-trip, CI gate, restore
  • validation.md — full INFO/WARNING/ERROR matrix, suspect-link mechanics, every -L/-R/-C/-Z/-S/-W/-w/-e flag
  • publishing.md — format matrix, --template, --index, --no-levels, traceability
  • import-export.md — CSV/TSV/XLSX round-trip, blank-UID convention, -m/--map
  • server-api.md — every REST endpoint with JSON shapes
  • extensions.md — extensions.item_validator, tree.validate(document_hook=, item_hook=), item_sha_required
  • troubleshooting.md — decision tree for the common failure modes
• scripts/doorstop_snapshot.py — dumps tree/items/links/issues as JSON for agent reasoning
• scripts/doorstop_lint.sh — CI-friendly doorstop -e -Z wrapper
• assets/example_reqs/ — tiny two-document tree (REQ + TST, one link, one heading) that validates clean and doubles as a copy-paste starter template

Install

The skill is installable across agents via the OpenSkills universal installer once this PR is merged:

npx openskills install doorstop-dev/doorstop            # project-local
npx openskills install doorstop-dev/doorstop --global   # ~/.claude/skills/doorstop

The layout (skills/<name>/SKILL.md at repo root) is what OpenSkills expects for multi-skill repos, and it sits cleanly alongside the existing doorstop/, docs/, and tests/ trees.

Why it lives in-tree

Doorstop's CLI surface, file format, and Python API evolve together. Keeping the skill inside this repo means the matching reference doc can be updated in the same PR as the behavior change, instead of drifting in an external fork.

Test plan

• doorstop on assets/example_reqs/ exits 0 after doorstop review all
• doorstop publish REQ /tmp/out.md produces correct Markdown
• doorstop export REQ /tmp/out.csv round-trips
• scripts/doorstop_snapshot.py --pretty emits valid JSON with valid: true
• scripts/doorstop_lint.sh wraps doorstop -e -Z and exits 0 on the example tree
• SKILL.md frontmatter description ≤ 200 chars

Scope

• No existing files modified
• No runtime/import dependencies added to Doorstop itself
• All content is under skills/doorstop/

🤖 Generated with Claude Code

[aelaguiz]

Follow-up commit 6ca8dd4 fixes a regression the smoke test surfaced: the bundled example_reqs/ tree is a live Doorstop project, so a plain doorstop run at the Doorstop repo root tried to merge it with the project's own reqs/ and failed with "multiple root documents".

Fix: added skills/doorstop/assets/.doorstop.skip-all to prune the asset subtree from doorstop/core/builder.py's os.walk. The marker sits above the example tree so it stays behind when users copy the example into a new project.

Verified:

• doorstop at the Doorstop repo root no longer errors on the example tree (the pre-existing TUT/EXT warnings in develop are unrelated).
• The standalone example still validates clean after cp -r example_reqs/. /new/repo.

Also documented the .doorstop.skip-all mechanism under references/troubleshooting.md → "multiple root documents" since it's a general-purpose feature.