DeepWorkPlan — Author
Author and maintain the current repository's agent kit: reusable skills, agents, and
commands. Reason about the repo — never copy a generic kit. This sub-skill is also the executor of
the mandatory "Skills & Agents Discovery" plan task.
Concepts
- Skill — a reusable, parameterized procedure invoked in-session (e.g.
/fix-lint). Encodes
"how to do X". Lives in <skills-dir>/<name>/SKILL.md.
- Agent — a specialized worker definition (role, model tier, tools, system prompt) dispatched to
handle a class of tasks (e.g.
reviewer, executor). Encodes "who does X". Lives in
<agents-dir>/<name>.md.
- Command — a thin slash-command entry point that routes to a skill or agent. Logic stays in the
skill/agent; the command is a delegator.
| Need |
Create |
| A repeatable procedure run in-session |
Skill |
| A persistent role with its own model tier / tools |
Agent |
| A shortcut to invoke a skill or agent |
Command |
Step 0 — Detect the repo layout (do NOT assume)
Before authoring anything, discover where this repo keeps its kit. Do not hardcode any single repo's
conventions.
- Find the agent root: look for
.agents/, then .claude/ or .cursor/ (often symlinks to .agents/), then any
AGENTS.md / CLAUDE.md at the repo root for documented paths.
- Within it, locate
skills/, agents/, commands/, and a catalog under docs/.
- Inspect 1-2 existing skills/agents to learn the repo's local conventions (frontmatter keys it
uses, naming, body structure, whether commands are thin delegators). Match them.
ls -d .agents .claude 2>/dev/null
ls .agents/skills .agents/agents .agents/commands .agents/docs 2>/dev/null
ls AGENTS.md CLAUDE.md 2>/dev/null
If the repo has no .agents/ layout yet, route the developer to the onboard sub-skill first
(onboard/SKILL.md) — onboarding scaffolds the directories this sub-skill writes into.
Trust boundary (write scope)
allowed-tools includes write-capable Edit, Write, and Bash.
Writes: new or updated files only under the repo's .agents/ kit —
skills/*/SKILL.md, agents/*.md, commands/*.md, docs/ catalogs — plus the
catalog index entries that keep them discoverable. Broad additions (a new skill
family, restructuring the kit) are proposed to the developer before creation.
It MUST NOT: edit files outside .agents/ (a skill's content may
document anything; this sub-skill writes only kit files), weaken the frontmatter
conventions (name, quoted version:, documentation_url, kebab-case), delete
an existing skill/agent/command without explicit approval, or commit/push.
Flows
Pick the flow that matches the developer's intent.
A. Create a skill
- Audit fit — confirm a real, repeatable workflow exists (see "Repo-fit rubric" below). Skip
generic skills that do not match an actual workflow.
- Name it — kebab-case, English, unique. Check for collisions in the skills dir.
- Scaffold — copy
templates/SKILL_TEMPLATE.md into <skills-dir>/<name>/SKILL.md. Adapt the
frontmatter to the repo's local convention (keys it already uses).
- Fill — one-procedure focus; clear Goal, When-to-use, Steps, Validation.
- Keep commands thin — if it needs a slash command, add a delegator (see Flow C).
- Catalog — update the repo's catalog under the docs dir (see "Keep the catalog in sync").
- Validate — naming, structure, frontmatter, and that any command is thin.
B. Create an agent
- Confirm a recurring role with distinct model/tools needs (not just a one-off procedure → that
is a skill).
- Name it — kebab-case, English, unique.
- Scaffold — copy
templates/AGENT_TEMPLATE.md into <agents-dir>/<name>.md.
- Choose a model tier — reason about it (see "Model tiers" below). Do NOT hardcode vendor model
IDs inside the agent body; keep the abstract tier and map it in repo config.
- Fill — Role, Inputs, Process, Output, escalation rules.
- Catalog — update the catalog under the docs dir.
- Validate — naming, structure, tier chosen with justification.
C. Create a command (thin delegator)
- Confirm the target skill or agent exists.
- Add
<commands-dir>/<cmd>.md as a ~20-line delegator: read the target skill/agent fresh and follow
it, passing along args. Do NOT embed logic — logic lives in the skill/agent so updates propagate.
- Reference the new command in the catalog / commands reference.
D. Update an existing skill / agent / command
- Read the existing file and the repo's conventions first.
- Make the smallest change that satisfies the request; preserve frontmatter the repo relies on.
- Keep delegators thin; keep skills single-procedure.
- Update the catalog if name, description, or surface changed.
E. Evaluate the catalog (Skills & Agents Discovery)
This is the flow invoked by the mandatory plan task.
- Enumerate every skill (
<skills-dir>/*/SKILL.md) and agent (<agents-dir>/*.md).
- For each, capture name, one-line description, and model tier (if any).
- Cross-check against the repo's catalog under the docs dir: flag missing entries, stale
descriptions, orphaned commands, and duplicates.
- Reconcile: update the catalog so it matches reality. Report drift found and fixed.
Repo-fit rubric (before creating)
Gather: stack & tooling (languages, frameworks, package manager, test runner, linter); workflows (how
code is built, tested, reviewed, released); pain points (repetitive manual steps); the existing kit
(avoid duplicates). Then:
- Create a skill for a repeatable procedure people do by hand.
- Create an agent for a recurring role with distinct model/tools needs.
- Create a command only as a thin entry point.
- Skip anything generic that does not match a real workflow.
Anti-patterns to avoid: generic kits that do not match the repo; fat commands with embedded logic;
duplicates of existing skills/agents; agents pinned to vendor model IDs in their bodies.
Model tiers (for agents)
Skills inherit the session model; agents may pin an abstract tier.
| Tier |
Use for |
Examples |
| light |
Mechanical, well-specified, low-judgment tasks |
formatting, lint fixes, renames, list/status commands |
| standard |
Most engineering work; moderate reasoning |
feature work, refactors, test writing, reviews |
| heavy |
High-judgment, architectural, ambiguous tasks |
architecture, security audits, complex planning |
How to choose: default to standard; drop to light only if mechanical and well-specified; raise
to heavy only for deep reasoning or high blast radius. Keep tiers abstract — map them to concrete
model IDs in the repo's runtime/config, in one place, never inside skill bodies.
Keep the catalog in sync
After any create/update, reconcile the repo's catalog (commonly under the docs dir, e.g. a
skills/agents catalog and a commands reference). Add or update the row for the affected skill/agent/
command: name, one-line description, tier (agents), and the command that invokes it. The catalog must
always match what is on disk.
Templates
templates/SKILL_TEMPLATE.md — skill scaffold.
templates/AGENT_TEMPLATE.md — agent scaffold.
Reference them by these relative paths. Adapt the frontmatter to the host repo's local convention
(some repos add version, documentation_url, or user-invocable; match what neighboring files use).
Validation
- Names are kebab-case, English, unique.
- Frontmatter matches the repo's convention; descriptions are a single line starting with a verb.
- Skills are single-procedure; agents declare a justified tier (no hardcoded vendor model IDs).
- Commands are thin delegators with no embedded logic.
- The catalog under the docs dir reflects every change.
Notes
- Reason about the repo; never copy a generic kit.
- Propose before creating when scope is broad — confirm the short list with the developer first.
- All references inside the skill are relative; nothing outside the skill root is required at runtime.
1---2name: deepworkplan-author-43description: Author or update reusable skills, agents, and commands in the current repo — reason about the repo's .agents/ layout, follow the Open Agent Skills frontmatter contract, and keep the .agents/docs/ catalog in sync. Use when a developer wants to create or evolve the repo's agent kit (skills, agents, commands), or runs /skill-create or /agent-create.4version: "2.17.0"5documentation_url: https://deepworkplan.com6user-invocable: true7allowed-tools: Bash, Read, Grep, Glob, Edit, Write8metadata:9 source: https://skillmd.com/skills/dailybothq/deepworkplan-author-410---1112# DeepWorkPlan — Author1314Author and maintain the current repository's **agent kit**: reusable **skills**, **agents**, and15**commands**. Reason about the repo — never copy a generic kit. This sub-skill is also the executor of16the mandatory "Skills & Agents Discovery" plan task.1718---1920## Concepts2122- **Skill** — a reusable, parameterized *procedure* invoked in-session (e.g. `/fix-lint`). Encodes23 "how to do X". Lives in `<skills-dir>/<name>/SKILL.md`.24- **Agent** — a specialized *worker definition* (role, model tier, tools, system prompt) dispatched to25 handle a class of tasks (e.g. `reviewer`, `executor`). Encodes "who does X". Lives in26 `<agents-dir>/<name>.md`.27- **Command** — a thin slash-command entry point that routes to a skill or agent. Logic stays in the28 skill/agent; the command is a delegator.2930| Need | Create |31|------|--------|32| A repeatable procedure run in-session | Skill |33| A persistent role with its own model tier / tools | Agent |34| A shortcut to invoke a skill or agent | Command |3536---3738## Step 0 — Detect the repo layout (do NOT assume)3940Before authoring anything, discover where this repo keeps its kit. Do not hardcode any single repo's41conventions.42431. Find the agent root: look for `.agents/`, then `.claude/` or `.cursor/` (often symlinks to `.agents/`), then any44 `AGENTS.md` / `CLAUDE.md` at the repo root for documented paths.452. Within it, locate `skills/`, `agents/`, `commands/`, and a catalog under `docs/`.463. Inspect 1-2 existing skills/agents to learn the repo's **local conventions** (frontmatter keys it47 uses, naming, body structure, whether commands are thin delegators). Match them.4849```bash50ls -d .agents .claude 2>/dev/null51ls .agents/skills .agents/agents .agents/commands .agents/docs 2>/dev/null52ls AGENTS.md CLAUDE.md 2>/dev/null53```5455If the repo has no `.agents/` layout yet, route the developer to the **onboard** sub-skill first56(`onboard/SKILL.md`) — onboarding scaffolds the directories this sub-skill writes into.5758## Trust boundary (write scope)5960`allowed-tools` includes write-capable `Edit`, `Write`, and `Bash`.6162**Writes:** new or updated files **only** under the repo's `.agents/` kit —63`skills/*/SKILL.md`, `agents/*.md`, `commands/*.md`, `docs/` catalogs — plus the64catalog index entries that keep them discoverable. Broad additions (a new skill65family, restructuring the kit) are proposed to the developer before creation.6667**It MUST NOT:** edit files outside `.agents/` (a skill's *content* may68document anything; this sub-skill writes only kit files), weaken the frontmatter69conventions (`name`, quoted `version:`, `documentation_url`, kebab-case), delete70an existing skill/agent/command without explicit approval, or commit/push.7172---7374## Flows7576Pick the flow that matches the developer's intent.7778### A. Create a skill79801. **Audit fit** — confirm a real, repeatable workflow exists (see "Repo-fit rubric" below). Skip81 generic skills that do not match an actual workflow.822. **Name it** — kebab-case, English, unique. Check for collisions in the skills dir.833. **Scaffold** — copy `templates/SKILL_TEMPLATE.md` into `<skills-dir>/<name>/SKILL.md`. Adapt the84 frontmatter to the repo's local convention (keys it already uses).854. **Fill** — one-procedure focus; clear Goal, When-to-use, Steps, Validation.865. **Keep commands thin** — if it needs a slash command, add a delegator (see Flow C).876. **Catalog** — update the repo's catalog under the docs dir (see "Keep the catalog in sync").887. **Validate** — naming, structure, frontmatter, and that any command is thin.8990### B. Create an agent91921. **Confirm a recurring role** with distinct model/tools needs (not just a one-off procedure → that93 is a skill).942. **Name it** — kebab-case, English, unique.953. **Scaffold** — copy `templates/AGENT_TEMPLATE.md` into `<agents-dir>/<name>.md`.964. **Choose a model tier** — reason about it (see "Model tiers" below). Do NOT hardcode vendor model97 IDs inside the agent body; keep the abstract tier and map it in repo config.985. **Fill** — Role, Inputs, Process, Output, escalation rules.996. **Catalog** — update the catalog under the docs dir.1007. **Validate** — naming, structure, tier chosen with justification.101102### C. Create a command (thin delegator)1031041. Confirm the target skill or agent exists.1052. Add `<commands-dir>/<cmd>.md` as a ~20-line delegator: read the target skill/agent fresh and follow106 it, passing along args. Do NOT embed logic — logic lives in the skill/agent so updates propagate.1073. Reference the new command in the catalog / commands reference.108109### D. Update an existing skill / agent / command1101111. Read the existing file and the repo's conventions first.1122. Make the smallest change that satisfies the request; preserve frontmatter the repo relies on.1133. Keep delegators thin; keep skills single-procedure.1144. Update the catalog if name, description, or surface changed.115116### E. Evaluate the catalog (Skills & Agents Discovery)117118This is the flow invoked by the mandatory plan task.1191201. Enumerate every skill (`<skills-dir>/*/SKILL.md`) and agent (`<agents-dir>/*.md`).1212. For each, capture name, one-line description, and model tier (if any).1223. Cross-check against the repo's catalog under the docs dir: flag missing entries, stale123 descriptions, orphaned commands, and duplicates.1244. Reconcile: update the catalog so it matches reality. Report drift found and fixed.125126---127128## Repo-fit rubric (before creating)129130Gather: stack & tooling (languages, frameworks, package manager, test runner, linter); workflows (how131code is built, tested, reviewed, released); pain points (repetitive manual steps); the existing kit132(avoid duplicates). Then:133134- Create a **skill** for a repeatable procedure people do by hand.135- Create an **agent** for a recurring role with distinct model/tools needs.136- Create a **command** only as a thin entry point.137- Skip anything generic that does not match a real workflow.138139Anti-patterns to avoid: generic kits that do not match the repo; fat commands with embedded logic;140duplicates of existing skills/agents; agents pinned to vendor model IDs in their bodies.141142---143144## Model tiers (for agents)145146Skills inherit the session model; agents may pin an abstract tier.147148| Tier | Use for | Examples |149|------|---------|----------|150| **light** | Mechanical, well-specified, low-judgment tasks | formatting, lint fixes, renames, list/status commands |151| **standard** | Most engineering work; moderate reasoning | feature work, refactors, test writing, reviews |152| **heavy** | High-judgment, architectural, ambiguous tasks | architecture, security audits, complex planning |153154How to choose: default to **standard**; drop to **light** only if mechanical and well-specified; raise155to **heavy** only for deep reasoning or high blast radius. Keep tiers abstract — map them to concrete156model IDs in the repo's runtime/config, in one place, never inside skill bodies.157158---159160## Keep the catalog in sync161162After any create/update, reconcile the repo's catalog (commonly under the docs dir, e.g. a163skills/agents catalog and a commands reference). Add or update the row for the affected skill/agent/164command: name, one-line description, tier (agents), and the command that invokes it. The catalog must165always match what is on disk.166167---168169## Templates170171- `templates/SKILL_TEMPLATE.md` — skill scaffold.172- `templates/AGENT_TEMPLATE.md` — agent scaffold.173174Reference them by these relative paths. Adapt the frontmatter to the host repo's local convention175(some repos add `version`, `documentation_url`, or `user-invocable`; match what neighboring files use).176177---178179## Validation180181- Names are kebab-case, English, unique.182- Frontmatter matches the repo's convention; descriptions are a single line starting with a verb.183- Skills are single-procedure; agents declare a justified tier (no hardcoded vendor model IDs).184- Commands are thin delegators with no embedded logic.185- The catalog under the docs dir reflects every change.186187---188189## Notes190191- Reason about the repo; never copy a generic kit.192- Propose before creating when scope is broad — confirm the short list with the developer first.193- All references inside the skill are relative; nothing outside the skill root is required at runtime.