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