Add Doorstop Agent Skill package for AI coding agents#1
Merged
Conversation
Adds `skills/doorstop/`, a comprehensive, progressively-disclosed Agent Skill
that teaches any compatible AI coding agent (Claude Code, Cursor, Gemini CLI,
Codex CLI, Antigravity) how to use Doorstop end to end.
Layout:
- SKILL.md — compact entry point (<200-char always-on description)
- references/ — 10 lazy-loaded deep references covering every CLI subcommand,
the Python API, `.doorstop.yml` + item YAML/Markdown schemas, end-to-end
workflows, the full validation severity matrix, publishing, CSV/TSV/XLSX
round-trip, REST server endpoints, custom validator extensions, and a
troubleshooting decision tree
- scripts/doorstop_snapshot.py — dumps the tree, items, links, and issues
as JSON for agent reasoning
- scripts/doorstop_lint.sh — CI-friendly `doorstop -e -Z` gate
- assets/example_reqs/ — tiny two-document example tree (REQ + TST, one link,
one heading) that validates clean
Installable across agents via the OpenSkills universal installer:
npx openskills install doorstop-dev/doorstop # project-local
npx openskills install doorstop-dev/doorstop --global # global
The skill lives inside this repo so it versions with Doorstop itself — when
the CLI surface, file format, or Python API changes, the matching reference
can be updated in the same PR. No Doorstop source files are modified.
The bundled `skills/doorstop/assets/example_reqs/` tree is a live Doorstop
project — a teaching fixture for the skill. When this skill is installed in a
repo that is itself a Doorstop project (including the Doorstop repo itself), a
plain `doorstop` run at the repo root walks into the example tree and tries to
merge it with the host project, failing with:
ERROR: multiple root documents:
- REQ: /.../reqs
- REQ: /.../skills/doorstop/assets/example_reqs/reqs
Fix: drop a `.doorstop.skip-all` marker at `skills/doorstop/assets/`, which
prunes the whole asset subtree from the `os.walk` in
`doorstop/core/builder.py`. The marker sits one level *above* the example
tree, so users who copy the example into a new project (`cp -r
example_reqs/. /new/repo`) leave the marker behind — their copied tree is
discovered normally.
Also document the mechanism in `references/troubleshooting.md` ("multiple
root documents") and note the rationale in `assets/example_reqs/README.md`.
Author
|
Follow-up commit 6ca8dd4 fixes a regression: the bundled Added |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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. Pure addition under a new top-levelskills/directory — no existing Doorstop source, tests, or docs are modified.Mirrors the upstream PR opened against
doorstop-dev/doorstop:develop(doorstop-dev#755).What's in the skill
SKILL.md— compact entry point, always-on description ≤ 200 charsreferences/— 10 lazy-loaded deep references (cli-commands, python-api, file-formats, workflows, validation, publishing, import-export, server-api, extensions, troubleshooting)scripts/doorstop_snapshot.py— dumps tree/items/links/issues as JSON for agent reasoningscripts/doorstop_lint.sh— CI-friendlydoorstop -e -Zwrapperassets/example_reqs/— tiny two-document tree (REQ + TST, one link, one heading) that validates cleanInstall
Once merged (locally, or when upstream merges):
Test plan
doorstoponassets/example_reqs/exits 0 afterdoorstop review alldoorstop publish REQ /tmp/out.mdproduces correct Markdowndoorstop export REQ /tmp/out.csvround-tripsscripts/doorstop_snapshot.py --prettyemits valid JSON withvalid: truescripts/doorstop_lint.shwrapsdoorstop -e -Zand exits 0 on the example treeSKILL.mdfrontmatter description ≤ 200 chars🤖 Generated with Claude Code