Study guide: Part 14. Own Process Through Qwen Code Skills

Topic: Part 14. Your Own Process Through Qwen Code Skills

Difficulty level: Medium

Estimated study time: 4-6 hours (theory + practice)

Prerequisites: Basic knowledge of Qwen Code and working with CLI agents

Understanding of Git and branching

Experience working with Markdown

Familiarity with the SDD (Specification-Driven Development) concept

Completed parts 1-13 of the course (especially working with QWEN.md)

Learning objectives: Create and configure agent skills in Qwen Code to automate repetitive processes

Distinguish between personal and project skills, justifying the choice of skill type for team work

Formulate effective descriptions in the YAML header of SKILL.md for correct automatic skill discovery

Implement escalation rules that prevent unwanted autonomous agent actions

Apply context hygiene techniques to maintain quality during long sessions with the agent

Overview: This part of the course is dedicated to automating repetitive engineering processes through the Qwen Code skills system. You will learn to transform frequently repeated requests into structured, reusable agent skills, create project and personal skills, implement escalation rules for safe agent operation, and manage context in long sessions. The main focus is on practical application: feature specification in SDD format and changelog maintenance as examples of typical skills that accelerate team work and standardize engineering practices.

Key concepts: Agent skill: A directory with a SKILL.md file containing a description of a specific process: when and how the agent should apply it. A skill is a unit of automation for repetitive requests in Qwen Code. Unlike slash commands, a skill is invoked by the model automatically or via /skills, describing a capability rather than a rigid interface.

Personal skill: A skill located at ~/.qwen/skills/<name>/SKILL.md. Available only to the current user on this machine. Suitable for individual preferences and experiments, but not included in version control.

Project skill: A skill located at .qwen/skills/<name>/SKILL.md inside the repository. Included in Git, becomes part of the team's engineering process, ensures consistency among all developers and agents working on the project.

YAML header of skill.md: Metadata in YAML format between --- markers at the beginning of the SKILL.md file. Contains required fields name (no spaces) and description (specific description of application conditions). A correct header is critical for skill discovery by the agent.

Escalation rules: An explicit contract describing situations where the agent must stop and request confirmation from a human instead of acting independently. Prevent agent guessing when context is insufficient, protect against unwanted changes.

Context rot: Phenomenon of deteriorating agent work quality during long sessions due to accumulation of irrelevant context. Old decisions from adjacent tasks are accidentally pulled into current work, reducing accuracy and relevance of output.

Context hygiene: A set of practices for managing agent context: regular use of /clear between role changes, limiting session duration, explicit file specification via @file instead of passing entire directories, restarting with QWEN.md reading when confusion is suspected.

Skill auxiliary files: Additional resources in the skill directory (templates/, examples, snippets) that SKILL.md can reference to extend functionality without bloating the main file. Templates are not copied with comments into final specifications.

Agents.md: An inter-agent standard of rules in the repository root, supplementing QWEN.md. Read not only by Qwen Code but also by other compatible tools. Ensures consistency when using several different agents in parallel on the same project.

Practice exercises: Name: Creating a basic feature specification skill

Problem: In your project, SDD specifications for new features are regularly created from the roadmap. The repeating request: "Create a specification for the next phase from roadmap.md". It is necessary to automate this process through an agent skill. Create a project skill feature-spec with a correct YAML header, an 8-step process, three output files (requirements.md, plan.md, validation.md), and constraints. Verify discovery via /skills.

Solution: 1. Create directory: mkdir -p .qwen/skills/feature-spec

1. Create file .qwen/skills/feature-spec/SKILL.md with contents:

--- 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 branch phase-N-kebab-name
4. Ask the human 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 — boundaries, out of scope, decisions, context, open questions ## File plan.md — numbered groups of tasks, each verified separately ## File validation.md — automatic checks, manual walkthrough, deviation checks, readiness criteria ## Constraints: follow tech-stack.md, do not add dependencies without approval, leave phase ready for delivery, do not edit unrelated files

1. Restart Qwen Code
2. Execute /skills — verify that feature-spec appears
3. Test invocation: "Use the feature-spec skill to start the next feature from the roadmap. Do not implement code"
4. If the skill did not work, check: file path, correctness of YAML header (--- at beginning and end), no spaces in name, specificity of description, agent restart

Complexity: beginner

Name: Extending a skill with auxiliary templates

Problem: The feature specification process has grown, and the SKILL.md file has become unwieldy. Moreover, different specifications require uniform structure, but the team spends time on formatting. It is necessary to extract templates into separate files and update SKILL.md to use them.

Solution: 1. Create templates directory inside the skill: mkdir -p .qwen/skills/feature-spec/templates

1. Create .qwen/skills/feature-spec/templates/requirements.md with initial structure:

# Requirements ## Boundaries <!-- What is included in the feature --> ## Out of scope <!-- What is explicitly not included --> ## Decisions <!-- Accepted architectural decisions --> ## Context <!-- Why these specific decisions were made --> ## Open questions <!-- What requires clarification -->

1. Similarly create templates/plan.md and templates/validation.md
2. Update SKILL.md, adding to the process:

"Use templates/requirements.md as the initial structure. Do not copy template comments into final specifications."

1. Verify that the agent correctly uses templates without transferring instruction comments into output files
2. Commit changes: git add .qwen/skills/ && git commit -m "Add feature-spec skill with templates"

Complexity: intermediate

Name: Implementing escalation rules

Problem: The agent in your project has made controversial decisions independently several times: adding dependencies without coordination, changing files outside specification boundaries, editing tech-stack.md. It is necessary to formalize escalation rules in QWEN.md or a skill so that the agent must stop and request confirmation.

Solution: 1. Open or create QWEN.md in the repository root (or add to existing SKILL.md)

1. Add section "Escalation Rules":

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

• if there are different interpretations of the same 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 QWEN.md rules.

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.

1. Test on a scenario: ask the agent to add a library not in tech-stack.md — verify it stopped with options
2. Additional: study the Stop hook from part 17 for programmatic verification of rule compliance

Complexity: intermediate

Name: Creating a changelog skill

Problem: The team spends time manually updating CHANGELOG.md before feature merges. Commit history is fragmented, formatting is inconsistent. Create a changelog skill that automates the process based on git log and git diff.

Solution: 1. Create directory: mkdir -p .qwen/skills/changelog

1. Create .qwen/skills/changelog/SKILL.md:

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

1. Look at git log and git diff relative to main
2. Create or update CHANGELOG.md
3. Use headings with dates
4. Write brief items understandable to stakeholders
5. Do not include noisy internal details
6. Restart Qwen Code, verify via /skills
7. Create a test branch with several commits, ask the agent to use the changelog skill
8. Check the result: dates in headings, absence of internal details like "refactoring function X", presence of user-friendly descriptions
9. Use the skill before actual merge to main

Complexity: beginner

Name: Diagnosing and resolving skill discovery problems

Problem: You created a skill, but the agent does not see it in /skills or does not apply it when explicitly requested. Systematically diagnose and resolve the issue.

Solution: 1. Check path: file must be at .qwen/skills/<name>/SKILL.md (project) or ~/.qwen/skills/<name>/SKILL.md (personal)

1. Check YAML header:

• Starts and ends with exact markers --- (no spaces, no BOM)
• Field name without spaces, only Latin characters, hyphens, underscores
• Field description specifically describes application conditions, not generic phrases like "useful skill"

1. Check access permissions: file must be readable
2. Check restart: Qwen Code caches skills at startup, changes require restart
3. Check Markdown syntax: broken headings or tables may interfere with parsing
4. Check for name conflicts: two skills with the same name are not allowed
5. If everything is correct — check Qwen Code version, an update may be required
6. Temporary solution: use explicit import via /load or equivalent command for your version

Complexity: intermediate

Name: Optimizing a long session with context hygiene

Problem: You have been working with the agent on a complex task for 90 minutes. Signs of context degradation are observed: the agent references decisions from a previous task, suggests irrelevant files, confuses boundaries of the current feature. Apply context hygiene techniques to restore work quality.

Solution: 1. Execute /clear for full session context cleanup

1. Re-read QWEN.md from scratch: "Read QWEN.md and follow its rules"
2. Re-read the active specification: "Read specs/YYYY-MM-DD-feature-name/requirements.md and all related files"
3. Explicitly specify needed files via @file instead of "find yourself" or passing entire directories
4. Break remaining work into subtasks of 15-20 minutes each
5. Between subtasks use /clear and re-read only relevant context
6. If automatic context compression is enabled — remember that it preserves summaries which may contain false hints; /clean is preferable for role changes
7. Document intermediate results in project files, do not rely on session memory

Complexity: advanced

Case studies: Name: Implementing SDD skills in a fintech startup: from chaos to standardization

Scenario: A fintech startup with 12 developers and 3 product teams. Each team used a different feature specification format: some wrote in Google Docs, others in Notion, a third group relied on verbal agreements. When rotating developers between teams, 2-3 days were needed to adapt to the new format. Introducing Qwen Code did not solve the problem: the agent generated specifications in whatever format it had seen most recently in context, leading to fragmentation.

Challenge: It was necessary to: (1) standardize the SDD specification format for all teams, (2) make this format automatically applicable by the agent without additional instructions, (3) ensure versioning and evolution of the format, (4) minimize adaptation time during rotation.

Solution: The tech lead created a project skill feature-spec in the company's root repository (mono-repo with 40+ services). The skill included: a strict 8-step process, three output files with detailed content requirements, templates in a templates/ subdirectory, and escalation rules prohibiting the agent from deviating from tech-stack.md. Additionally, a changelog skill was created for uniform changelog maintenance. For cross-team consistency, AGENTS.md was added to the mono-repo root with basic rules readable by all team tools.

Result: After 3 weeks of implementation: specification creation time reduced from 4 hours to 45 minutes (including time for agent clarifying questions); adaptation during rotation reduced to 2 hours (reading SKILL.md is sufficient); 94% of specifications accepted without revision at review (vs. 60% previously); unified CHANGELOG enabled automated release notes generation; the team identified and corrected 7 cases where the agent tried to add unapproved dependencies, thanks to escalation rules.

Lessons learned: Project skills in the root repository are more effective than individual developers' personal skills for scaling practices

Escalation rules are not redundant bureaucracy but savings: 7 prevented dependency incidents saved a week of rollback work

Templates in templates/ accelerate agent work and improve consistency, but require an explicit "do not copy comments" rule

AGENTS.md is necessary when using multiple tools (Qwen Code, Cursor, custom scripts) — prevents rule divergence

Related concepts: Project skill

Escalation rules

Skill auxiliary files

AGENTS.md

Context hygiene

Name: Rescuing from context degradation in a long agent refactoring session

Scenario: A team of 4 developers was conducting a large-scale refactoring of a payment system core. One developer used Qwen Code to sequentially process 15 related services in one session lasting 3 hours. Starting from the 8th service, the agent began suggesting solutions characteristic of the 3rd service (outdated architecture, already abandoned), and tried to change tech-stack.md, "optimizing" for a pattern the team had consciously rejected.

Challenge: Diagnose and stop context degradation without losing progress; understand why automatic context compression did not help; restore correct agent operation; prevent recurrence in future long sessions.

Solution: The developer applied emergency context hygiene: /clear, re-reading QWEN.md and the active specification, explicit @file specification for the specific service instead of "process the remaining". For the remaining 7 services, work was split into separate 20-minute sessions each with mandatory /clear between them. Medium results were fixed in project files, not session memory. It was discovered that automatic compression had preserved "summaries" of outdated decisions as "important context", which became the source of false hints.

Result: The last 7 services were processed correctly, without deviations from the approved architecture. The developer documented the incident in the internal knowledge base. The team introduced a rule: agent sessions limited to 45 minutes, mandatory /clear and QWEN.md re-reading between stages. No similar incidents were observed in subsequent refactorings.

Lessons learned: Automatic context compression helps for a long continuous task but harms sequential different tasks — summary becomes a source of false hints

/clear guarantees a clean start but requires discipline of documenting intermediate results in files

Session duration limit (45 minutes) is a simple and effective rule, easily verifiable in retrospective

Explicit file specification via @file is critical after /clear: the agent will not "guess" context from the previous session

Related concepts: Context degradation

Context hygiene

Escalation rules

Project skill

Study tips: Start by creating a personal skill in ~/.qwen/skills/, debug it on your project, then transfer to project — this avoids committing non-working versions to Git

Validate the YAML header with a validator (e.g., yamllint) — invisible formatting errors often cause skill non-discovery

Keep an "escalation diary": record cases where the agent should have stopped but did not — use these to supplement rules

Use the "parallel comparison" technique: create the same skill two ways (via SKILL.md and via slash command), test on one task, record differences in agent behavior

Practice "hygiene stress test": intentionally create a long session with role switching to learn recognizing early signs of context degradation

Create a "skill for skills" — a meta-skill that helps create new skills from a template, with correct YAML header and structure

Study others' project skills in open-source repositories — the Qwen Code community actively shares best practices

Combine visual, auditory, and kinesthetic learning: read SKILL.md aloud to check instruction clarity, draw process flowcharts, write skills by hand before digital input for better structure memorization

Additional resources: Official Qwen Code documentation: https://github.com/QwenLM/Qwen-Code (current skill examples and format updates)

Course part 15 — agents.md and inter-agent compatibility: part-15-agent-replaceability.md (in course repository)

Course part 17 — stop hook for programmatic escalation verification: part-17-stop-hooks.md (in course repository)

Course part 19 — agent managed memory on sqlite: part-19-agent-memory-sqlite.md (in course repository)

YAML specification 1.2: https://yaml.org/spec/1.2.2/ (for deep understanding of SKILL.md header requirements)

Community project skill examples: https://github.com/search?q=path%3A.qwen%2Fskills+SKILL.md&type=code (public repository search)

Research on context rot in LLM agents: https://arxiv.org/abs/2404.06910 (academic analysis of context degradation)

Interactive YAML header trainer: https://www.yamllint.com/ (syntax check for skill metadata)

Summary: Key takeaways of part 14: (1) Repetitive requests should be automated through agent skills — this saves time and standardizes processes. (2) Project skills (.qwen/skills/) are preferable to personal ones (~/.qwen/skills/) for team work, as they are versioned in Git and available to all participants. (3) A correct YAML header with a specific description is critical for automatic skill discovery by the agent. (4) Escalation rules are a mandatory safety contract preventing unwanted autonomous agent actions under uncertainty. (5) Context hygiene (/clear, session duration limits, explicit file specification) is no less important than skill quality — context degradation destroys the effectiveness of even perfectly written instructions. (6) Skills and slash commands complement each other: skills for automatic application, commands for explicit invocation. (7) Auxiliary files (templates/) allow scaling complex skills without bloating SKILL.md.