Reusable agent skills for previews, technical teaching, project documentation and client quotations.
| Skill | Purpose |
|---|---|
| pr-preview | Create or operate an on-demand PR/worktree preview using a project's production build path. |
| teaching-with-diagrams | Teach technical concepts through grounded explanations, practice and Mermaid diagrams. Combines reviewed practices from three upstream skills with update tracking. |
| readme-value | Help first-time visitors understand a project's use, evidence and next step, with concrete proposals when its value is still unproven. |
| client-quotation | Prepare a service quotation and matching plain-language scope attachment; includes blank editable ODT templates. |
| flow-docs-sync | Create navigable system/feature flows and establish mandatory source, diagram and review synchronization controls. |
Install with npx --yes [email protected] add CloudWorkTools/skills --skill flow-docs-sync --agent codex --yes, then ask:
Use $flow-docs-sync to establish a system overview and per-feature flows with source-file/symbol navigation. Make synchronous updates mandatory and verify the project's CI and merge controls.
The default synchronization boundary is PR delivery: defer generation during Draft/WIP work, synchronize when ready for review, and revalidate subsequent candidates before merge. Projects without PRs use commit preparation. Automatic CI generation requires a project-specific AI runner; none is bundled. See delivery triggers.
The skill bundles a Python checker, optional strict staged pre-commit template, inline AGENTS.md bootstrap and fresh-subagent review prompt. It combines file MD5 integrity with symbol/context hashes: native Python or optional Tree-sitter adapters for JS/TS/TSX, Go, Rust, Java, C#, C/C++, GDScript, SQL, Prisma and JSON. Other formats use explicit file-level coverage. See the checker contract and language boundaries.
Adoption requires the root reading rule, real feature/source mappings and project-specific CI/merge controls. Installing the skill only copies resources. Headless graph/complexity checks do not prove visual readability; an agent review record does not replace repository-required human approval.
Shared rules live in AGENTS.md, with verified agent-specific imports when needed. Start with a core end-to-end feature and its dependencies; the adoption guide covers entrypoints, mixed-language choices, evidence templates and completion reporting. The colored workflow explains how AST filtering avoids cosmetic-only redraw/review obligations while retaining candidate checks.
Install with npx --yes [email protected] add CloudWorkTools/skills --skill client-quotation --agent codex --yes. Use $client-quotation to draft or revise a quotation and scope attachment that share one identifier, show payment milestones clearly, and describe UI review and agreed adjustments. The bundled ODT templates contain field prompts only; replace them with authorized project details before delivery.
Install from this checkout with npx --yes [email protected] add . --skill readme-value --agent codex --yes, then ask:
用 $readme-value 改善這個 repo 的 README，讓第一次來、沒有專業背景的人看懂用途、目前成果與如何開始。把深入技術內容放到延伸文件；價值還未驗證的部分，提出具體且標示為建議的未來工作。
The skill adapts audience guidance from crafting-effective-readmes, benefit analysis from value-proposition and document organization from documentation-writer. It is independent of the teaching skill and includes its own upstream checker. See sources, adaptations and maintenance.
Run npm run skills:check-readme-updates in this repository, or node <skill-directory>/scripts/check-upstreams.mjs after installation. The weekly workflow checks both skills independently. README updates use a separate Draft PR and .github/upstream-reviews/readme-value.md; source adoption requires review before advancing the baseline.
Install the composite skill in your project:
npx --yes [email protected] add CloudWorkTools/skills --skill teaching-with-diagrams --agent codex --yesThen ask:
用 $teaching-with-diagrams，把這個模型的 README 整理成繁體中文初學者教材，加入 Mermaid 流程圖、數值例子與有解答的小練習，保留操作指南的入口。
The skill combines teach (learning outcomes and practice), documentation-writer (Diátaxis structure) and mermaid-diagrams (visual explanation) into a self-contained adaptation. It supports one-off Markdown documents as well as an explicitly requested ongoing course. The three original skills do not need to be installed separately. See composition, source links and maintenance decisions.
In this repository:
npm run skills:check-updatesAfter installing the skill, ask the agent to check its upstream updates, or run:
node .agents/skills/teaching-with-diagrams/scripts/check-upstreams.mjsNode.js 22+ and GitHub network access are required. The checker compares each complete skill directory and root license with the reviewed baseline. It prints changes and compare links without modifying files. Exit codes are 0 unchanged, 2 updates available, and 1 check failure. GH_TOKEN or GITHUB_TOKEN is optional for authenticated API rate limits.
Check skill upstreams runs every Monday at 03:17 UTC (11:17 Asia/Taipei) and can be run manually from Actions. When updates are found, it opens or updates one Draft PR, assigned to jhihweijhan, containing a report, comparison links and a review checklist. Find it in Pull requests or GitHub notifications; email delivery depends on your GitHub notification settings. No AI key is needed: the workflow uses its built-in GITHUB_TOKEN.
The PR is a notification, not a completed adaptation. Ask your agent to review and adapt the upstream changes on that PR branch, test them, and update the reviewed baseline before marking it ready. The automation only writes .github/upstream-reviews/teaching-with-diagrams.md; it preserves other files and your PR description. Identical batches cause no report commit, closed batches are not reopened automatically, and non-draft PRs are left untouched. Reopen a dismissed PR manually to reconsider it. If updates disappear, close the stale PR manually. Check failures stop PR writes and remain visible in Actions.
Organization and repository settings must allow Actions to create pull requests. The workflow grants only contents: write and pull-requests: write to its notification job, runs on the default branch, and never automatically merges or advances the lock. Follow the review and adoption procedure. Schedule timing depends on GitHub Actions availability.
Run this in the project where you want to use the skill:
npm exec --yes [email protected] -- skills add CloudWorkTools/skills --skill pr-preview --agent codex --yesEquivalent npx command:
npx --yes [email protected] add CloudWorkTools/skills --skill pr-preview --agent codex --yesFor Claude Code, replace --agent codex with --agent claude-code. Add --global for user-level installation. These options use the standard skills npm CLI, which installs the skill and its references into the agent's skill directory.
You can also install this repository as an npm dependency from GitHub, then register the skill:
npm install --save-dev github:CloudWorkTools/skills
npm exec --yes [email protected] -- skills add ./node_modules/@cloudworktools/skills --skill pr-preview --agent codex --yesThe package is distributed through GitHub; it is not published under @cloudworktools/skills on the npm registry. Installation copies agent guidance; it does not start containers or modify deployment configuration.
Ask your agent:
Use $pr-preview to preview PR #42 for manual review, using this project's production build path. Verify the source revision, login and assets, and give me the cleanup command.
Or:
用 $pr-preview 預覽目前 worktree（含未 commit 修改），確認與生產建置路徑一致。檢視完後清理這一站，保留其他環境。
The agent inspects and reuses the target project's preview script, or creates/adapts one using the included implementation contract. It covers exact PR revisions, distinct worktree identities, readiness failures, private state, offline logs/teardown, and cleanup verification.
Preview execution needs Git, Docker Compose, and a dedicated preview host/daemon. Use trusted code and preview-only credentials/data. Production parity depends on the project's actual deployment overlays, data, and external services; container naming alone is not a security boundary.
- pr-preview skill
- Implementation contract
- Teaching with diagrams skill
- Teaching composition and update tracking
npm testNode.js 22+, npm, Python 3.10+ and Git are required for the full test suite. They pack the repository, install the tarball into temporary projects, install each skill through the real npm CLI, and verify every resource is copied intact and discoverable. Update-check tests cover reference changes, additions/deletions, license changes, unrelated commits and failed API calls. Flow-checker tests use temporary Git repositories, including real hook rejection and staged checks. Optional cross-language tests require the pinned parser packages; set FLOW_REQUIRE_TREE_SITTER=1 in the test environment to fail rather than skip when they are missing. The tests leave user-level skills and Docker workloads untouched. Network access is needed to obtain the pinned CLI if it is not cached.
The portable guidance was developed from the PR preview work in MUAMS PR #71; MUAMS-specific service names, credentials, and deployment settings are not bundled.
PR tests run through .github/workflows/tests.yml. See contributor checks for installed-link validation, flow behavior review cases and global skill receipts.