Skills

Skills allow you to extend PostQode with reusable, on-demand instruction sets for specialized tasks. Think of them as "plugins" that teach PostQode how to perform complex workflows or follow specific protocols.

Why Skills?

• At startup: PostQode sees only a brief description of each skill
• When triggered: PostQode loads the full instructions for that specific skill
• As needed: Skills can bundle additional files that PostQode reads only when referenced

Creating a Skill

A skill is defined by a directory containing a SKILL.md file.

my-skill/
├── SKILL.md          # Required: main instructions
├── docs/             # Optional: additional documentation
│   └── advanced.md
└── scripts/          # Optional: utility scripts
    └── helper.sh

The SKILL.md File

The SKILL.md file must contain a YAML frontmatter block with a name and description, followed by the detailed instructions.

---
name: my-skill
description: Brief description of what this skill does and when to use it.
---

# My Skill

Detailed instructions for PostQode to follow when this skill is activated.

## Steps

1. First, do this
2. Then do that
3. For advanced usage, see [advanced.md](docs/advanced.md)

• name: Must exactly match the directory name
• description: Tells PostQode when to use this skill (max 1024 characters)

Where Skills Live

The location of your skills directory depends on your operating system:

• macOS/Linux: ~/.postqode/skills/
• Windows: C:\Users\USERNAME\.postqode\skills\

You can also place skills in your project-specific configuration folders (depending on your setup):

• .postqode/skills/ (recommended)
• .postqoderules/skills/

Managing Skills

PostQode provides tools to manage your skills:

• View all available skills (global and workspace)
• Toggle individual skills on or off
• Create new skills from a template
• Delete skills you no longer need

How PostQode Uses Skills

When you ask PostQode to perform a task, it checks the descriptions of all available skills. If a skill seems relevant, PostQode will activate it and follow the instructions in its SKILL.md file.

For example, if you have an aws-deploy skill:

---
name: aws-deploy
description: Deploy applications to AWS using CDK. Use when deploying, updating infrastructure, or managing AWS resources.
---

When you say "Deploy the app to AWS", PostQode will see the aws-deploy skill description, load the full instructions, and guide you through the deployment process.

Example: Data Analysis Skill

Here is a complete example of a Data Analysis skill.

Directory Structure:

data-analysis/
└── SKILL.md

SKILL.md Content:

---
name: data-analysis
description: Analyze data files and generate insights. Use when working with CSV, Excel, or JSON data files that need exploration, cleaning, or visualization.
---

# Data Analysis

When analyzing data files, follow this workflow:

## 1. Understand the Data
- Read a sample of the file to understand its structure
- Identify column types and data quality issues
- Note any missing values or anomalies

## 2. Ask Clarifying Questions
Before diving in, ask the user:
- What specific insights are they looking for?
- Are there any known data quality issues?
- What format do they want for the output?

## 3. Perform Analysis
Use pandas for data manipulation:

\`\`\`python
import pandas as pd

# Load and explore
df = pd.read_csv("data.csv")
print(df.head())
print(df.describe())
print(df.info())
\`\`\`

For visualization, prefer matplotlib or seaborn depending on complexity.

## 4. Present Findings
- Start with a summary of key insights
- Support findings with specific numbers
- Include visualizations where they add clarity
- End with recommendations or next steps

Bundling Supporting Files

Skills can include supporting files like scripts, templates, or additional documentation.

complex-skill/
├── SKILL.md
├── docs/
│   ├── setup.md
│   └── troubleshooting.md
├── templates/
│   └── config.yaml
└── scripts/
    └── validate.py

In your SKILL.md, you can reference these files relative to the skill directory:

For initial setup, follow [setup.md](docs/setup.md).
Use the config template at `templates/config.yaml` as a starting point.

Run the validation script to check your configuration:
\`\`\`bash
python scripts/validate.py
\`\`\`

Ideas for Skills

• Release management: Version bumping, changelog generation, git tagging, and publishing
• Code review: Your team’s specific review checklist and quality standards
• Database migrations: Safely evolving schemas with rollback procedures
• API integration: Connecting to specific third-party services with proper error handling
• Documentation: Your preferred structure, style guide, and tooling
• Debugging workflows: Systematic approaches to diagnosing specific types of issues
• Infrastructure: Terraform/CDK patterns for your cloud setup

---

Packaged Built-in & Enterprise Skills

PostQode comes pre-bundled with a rich library of specialized skills for software engineering, architecture, code quality, QA automation, and release management:

Planning & Architecture Skills

Skill Name	Description
autoplan	Automated multi-phase task breakdown and implementation planning.
plan-ceo-review	High-level product vision and user journey review for feature plans.
plan-eng-review	In-depth engineering feasibility and architectural review.
plan-design-review	UI/UX design consistency and component structure review.
office-hours	Interactive technical consultation and decision alignment.

Code Quality & Security Skills

Skill Name	Description
review	In-depth code review for bugs, regressions, performance, and best practices.
cso	Chief Security Officer threat modeling, credential scan, and vulnerability auditing.
careful	High-caution execution mode for critical or destructive operations.
guard	Pre-execution safety validation for system commands and file edits.
checkpoint	Automated git checkpoint creation before risky refactoring.
freeze / unfreeze	Freezes or unfreezes target files to protect them from unintended modifications.

QA & Testing Skills

Skill Name	Description
qa	End-to-end web testing, form validation, and bug logging.
qa-only	Strict QA execution mode focused exclusively on verifying test criteria.
playwright	End-to-end browser automation and test generation using Playwright.

Release & DevOps Skills

Skill Name	Description
land-and-deploy	End-to-end pull request validation, CI checks, and release deployment.
ship	Streamlined release tagging, version bumping, and release note publishing.
canary	Post-deploy canary verification and live health validation.
health	Service health checks and uptime validation.
benchmark	Performance benchmarking and Core Web Vitals profiling.
document-release	Automated changelog and documentation updates for releases.

Design & Frontend Skills

Skill Name	Description
frontend-design	UI component styling, responsive layouts, and design system implementation.
design-review	Visual audits of live pages against design specifications.
design-html	Generates clean, accessible semantic HTML/CSS from design specs.
design-consultation	Consultative feedback on UI aesthetics and user experience.
design-shotgun	Rapid design exploration and multi-variant UI generation.

Developer Tools & Utilities

Skill Name	Description
docx	Reads and generates Microsoft Word (.docx) technical documentation.
learn	Extracts and persists reusable patterns into project memory.
investigate	Deep codebase exploration and root-cause tracing.
retro	Generates retrospective summaries of tasks and sessions.
skill-creator	Guides creating new custom skills with proper SKILL.md structure.
postqode-sdk	Integration guide and patterns for using the PostQode SDK.