Skip to content
Back to search

agent-workflow-skills

Reusable skills for coding agents: plan, debug, review, resume, and verify software work.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/msalomonn--agent-workflow-skills/badge.svg)](/listings/msalomonn--agent-workflow-skills)

HTML

<a href="/listings/msalomonn--agent-workflow-skills"><img src="/api/listings/msalomonn--agent-workflow-skills/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 264 lines
  1. # Agent Workflow Skills
  2. **Reusable skills for coding agents: define the work, resume with context, and verify what shipped.**
  3. [Español](README.es.md) · [Download v0.1.1](https://github.com/msalomonn/agent-workflow-skills/releases/tag/v0.1.1) · [Installation](docs/installation.md) · [Usage examples](#usage-examples) · [Try the demo](examples/cart/README.md) · [Validation](docs/validation.md) · [MIT License](LICENSE)
  4. Agent Workflow Skills is a collection of 12 focused instructions for everyday software work. Each exported skill carries its own references and templates. Use one skill for a specific task, or combine them around your existing development process.
  5. The toolkit keeps acceptance criteria, repository state, and verification connected. It helps an agent distinguish a completed implementation from a merged PR, a deployment, or an accepted delivery—and resume work without treating yesterday's checkpoint as today's truth.
  6. ## Start small
  7. Requirements: Git and Python 3.9+ to prepare the package, and a coding agent that supports `SKILL.md` folders. The export tool uses only the Python standard library and makes no network requests. Your agent supplies its own tools and credentials.
  8. ```sh
  9. git clone https://github.com/msalomonn/agent-workflow-skills.git
  10. cd agent-workflow-skills
  11. python3 scripts/export_skills.py --output dist/starter \
  12. --skill workflow-debug --skill workflow-verify --skill workflow-handoff
  13. python3 scripts/export_skills.py --verify dist/starter
  14. ```
  15. Copy the **complete exported skill folders** into your agent's project skill directory. For Codex, that directory is `.agents/skills/`. Check for existing folders before copying; retain any customizations. Follow the [installation guide](docs/installation.md) for a full package, existing installations, updates, and compatibility limits.
  16. Then ask, for example:
  17. ```text
  18. Use workflow-debug to reproduce and fix the failing total in this project.
  19. Keep the change scoped to the bug and record before/after verification.
  20. ```
  21. The [cart demo](examples/cart/README.md) provides a small local task with a real failing test. No account, API key, or hosted demo is needed for that exercise.
  22. ## Choose a skill
  23. | Skill | Useful when you need to… | Example |
  24. | --- | --- | --- |
  25. | [workflow-spec](skills/workflow-spec/SKILL.md) | Define observable behavior and acceptance criteria. | [View example](#workflow-spec) |
  26. | [workflow-plan](skills/workflow-plan/SKILL.md) | Turn agreed scope into reviewable steps. | [View example](#workflow-plan) |
  27. | [workflow-execute](skills/workflow-execute/SKILL.md) | Implement or resume authorized work. | [View example](#workflow-execute) |
  28. | [workflow-debug](skills/workflow-debug/SKILL.md) | Reproduce a failure and test its cause. | [View example](#workflow-debug) |
  29. | [workflow-audit](skills/workflow-audit/SKILL.md) | Review a diff and report substantiated defects. | [View example](#workflow-audit) |
  30. | [workflow-verify](skills/workflow-verify/SKILL.md) | Check evidence before declaring completion. | [View example](#workflow-verify) |
  31. | [workflow-doctor](skills/workflow-doctor/SKILL.md) | Diagnose setup, missing tools, or integration access. | [View example](#workflow-doctor) |
  32. | [workflow-triage](skills/workflow-triage/SKILL.md) | Classify requests and select the next action. | [View example](#workflow-triage) |
  33. | [workflow-research](skills/workflow-research/SKILL.md) | Investigate a technical decision with sources. | [View example](#workflow-research) |
  34. | [workflow-github-status](skills/workflow-github-status/SKILL.md) | Reconcile issues, PRs, checks, and remaining work. | [View example](#workflow-github-status) |
  35. | [workflow-handoff](skills/workflow-handoff/SKILL.md) | Save or resume a recoverable checkpoint. | [View example](#workflow-handoff) |
  36. | [workflow-release](skills/workflow-release/SKILL.md) | Prepare or publish a release within project policy. | [View example](#workflow-release) |
  37. A typical feature might use spec → plan → execute → audit → verify. A clear bug can start at debug. Handoff supports either flow. These are entry points, not a mandatory sequence.
  38. ## Usage examples
  39. Install each named skill before using its example; the starter command above installs only debug, verify, and handoff. The [installation guide](docs/installation.md) explains exporting the full collection or a selection. Paste the prompts into your coding agent, replacing illustrative filenames, versions, and repository names with your project's actual context.
  40. A useful request identifies the outcome, relevant files or issue, constraints, and whether you want analysis or implementation. Add available tests, logs, or acceptance criteria. The outputs below describe the intended deliverable; its detail depends on the task and available tools.
  41. ### workflow-spec
  42. Use it when a request needs clearer behavior before implementation. Supply the current behavior, user need, constraints, and any existing specification. It examines the implementation to avoid specifying work that is already done.
  43. ```text
  44. Use workflow-spec to define retries for failed CSV imports.
  45. Inspect importer.py and the existing requirements. A failed import can leave
  46. some rows saved; we have not decided whether retries skip or replace them.
  47. Define acceptance criteria and failure cases, and identify that decision.
  48. Write the proposal in docs/import-retries.md; do not implement it yet.
  49. ```
  50. **Expected result:** observable behavior, testable acceptance criteria, exclusions, dependencies, and unresolved decisions. If one decision blocks only part of the work, the specification identifies that boundary.
  51. ### workflow-plan
  52. Use it to turn agreed scope into implementation steps or update an existing plan. Supply the acceptance criteria and current plan, if one exists. The skill checks actual progress before scheduling more work.
  53. ```text
  54. Use workflow-plan with docs/import-retries.md and docs/plan.md.
  55. The CSV reader may already be implemented; verify that in the repository.
  56. Plan the remaining work with step IDs, dependencies, affected interfaces,
  57. and a check for each outcome. Keep unresolved retry decisions explicit.
  58. Update docs/plan.md without implementing the feature.
  59. ```
  60. **Expected result:** a concise plan that preserves completed work, covers acceptance criteria, identifies conditional steps, and names the next executable action.
  61. ### workflow-execute
  62. Use it when the change is clear and implementation is authorized. Supply the agreed scope, relevant plan or checkpoint, and verification command when known. It reconciles those artifacts with current code and preserves unrelated edits.
  63. ```text
  64. Use workflow-execute to implement the agreed input-size limit in
  65. docs/import-retries.md. Inspect docs/plan.md and continue the unfinished step.
  66. Preserve my unrelated UI changes. Add the relevant boundary tests and run
  67. the importer tests. Keep the change local and update the checkpoint.
  68. ```
  69. **Expected result:** the scoped implementation, verification results tied to the current change, and a checkpoint describing completed and remaining work. PR preparation is included only when sharing a PR is part of the request.
  70. ### workflow-debug
  71. Use it for a reproducible bug or an intermittent failure with available evidence. Supply expected versus actual behavior, triggering input, environment, and logs or tests. Say whether you want diagnosis only or a correction.
  72. For this example, prepare the disposable project described in the [cart demo](examples/cart/README.md), install the skill there, and open your agent in that project.
  73. ```text
  74. Use workflow-debug in this cart project. Quantities above one produce the wrong
  75. total, and a zero-quantity item must contribute zero.
  76. Reproduce with python3 -B -m unittest -v from the project root, identify the
  77. cause, and fix it. Preserve the existing input contract and verify all cases.
  78. ```
  79. **Expected result:** a reproduction, evidence supporting the cause, the authorized fix, and before/after results. For an unresolved failure, it reports the remaining uncertainty and the observation needed next.
  80. ### workflow-audit
  81. Use it to review a diff or PR for actionable defects. Supply the base and target revision or PR link, intended behavior, and acceptance criteria. A full diff and surrounding code provide more coverage than an isolated snippet.
  82. ```text
  83. Use workflow-audit to review the current branch against origin/main.
  84. The change should apply percentage discounts using integer cents.
  85. Check rounding and boundary inputs, and reproduce suspected regressions.
  86. Report findings with file, line, trigger, impact, and supporting evidence.
  87. Keep this a review only; do not edit code or post GitHub comments.
  88. ```
  89. **Expected result:** confirmed findings ordered by impact, the reviewed revision, and coverage gaps. Style preferences are separated from defects; an absence of findings is not formal approval or proof that no bugs exist.
  90. ### workflow-verify
  91. Use it before declaring work complete. Supply the acceptance criteria, target revision, and available test, review, or deployment evidence. It checks whether that evidence still applies and runs missing checks within scope.
  92. ```text
  93. Use workflow-verify to assess the import change against
  94. docs/import-retries.md. Check whether the recorded tests cover the current
  95. HEAD and run missing local checks. The PR is merged, but production has
  96. not been inspected. Report what is verified, failed, or still pending.
  97. Do not deploy or close the issue.
  98. ```
  99. **Expected result:** a criterion-by-criterion evidence table, explicit failures or gaps, and the next action. Implementation, merge, deployment, and acceptance remain separate claims.
  100. ### workflow-doctor
  101. Use it when onboarding or when setup, tooling, or access blocks a task. State what you are trying to do and include the failure message if available. The skill checks only the capabilities that task needs.
  102. ```text
  103. Use workflow-doctor to check whether this repository is ready for local
  104. Python development. Inspect repository instructions, runtime, documented
  105. test commands, and installed workflow skill resources.
  106. GitHub access is optional for this task. Diagnose setup without changing
  107. configuration, and report the smallest remedy for each blocker.
  108. ```
  109. **Expected result:** checks marked ready, failed, unknown, or not applicable, with evidence and remedies. It distinguishes missing tools, wrong targets, authentication failures, and network errors without exposing credential values.
  110. ### workflow-triage
  111. Use it to organize incoming requests or a backlog before starting work. Supply the queue, existing issues, and known impact. It looks for duplicates and selects the next useful action without inventing urgency or ownership.
  112. ```text
  113. Use workflow-triage on requests.md and the existing issues in backlog.json.
  114. Two requests ask to retry failed imports; another asks for progress updates.
  115. Identify likely duplicates, missing context, and the next action for each.
  116. Return a table with evidence and suggested priority. Do not create or close
  117. tickets, assign people, or start implementation.
  118. ```
  119. **Expected result:** a compact table of requests, classifications, evidence, suggested priorities, related items, and next actions. Missing impact or incomplete queue access is stated explicitly.
  120. ### workflow-research
  121. Use it when a technical choice needs evidence. Supply the decision, runtime or dependency constraints, and existing implementation. The skill compares viable options using primary sources and bounded experiments where useful.
  122. ```text
  123. Use workflow-research to choose a CSV parsing approach for this project.
  124. We require Python 3.9+, quoted commas and newlines, and no third-party
  125. runtime dependencies. Inspect the current reader and compare it with the
  126. suggestion to split lines on commas. Consult version-relevant official docs
  127. and run a small parsing experiment. Recommend an approach without changing
  128. the application or installing dependencies.
  129. ```
  130. **Expected result:** a recommendation, alternatives, linked sources, documented facts versus inferences, and the smallest remaining experiment. Research does not automatically begin implementation.
  131. ### workflow-github-status
  132. Use it for an evidence-based view of a specific repository's issues, PRs, checks, and blockers. Supply the exact repository and scope or time range. Live status requires a configured GitHub connector or CLI with read access; supplied snapshots support a limited report.
  133. ```text
  134. Use workflow-github-status for owner/repository, focusing on open issues
  135. and PRs merged during the last seven days. Inspect linked checks and
  136. remaining acceptance criteria. Separate merged code from deployment and
  137. verified delivery. Include links, observation time, blockers, and next
  138. actions. Keep this read-only; do not update issues or send a standup.
  139. ```
  140. **Expected result:** a status summary separating completed outcomes, ongoing work, dependencies, and unknowns. It checks whether green results cover the current revision and states pagination or access limits.
  141. ### workflow-handoff
  142. Use it to save progress or resume an authorized task in a fresh session. Supply the task and current artifacts when saving, or the checkpoint when resuming. A checkpoint records evidence; current repository state determines what remains.
  143. ```text
  144. Use workflow-handoff to save this task in docs/checkpoint.md.
  145. Record HEAD, uncommitted changes, decisions, completed checks, remaining
  146. work, and the first next action. Use repository-relative artifact paths.
  147. ```
  148. In a later session:
  149. ```text
  150. Use workflow-handoff to resume docs/checkpoint.md and finish the local fix.
  151. Compare the checkpoint with the current branch and working tree first;
  152. another contributor may have completed part of the work. Preserve unrelated
  153. edits and rerun only checks invalidated by the changes or still missing.
  154. ```
  155. **Expected result:** a recoverable checkpoint, or a reconciliation note followed by the next authorized unfinished step. Saving context alone does not send it to anyone or authorize future implementation.
  156. ### workflow-release
  157. Use it to prepare a versioned release or publish one when explicitly requested. Supply the intended version or outcome, target revision, and project release policy. The skill distinguishes preparation, draft, publication, and deployment.
  158. ```text
  159. Use workflow-release to prepare the next patch release from the current
  160. HEAD. Inspect the project's versioning policy and previous release.
  161. Update version metadata and changelog, check tests and reviews against the
  162. target commit, and prepare release notes with recovery guidance.
  163. Do not create a remote tag, publish a release, or deploy.
  164. ```
  165. **Expected result:** consistent version metadata and notes, target commit, readiness checks, and unresolved publication conditions. When publication is separately requested, it checks existing tags/releases first and verifies the resulting target and assets afterward.
  166. ## Combine skills around an outcome
  167. | Situation | Useful sequence | What each step adds |
  168. | --- | --- | --- |
  169. | An ambiguous feature | spec → plan → execute → audit → verify | Agreed behavior, actionable steps, implementation, defect review, and acceptance evidence. |
  170. | A broken calculation | debug → verify | Reproduction and correction, then a check against the full acceptance criteria. |
  171. | Work interrupted between sessions | handoff → execute → verify | Reconciled context, only the unfinished implementation, and current evidence. |
  172. | A release candidate | audit → verify → release | Findings, revision-specific readiness, and release preparation or authorized publication. |
  173. Use only the steps the task needs. Existing decisions and still-valid test results carry forward; naming a sequence does not grant permission to publish or deploy.
  174. ## How it fits your project
  175. - **Project conventions stay in the project.** No required branch names, tracker, cloud provider, or team structure.
  176. - **Context survives a session.** Optional templates capture acceptance, decisions, observed revision, evidence, and the next action.
  177. - **Skills remain independent.** Export all 12 or a selection; no dependency on another installed skill.
  178. - **Tools remain yours.** GitHub-specific operations use an available connector or CLI. Other skills can work locally.
  179. - **Permissions remain explicit.** Instructions do not grant credentials or replace the agent host's controls. Existing user authorization is reused.
  180. This is an instruction toolkit, not an autonomous service, an enforcement system, or a model. Results depend on the agent, tools, repository, and task. Version 0.1.1 includes 21 package tests, observations from four independent agent sessions covering all 12 skills, and a native Codex discovery check. These results do not establish a measured productivity improvement or universal client compatibility. See [validation and limits](docs/validation.md).
  181. ## Develop and contribute
  182. ```sh
  183. python3 scripts/check_repository.py
  184. ```
  185. Edit `skills/` and `workflow/`, then export again. Generated bundles belong in `dist/` and are not committed. The [contribution guide](CONTRIBUTING.md) explains how to propose a focused change and evaluate it.
  186. Created and maintained by [Manuel Salomon](https://github.com/msalomonn). Free to use, modify, and share under the [MIT license](LICENSE).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.