Skills

A skill is a block of domain expertise that gets injected into the AI during specific workflow phases. Instead of repeating your project's conventions in every conversation, you define them once as a skill and attach them to the phases where they matter.

Why skills exist

Every project has rules that aren't in the code. Error handling conventions. Testing patterns. Naming standards. Architectural constraints. Without skills, you'd have to remind the AI about these rules every time. With skills, you write them once and the system injects them at the right moment.

Structure

name: rust-conventions
group: vast
department: engineering
description: Rust coding patterns for this project

triggers:
  - build
  - fix
  - refactor

content: |
  ## Error Handling
  - Use tracing::warn! for recoverable errors
  - Return Result<T, String> for domain errors
  - Never use unwrap() in production code

  ## Testing
  - Every fix must include a regression test
  - Use #[test] not #[ignore] — broken tests are bugs
  - Test names describe the scenario: test_login_fails_with_expired_token

  ## Style
  - No abbreviations in public APIs
  - Prefer &str over String in function parameters
  - Group imports: std, external crates, internal modules

A skill has:

• name — Identifier used when referencing this skill.
• group — Namespace.
• description — What this skill covers.
• triggers — A list of workflow phase names. When the workflow enters a phase whose name matches a trigger, this skill activates.
• content — The actual expertise. Written as instructions the AI should follow. Be specific and concrete — vague guidelines don't help.

When skills activate

Skills fire based on triggers. The trigger values match against workflow phase names. When the workflow enters a phase named "build," all skills with triggers: [build] get injected into the AI's context.

This means you can write a skill once and have it activate across multiple workflows. A "rust-conventions" skill with triggers: [build, fix, refactor] fires during any workflow that has phases with those names.

Step-level skills

Individual workflow steps can also request skills directly:

steps:
  - name: Write the fix
    instruction: Minimal change that addresses root cause
    skills: [rust-conventions, error-handling]

When this step runs, the listed skills are injected regardless of the phase-level triggers. This gives you fine-grained control — a step in an "understand" phase can pull in coding conventions if it needs to analyze code patterns.

Writing good skills

Skills work best when they're specific. Compare:

Vague: "Follow good coding practices and write clean code."

Specific: "Use tracing::warn! for recoverable errors. Return Result<T, String> for domain errors. Never call .unwrap() in production code."

The AI already knows general best practices. Skills should encode the things that are specific to your project — the decisions your team has made that differ from defaults.

Where skills live

Skills are YAML files stored in .8v/skills/:

• Project skills (.8v/skills/rust-conventions.yaml in your project) — Available only in that project.
• User skills (~/.8v/skills/rust-conventions.yaml) — Available in all your projects.

Project skills take priority over user skills with the same name.

Skills vs. roles

Roles define who the AI is — its perspective and approach. Skills define what the AI knows — domain-specific rules and patterns. A phase has one role and can reference many skills. The role shapes behavior; the skills provide knowledge.