docs: add Agent Skills for development workflows

[bkrupa]

Summary

Adds 11 structured SKILL.md files in .skills/ directory, providing AI-assisted development workflow definitions for:

• Branching, Building, Cascading, Debugging
• Installing, Linting, Manual Testing
• Pull Requests, Stacking, Testing

Each skill file defines inputs, steps, and expected outcomes for common development tasks.

Files changed

• .skills/README.md - Skills index
• .skills/branching/SKILL.md
• .skills/building/SKILL.md
• .skills/cascading/SKILL.md
• .skills/debugging/SKILL.md
• .skills/installing/SKILL.md
• .skills/linting/SKILL.md
• .skills/manual-testing/SKILL.md
• .skills/pull-requests/SKILL.md
• .skills/stacking/SKILL.md
• .skills/testing/SKILL.md

[sourcery-ai]

Reviewer's Guide

Introduces an Agent Skills directory (.skills/) to the repository and populates it with focused SKILL.md guides that encode the project’s development, branching, stacking, cascading, debugging, testing, linting, installing, manual testing, and pull-request workflows in the Agent Skills open standard format.

Sequence diagram for Agent Skills discovery and execution

sequenceDiagram
    actor Developer
    participant Agent
    participant Repo
    participant SkillsDir as Skills_directory
    participant SkillFile as SKILL_md

    Developer->>Agent: describe_task_for_twig_development
    Agent->>Repo: locate_project_root
    Repo-->>Agent: project_root_path

    Agent->>SkillsDir: scan_directory_for_skills
    SkillsDir-->>Agent: list_of_SKILL_md_files

    Agent->>SkillFile: read_frontmatter
    SkillFile-->>Agent: name_and_description

    Agent->>Agent: rank_skills_by_description_match
    Agent->>SkillFile: load_full_body_for_selected_skill
    SkillFile-->>Agent: detailed_instructions

    Agent->>Developer: propose_concrete_workflow_steps
    Developer->>Agent: approve_or_refine_plan

    Agent->>Developer: guide_through_commands_and_checks

Loading

Flow diagram for selecting the appropriate twig development skill

flowchart TD
    Start["Start_twig_related_task"]

    Start --> Q1["Need_to_build_or_check_the_workspace?"]
    Q1 -->|yes| Skill_building["use_skill_building"]
    Q1 -->|no| Q2["Need_to_lint_or_format_code?"]

    Q2 -->|yes| Skill_linting["use_skill_linting"]
    Q2 -->|no| Q3["Need_to_run_tests_or_coverage?"]

    Q3 -->|yes| Skill_testing["use_skill_testing"]
    Q3 -->|no| Q4["Installing_dev_builds_or_tools?"]

    Q4 -->|yes| Skill_installing["use_skill_installing"]
    Q4 -->|no| Q5["Debugging_unexpected_twig_behavior?"]

    Q5 -->|yes| Skill_debugging["use_skill_debugging"]
    Q5 -->|no| Q6["Working_with_branches_and_dependencies?"]

    Q6 -->|yes_core_tree| Skill_branching["use_skill_branching"]
    Q6 -->|stacked_feature_branches| Skill_stacking["use_skill_stacking"]
    Q6 -->|propagate_changes_through_tree| Skill_cascading["use_skill_cascading"]
    Q6 -->|none_of_these| Q7["Creating_or_managing_pull_requests?"]

    Q7 -->|yes| Skill_pr["use_skill_pull_requests"]
    Q7 -->|no| Q8["Manual_testing_against_real_repo?"]

    Q8 -->|yes| Skill_manual["use_skill_manual_testing"]
    Q8 -->|no| End["no_matching_skill_in_current_set"]

Loading

File-Level Changes

Change	Details	Files
Add Agent Skills scaffolding and documentation entrypoint for AI-discoverable workflows.	Create .skills/ directory to host Agent Skills-compliant content. Document skills structure, discovery, and authoring conventions in a top-level README within .skills/.	.skills/README.md
Capture manual testing workflow for twig using a dedicated sibling Git repository.	Define the manual-testing skill with YAML frontmatter (name, description) and detailed Markdown instructions. Describe how to create, reset, and manage the d:\code\twig-test-dir repo for safe manual experiments. Provide recipes for constructing branch trees and exercising key twig commands (tree, cascade, rebase, tidy, dashboard, sync, switch). Include guidance on verifying git/twig state, using debug binaries vs PATH binaries, and general testing tips.	.skills/manual-testing/SKILL.md
Encode debugging practices for twig using structured logging and diagnostics.	Define the debugging skill with YAML frontmatter aligned to the Agent Skills spec. Document tracing levels via -v flags and RUST_LOG targeting for specific crates/modules. Show patterns for adding tracing macros, spans, and structured fields without polluting user-facing output. Explain enhanced error handling, self diagnostics, and a stepwise debugging workflow including state inspection.	.skills/debugging/SKILL.md
Encode the twig pull-request lifecycle as a reusable skill.	Define the pull-requests skill with frontmatter plus a full PR workflow from branching off main through cleanup. Describe usage of gh CLI for creating and inspecting PRs, including body files. Document twig github integration commands for linking, inspecting status, CI checks, listing, and opening PRs, including aliases. Cover stacked PR workflows, force-push handling after rebases, and pre-PR checks via make targets.	.skills/pull-requests/SKILL.md
Document stacked branch workflows for twig as an Agent Skill.	Define the stacking skill with metadata and a conceptual overview of branch stacks. Provide concrete flows for creating stacks with twig switch -p, rebasing individual branches, and running twig update. Describe Jira-aware committing, interactive fixup commits, and metadata syncing via twig sync. Show how to inspect and manage stacks via twig tree and twig dashboard, including example end-to-end workflows and tips.	.skills/stacking/SKILL.md
Document cascading rebases across branch trees as a dedicated skill.	Define the cascading skill with frontmatter describing when to use twig cascade. Explain cascade behavior, options (force, force-push, autostash, max-depth, skip-commits, non-interactive), and conflict handling. Clarify distinctions between twig cascade, twig rebase, and twig update, with guidance on when to choose each. Provide a full example workflow and best-practice tips for verbose output, autostash, and exit-code checking.	.skills/cascading/SKILL.md
Document branch management concepts and commands as an Agent Skill.	Define the branching skill describing roots, dependencies, orphans, and the branch tree model stored in .twig/state.json. Show how to initialize twig in a repo, manage root branches, and define/remove dependencies. Describe viewing the tree, switching/creating branches (including Jira/PR-based switching), and bulk reparenting or clearing configuration. Detail cleanup flows via twig tidy clean/prune and associated aliases.	.skills/branching/SKILL.md
Document testing practices for twig using nextest and insta as a skill.	Define the testing skill with a strong directive to avoid cargo test and use cargo nextest run instead. Provide quick-reference commands for running all tests, specific tests, per-crate tests, and coverage via make and nextest. Explain insta snapshot workflows, updating/reviewing snapshots, and global snapshot updates. Describe shared test utilities (twig-test-utils) and integration test layout, plus tips for parallelism, flakiness, and verbose output.	.skills/testing/SKILL.md
Document build workflows and workspace structure as an Agent Skill.	Define the building skill with commands for debug, release, workspace, and single-crate builds plus cargo check. Describe the Cargo workspace members, default-members, and correct use of -p instead of per-crate cargo build from subdirs. Explain CI-specific cargo profiles and general tooling assumptions (nightly, components). Add troubleshooting guidance for linker/openssl issues and slow builds vs type-check-only flows.	.skills/building/SKILL.md
Document linting, formatting, and pre-commit workflows as an Agent Skill.	Define the linting skill describing make fmt, make lint, and make lint-all as primary entry points. Clarify how make fmt chains cargo fmt, clippy --fix, and Ruff for Python examples. Show per-crate clippy invocations and advise on common lint categories and fixes. Describe pre-commit hook setup and how it integrates into the workflow.	.skills/linting/SKILL.md
Document installation of twig binaries and dev tools as an Agent Skill.	Define the installing skill covering make install, make install-flow-plugin, and make install-dev-tools. List the dev tools installed (nextest, watch, outdated, llvm-cov, insta, pre-commit) and their purposes. Clarify the distinction between debug binaries in target/ and the PATH-installed release binary, including when each is updated. Recommend a development workflow that rebuilds locally first, then explicitly reinstalls to update the PATH binary.	.skills/installing/SKILL.md

---

Tips and commands

Interacting with Sourcery

• Trigger a new review: Comment @sourcery-ai review on the pull request.
• Continue discussions: Reply directly to Sourcery's review comments.
• Generate a GitHub issue from a review comment: Ask Sourcery to create an
  issue from a review comment by replying to it. You can also reply to a
  review comment with @sourcery-ai issue to create an issue from it.
• Generate a pull request title: Write @sourcery-ai anywhere in the pull
  request title to generate a title at any time. You can also comment
  @sourcery-ai title on the pull request to (re-)generate the title at any time.
• Generate a pull request summary: Write @sourcery-ai summary anywhere in
  the pull request body to generate a PR summary at any time exactly where you
  want it. You can also comment @sourcery-ai summary on the pull request to
  (re-)generate the summary at any time.
• Generate reviewer's guide: Comment @sourcery-ai guide on the pull
  request to (re-)generate the reviewer's guide at any time.
• Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
  pull request to resolve all Sourcery comments. Useful if you've already
  addressed all the comments and don't want to see them anymore.
• Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
  request to dismiss all existing Sourcery reviews. Especially useful if you
  want to start fresh with a new review - don't forget to comment
  @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

• Enable or disable review features such as the Sourcery-generated pull request
  summary, the reviewer's guide, and others.
• Change the review language.
• Add, remove or edit custom review instructions.
• Adjust other review settings.

Getting Help

• Contact our support team for questions or feedback.
• Visit our documentation for detailed guides and information.
• Keep in touch with the Sourcery team by following us on X/Twitter, LinkedIn or GitHub.

[sourcery-ai]

Hey - I've left some high level feedback:

• Several skills (e.g., manual-testing) hard-code your local Windows paths and PowerShell usage (d:\code\twig-test-dir, twig.exe), which will be confusing or unusable on other environments—consider expressing paths relative to the repo and either making commands shell-agnostic or explicitly scoping the skill to Windows/PowerShell in the description.
• The pull-requests skill is not mentioned in the PR description’s skills list; if it’s intended to be a first-class workflow skill like the others, consider updating the summary/README so it’s discoverable alongside the existing development skills.

Prompt for AI Agents

Please address the comments from this code review:

## Overall Comments
- Several skills (e.g., `manual-testing`) hard-code your local Windows paths and PowerShell usage (`d:\code\twig-test-dir`, `twig.exe`), which will be confusing or unusable on other environments—consider expressing paths relative to the repo and either making commands shell-agnostic or explicitly scoping the skill to Windows/PowerShell in the description.
- The `pull-requests` skill is not mentioned in the PR description’s skills list; if it’s intended to be a first-class workflow skill like the others, consider updating the summary/README so it’s discoverable alongside the existing development skills.

---

Sourcery is free for open source - if you like our reviews please consider sharing them ✨

• X
• Mastodon
• LinkedIn
• Facebook

_{Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.}