Designing Hierarchical Skills and Sub‑Agents for Product Development Teams

1. What is a Skill?

A Skill is not a simple prompt template; it is a reusable work‑method definition that must specify four elements: the trigger scenario, required inputs, execution steps, and how to verify the output. For example, write-prd guides an agent to clarify background, identify roles, break down features, define acceptance criteria, and produce a reviewable PRD, while code-review checks code against architecture, security, performance, and maintainability guidelines.

2. How to abstract a Skill

The most common mistake is unclear boundaries. A Skill that is too fine‑grained becomes a collection of tiny functions; one that is too coarse tries to do everything and becomes unusable. The guiding principle is that a Skill corresponds to one high‑frequency activity of a role, not a document fragment. Related tasks should be merged—for instance, user‑story writing, acceptance‑criteria definition, and PRD self‑check belong to write-prd. A work item is suitable for Skillification when it meets four criteria: high frequency, stable steps, requires contextual judgment, and has verifiable results.

3. Representative Skills for product development

Requirements & Product: write-prd, write-research-report Design & Planning: write-tech-design, write-api-contract, breakdown-tasks Code & Review: code-review, generate-unit-test Release & Ops: write-release-changelog, write-runbook, write-postmortem Collaboration & Knowledge: write-meeting-notes, write-weekly-report, write-sprint-retro, write-onboarding-guide,

maintain-ai-context

4. Placing Skills in a collaborative chain

The four‑layer model is Context → Skill → Workflow → Human confirmation. Context enforces boundaries, Skill provides the method, Workflow strings multiple Skills together, and humans make final judgments. An example chain for a feature is:

write-prd → write-tech-design → breakdown-tasks → code-review → write-release-changelog

. Isolated Skills cannot close the loop; without human confirmation they may drift.

5. From Skill to Sub‑Agent

A Skill solves “how to do a class of tasks”; a Sub‑Agent solves “who continuously owns a chain of responsibilities”. Sub‑Agents combine several Skills, maintain state across steps, handle exceptions, and invoke tools or humans when needed. Their boundaries should be defined by role responsibilities rather than document types. Promotion to Sub‑Agent is justified when the work is a continuous chain, requires stable composition of Skills, needs state persistence, and the team already has clear role division.

Typical Sub‑Agent compositions:

Product analysis: write-prd, write-research-report, write-meeting-notes Technical design: write-tech-design, write-api-contract, breakdown-tasks Engineering quality: code-review, generate-unit-test, write-release-changelog Collaboration & knowledge maintenance: write-meeting-notes, write-weekly-report, write-sprint-retro,

maintain-ai-context

6. Measuring Skill effectiveness

Adoption rate : proportion of Skill output accepted with little or no modification.

Downstream rework rate : frequency of extra work after the Skill’s result is handed to the next stage.

Continued usage rate : whether the team keeps using the Skill after the initial trial.

Regular retrospectives should record which steps produce stable results, which checks are missing, and which outputs need manual tweaking, driving continuous iteration.

7. Common pitfalls

Turning Skills into a mere template library without execution steps or verification criteria.

Defining overly broad boundaries that make the Skill unstable.

Separating Skills from context and workflow, causing drift.

Attempting Sub‑Agents before the underlying Skills are stable.

8. Starting from scratch

For teams new to Skill construction, begin with three core Skills that cover the main product‑development chain: write-prd, write-tech-design, and code-review. Once these are reliable, connect them into a workflow and finally encapsulate the workflow as a Sub‑Agent.

Stabilize high‑frequency Skills.

Chain Skills into a workflow.

Wrap the stable workflow into a Sub‑Agent.

Conclusion

Context engineering keeps agents from drifting; Skills enable agents to participate in structured collaboration; Sub‑Agents turn coordinated Skills into responsibility‑oriented units, forming the foundational infrastructure for scalable AI‑assisted product development.