Reading: Part 14. Own Process Through Qwen Code Skills

Lesson 1 of 5 in module «Part 14. Own Process Through Qwen Code Skills»

You are viewing the lesson without signing in. Sign in to save progress and take tests.

Source

Part 14. Build Your Own Workflow with Qwen Code Skills

When you've repeated a prompt for feature specification several times, it's time to automate it. In Qwen Code, agent skills are the right tool for this. A skill is a directory with a SKILL.md file that describes when and how the agent should apply a specific process. A skill can be personal or project-specific.

Personal skill:

~/.qwen/skills/feature-spec/SKILL.md

Project skill:

.qwen/skills/feature-spec/SKILL.md

For a team, a project skill is better: it goes into Git and becomes part of the engineering process.

If multiple different agents use your project in parallel, skills can be supplemented with an AGENTS.md file in the repository root — this is an inter-agent standard for rules that is read not only by Qwen Code but also by other compatible tools. More on the role of AGENTS.md alongside QWEN.md — in part 15.

Creating a Skill

mkdir -p .qwen/skills/feature-spec

SKILL.md:

---
name: feature-spec

description: Creates a new SDD feature specification from the next uncompleted phase of the roadmap. Use before starting the next feature, writing a specification, or preparing a new phase before implementation.
---

# Feature Specification

## Process

1. Read specs/roadmap.md.
2. Find the first uncompleted phase.
3. Create a branch named phase-N-kebab-name.
4. Before writing files, ask the human exactly three groups of questions:
   - boundaries;
   - decisions;
   - context.
5. Read specs/mission.md and specs/tech-stack.md.
6. Create specs/YYYY-MM-DD-feature-name/.
7. Write:
   - requirements.md
   - plan.md
   - validation.md
8. Do not implement code.

## File requirements.md

Include boundaries, what's outside the boundaries, decisions, context, and open questions.

## File plan.md

Use numbered groups of tasks. Each group must be verifiable separately.

## File validation.md

Include automated checks, manual walkthrough, deviation review, and acceptance criteria.

## Constraints

- Follow specs/tech-stack.md.
- Do not add dependencies without explicit approval.
- Leave the phase ready for independent delivery.
- Do not edit unrelated files.

Testing the Skill

Launch Qwen Code:

qwen

Check the list:

/skills

Request explicitly:

Use the feature-spec skill to start the next feature from the roadmap.
Do not implement code.

If the skill doesn't work, check:

the file is at .qwen/skills/feature-spec/SKILL.md;
the YAML header starts and ends with ---;
name has no spaces;
description specifically says when to apply the skill;
Qwen Code was restarted after creating the skill.

Skill vs Slash Command

A skill is invoked by the model or via /skills; it describes a capability. A slash command is explicitly invoked by the user. For SDD feature specification, a skill is more convenient: the agent can itself understand that it's needed when the user writes "start the next feature."

If your team needs a rigid interface, you can additionally create a custom command, but a skill is enough to start with.

Auxiliary Files

When the process grows, extract templates:

.qwen/skills/feature-spec/
  SKILL.md
  templates/
    requirements.md
    plan.md
    validation.md

In SKILL.md:

Use templates/requirements.md as the initial structure.

Do not copy template comments into final specifications.

Changelog Skill

A second useful skill:

.qwen/skills/changelog/SKILL.md

Example:

---
name: changelog
description: Updates CHANGELOG.md based on Git history and changes in the current branch before merging the feature branch.
---

# Changelog

1. Review git log and git diff against main.
2. Create or update CHANGELOG.md.
3. Use date-based headings.
4. Write brief items understandable to stakeholders.
5. Do not include noisy internal details.

Escalation Rules: When the Agent Must Stop

A good agent differs from a bad one not by being smarter, but by knowing when to stop and ask. By default, most CLI agents strive to complete the task at any cost: if context is insufficient, they guess. This is a useful property for short tasks and a bad one for SDD work.

To prevent the agent from guessing, it's convenient to put explicit escalation rules in QWEN.md (or in a skill):

Stop and ask the human, do not act, in the following cases:

- if there are different interpretations of a single requirement in the feature specification;

- if you are about to change a file outside the boundaries of the current specification;
- if you are about to add a new dependency not listed in tech-stack.md;
- if you are about to change tech-stack.md, mission.md, or roadmap.md;
- if a migration, drop, delete, or rm with non-trivial scope is required;
- if you did not find a file referenced by the user;
- if the result does not match a fact from validation.md, and the fact is not marked as "deferred";
- if the user's request contradicts previously accepted rules in QWEN.md.

In each such case, output a brief explanation of what exactly is ambiguous,
and offer 2–3 specific options to choose from. Do not choose for the human.

This is not "politeness." This is a contract: the agent is obligated to return control to the human as soon as it encounters a condition from the list. The same rules can be additionally reinforced with a Stop hook (see part 17), which will prevent the agent from completing if it silently made a contentious decision.

Context Hygiene and Cost

Every long session has a price in two senses: tokens and quality. The longer a session runs, the more old context the agent has, and the easier it is to accidentally pull solutions from adjacent tasks into the current one. On long sessions, a phenomenon observed in research papers called "context rot" is seen: a focused short input yields a better result than a large irrelevant one. The same principle applies to agent-managed memory — more in part 19.

A few simple hygiene rules:

run /clear between roles (interview → implementation → review → replanning);
keep one session time-limited; if a session lasts more than an hour, it's probably time to close it and start a clean one;
don't feed the agent entire folders if you can feed specific files;
for long tasks, use @file explicitly, not "it will find it itself";
if you suspect confusion — /clear, read QWEN.md and the active specification from scratch.

If Qwen Code has automatic context compression enabled, it helps but does not replace /clear. Compression preserves a summary of history — it's useful for a long continuous task, but it's precisely the summary that often becomes a source of false hints for the next task. /clear guarantees that in a new role, the agent works only with what's written in the repository.