Working With Skills

PAS Code ships skills for AI coding assistants. A skill carries the procedure for one task. One of these skills carries the development workflow itself: spec-driven development, the workflow that every feature change in a PAS Code project follows. This page explains what a skill is, how the skills reach your project, how you use them, what spec-driven development is, and why PAS Code works this way. The complete details of a skill, including every step of the spec-driven workflow, are in the skill file in your project.

What is a Skill?

A skill is a packaged instruction set for an AI coding assistant. Skills keep your assistant on the supported path. It scaffolds through the PAS CLI instead of writing project files by hand, and it follows the PAS code, specification, and documentation rules instead of inventing its own conventions.

Skill Availability

The skills are part of the PAS Code packages. Every project that you create with pas new is prepared for them.

Skill Sources

Skill sources are a PAS-specific mechanism. The official skill convention expects every skill to sit directly in the folder that one AI coding assistant reads, which means the same skill has to be copied for each assistant and kept up to date in each copy. PAS Code replaces that with a single declaration: a project lists where its skills come from, and PAS Code links them into the folders of every assistant the project uses. Skills from different sources are combined this way, for example the packages that PAS Code ships, a git repository, and a folder in your own project. The mechanism is open to you as well: add your own sources to the declaration, and the skills they contain reach every assistant in the project together with the skills of PAS Code.

A project declares its skill sources in .pas/skills-sources.json:

{
  "agents": ["claude-code", "junie", "universal"],
  "sources": ["./node_modules/@pas/dev-guidelines", "./.pas/skills"],
  "gitignore": false
}

Linking Skills

Linking copies the declared skills into the directories where your AI coding assistant discovers them. The pas-link-skills command performs the linking. It runs automatically as the postinstall script of your project, so npm install is enough to make the skills available.

Run the command manually after you add a source or change the assistant list:

npx pas-link-skills

The command is non-interactive, safe to run in a pipeline, and repeatable. A local folder is only linked when at least one of its subfolders contains a SKILL.md file.

Project-Level Rules

The rule skills carry the global PAS rules. To complete or override them for your own project, add the matching rule file to the .agents folder of your project:

• .agents/code-rules.md for the code rules

• .agents/specification-rules.md for the specification rules

• .agents/documentation-rules.md for the documentation rules

When a project-level rule conflicts with a global rule, the project-level rule applies.

Using Skills

Keep the following recommendations in mind:

• Install the PAS CLI before you use the scaffolding skills. They call pas commands. Without the CLI, the skill falls back to npx -y @pas/cli <command>.

• Start feature work with the specification. The scaffolding and code skills require an approved SPEC.md file on disk. Your assistant returns to the specification phase when the file is missing.

• Approve each phase explicitly. The spec-driven workflow never advances a phase on its own.

• Your assistant names the skill it used, so you can check which procedure it followed.

For an overview on all available skills, refer to Skills.

Spec-Driven Development

Spec-driven development is the default development workflow in a PAS Code project. PAS Code delivers this workflow as a skill. Every change that adds, extends, modifies, refactors, renames, or cleans up a feature runs through it. A specification describes what the code must achieve, and it is the source of truth the code is measured against.

The concept rests on these principles:

• A specification is a SPEC.md file on disk. It sits next to the code it governs and applies to its own directory and to the subdirectories of that directory.

• The specification is written and approved before the code. This includes generated code.

• The workflow runs through its phases in a fixed order, and each phase ends with your explicit approval. It never advances a phase on its own.

• Every phase follows one set of rules, and every remark you make is written into the specification or into the rules, so it also applies to the next change.

• The workflow applies whether you write the code yourself or work with an AI coding assistant. The rules are the same, and the review checks the result against the same specification.

Spec-Driven Development Is a Skill

The skill pas-spec-driven-development reaches your project through the same sources and the same linking as every other PAS Code skill. Your assistant loads it before any feature work, including work that starts as a plan, and the skill calls the skills that own the rules of each phase.

Because the workflow is a skill, it is a file you can read. The skill file describes the phases, the approval rules, the handling of your remarks, and the rules for a SPEC.md file. Read it in your project when you need a step in detail.

Why the Specification Comes First

The specification is what the code is checked against. A review compares a change to the SPEC.md files that govern it, so code that no specification covers cannot be judged complete or correct.

The specification records the decision, not the conversation. An agreement made in a chat is gone the next time. A SPEC.md on disk is read again by whoever continues the work.

The specification stays implementation-agnostic, so the requirement survives a rewrite of the code that fulfills it.

This is the reason the workflow produces no code, including scaffolded code, before a specification is approved.

Scaffolding Follows the Same Rule

Generating a project, an app, a service, an agent, or a bundle deployment adds a feature to your project. The same requirement therefore applies: an approved SPEC.md covering the feature exists first. The generated code is code you own from the moment it exists, and the review holds it to the same specification as everything you write by hand.

Inspecting a Skill in Your Project

The linked skills are files in your project, so you can read every procedure your assistant follows:

• Open the skills folder of your assistant, for example .claude/skills or .agents/skills, and open the SPEC.md file of the skill.

• Open the reference folder next to a SKILL.md file for the detailed rules of that skill.

• Open the folder pas-spec-driven-development for the development workflow. Its SKILL.md file names the phases and the approval rules, and its reference folder holds the complete workflow with every step, together with the rules for a SPEC.md.

Related Content