PSS Usage Skill

Overview

Perfect Skill Suggester (PSS) is an AI-powered plugin that automatically suggests relevant skills based on your prompts. This skill teaches you how to use PSS commands (/pss-status, /pss-reindex-skills), interpret skill suggestion output with confidence levels (HIGH/MEDIUM/LOW) and evidence types (intent/keyword/co_usage), and maintain the skill index for optimal performance.

Prerequisites

Before using PSS, ensure:

•PSS plugin is installed and enabled - Verify with /plugin list
•Skills are available - At least one skill directory exists in ~/.claude/skills/ or project .claude/skills/
•Index has been built - Run /pss-reindex-skills at least once after installation
•Write permissions - PSS needs to write skill-index.json to ~/.claude/ directory

If index has never been built, PSS will show "Index file missing" error when trying to suggest skills.

When to Use This Skill

Activate this skill when:

•User asks about skill suggestions ("which skills should I use?")
•User asks about PSS functionality ("how does skill suggestion work?")
•User requests reindexing ("update the skill index", "refresh skills")
•User asks for PSS status ("is PSS working?", "show me PSS info")
•Skill suggestions appear empty or incorrect
•PSS commands fail or produce errors

Do NOT activate for:

•General skill activation (use skill-specific skills instead)
•Writing skill content (use skill authoring skills instead)
•Plugin development (use plugin development skills instead)

Instructions

Step-by-Step Usage

•
Verify PSS is working - Run the status command to confirm the index exists and shows a recent timestamp:
code
```
/pss-status
```
•
Build or rebuild the index after installing skills - Run the reindex command and wait for the "Phase 2: Analysis... Index updated successfully" message:
code
```
/pss-reindex-skills
```
•
Use natural prompts and review suggestions - Enter a prompt describing the task; PSS will suggest relevant skills with confidence levels and evidence:
code
```
"I need to write Python unit tests"
```
•
Activate HIGH confidence skills - Activate skills that PSS rates as HIGH confidence, review MEDIUM confidence based on evidence, and skip LOW confidence:
code
```
/skill activate python-test-writer
```
•
Reindex after major changes - Run /pss-reindex-skills after installing, modifying, or deleting skills to keep suggestions accurate.

Quick Reference

Most Common Tasks

Task	Command	When to Use
Check PSS health	`/pss-status`	Before first use, after installing skills, when debugging issues
Rebuild skill index	`/pss-reindex-skills`	After adding/modifying skills, when suggestions are stale
Understand suggestion	Read confidence + evidence	Every time PSS suggests skills

Command Quick Examples

Check if PSS is working:

code

/pss-status

Expected output:

code

Perfect Skill Suggester Status
==============================
Index Status: ✓ Exists
Total Skills Indexed: 42

Rebuild the index after adding skills:

code

/pss-reindex-skills

⛔ CRITICAL: PSS reindexing ALWAYS performs a FULL regeneration from scratch. The command first deletes ALL previous index data (skill-index.json, all .pss files, checklist), then discovers and analyzes ALL skills fresh. There is NO incremental update mode. This is mandatory to prevent stale paths, orphaned entries, and name mismatches.

Expected output:

code

Phase 0: Clean slate...
  ✓ Deleted skill-index.json
  ✓ Deleted 42 .pss files
  ✓ Clean slate verified

Phase 1: Discovery...
  ✓ Found 45 skills

Phase 2: Analysis...
  ✓ Index updated successfully

Detailed Command Reference

For comprehensive information about all PSS commands, see pss-commands.md:

Contents of pss-commands.md

•
1.0 Understanding PSS command structure and invocation
- •1.1 Command naming conventions
- •1.2 Command invocation from Claude Code chat
•
2.0 Using /pss-status to check PSS configuration and index health
- •2.1 Basic /pss-status usage without arguments
- •2.2 Understanding /pss-status output: index statistics
- •2.3 Understanding /pss-status output: skill counts and categories
- •2.4 Interpreting /pss-status warnings and errors
•
3.0 Using /pss-reindex-skills to rebuild the skill index
- •3.1 When to reindex: detecting stale skill data
- •3.2 Running /pss-reindex-skills workflow step-by-step
- •3.3 Understanding reindex progress and completion messages
- •3.4 Verifying successful reindexing with /pss-status
•
4.0 Interpreting PSS skill suggestion output
- •4.1 Understanding confidence levels: HIGH, MEDIUM, LOW
- •4.2 Understanding evidence types: intent, keyword, co_usage
- •4.3 Reading the skill suggestion table format
- •4.4 Deciding when to activate suggested skills
•
5.0 Troubleshooting common PSS issues
- •5.1 PSS commands not found or not responding
- •5.2 Empty or missing skill suggestions
- •5.3 Index file errors or corruption
- •5.4 Reindexing failures and recovery

Output

Understanding PSS Suggestion Output

When PSS suggests skills, you will see output like:

code

Suggested Skills
================

Skill                    Confidence  Evidence
-----------------------------------------------
python-test-writer       HIGH        intent:testing, keyword:pytest, keyword:unittest
docker-deploy            MEDIUM      keyword:docker, co_usage:github-actions-ci(0.7)
code-reviewer            LOW         co_usage:python-test-writer(0.5)

Reading This Table

Columns explained:

•Skill: The skill identifier (use this with /skill activate <skill>)
•Confidence: How strongly PSS recommends (HIGH/MEDIUM/LOW)
•Evidence: Why PSS suggested this (intent match, keyword match, co-usage relationship)

Evidence types:

•intent:<category> - Your prompt matches this skill category
•keyword:<word> - Your prompt contains this keyword defined by the skill
•co_usage:<skill>(<weight>) - This skill is often used with another mentioned skill

Decision Framework

For HIGH confidence suggestions:

•Default action: Activate the skill
•Why: Strong evidence indicates relevance
•Skip only if: You are certain the skill is not needed

For MEDIUM confidence suggestions:

•Default action: Review the evidence and decide
•Consider: Does the evidence align with your task?
•Activate if: Intent or keywords match your goal

For LOW confidence suggestions:

•Default action: Skip the skill
•Why: Speculative suggestion based on co-usage only
•Activate only if: You specifically recognize the skill as needed

Example decision process:

Prompt: "Write unit tests for the authentication module"

PSS suggests:

•
python-test-writer (HIGH, intent:testing, keyword:unit, keyword:tests)
- •Action: ACTIVATE - Directly needed for writing tests
•
auth-security-checker (MEDIUM, keyword:authentication, co_usage:python-test-writer(0.7))
- •Action: ACTIVATE - Relevant for testing auth logic
•
docker-deploy (LOW, co_usage:python-test-writer(0.3))
- •Action: SKIP - Not relevant to writing tests

For detailed explanation of confidence levels and evidence scoring, see section 4.0 in pss-commands.md.

Common Workflows

Workflow 1: First-Time PSS Setup

Scenario: You just installed PSS and want to verify it works.

Steps:

•
Check initial status
code
```
/pss-status
```
Expected: "Index file missing" or old index
•
Build the index
code
```
/pss-reindex-skills
```
Wait for completion (1-2 minutes)
•
Verify success
code
```
/pss-status
```
Expected: "Index Status: ✓ Exists", recent timestamp
•
Test with a prompt
code
```
"I need to write Python unit tests"
```
Expected: PSS suggests relevant testing skills with HIGH confidence

If any step fails: See troubleshooting in section 5.0 of pss-commands.md.

Workflow 2: Adding New Skills

Scenario: You installed new skills from a marketplace.

Steps:

•
Install skills (via marketplace or manual installation)
code
```
/plugin install new-skill-pack
```
•
Reindex immediately
code
```
/pss-reindex-skills
```
Why: PSS does not auto-detect new skills
•
Verify new skills indexed
code
```
/pss-status
```
Check: "Total Skills Indexed" should increase
•
Test suggestion Create a prompt using keywords from the new skills

Expected: New skills appear in PSS suggestions

Workflow 3: Debugging Missing Suggestions

Scenario: PSS should suggest a skill but does not.

Steps:

•
Check PSS is working
code
```
/pss-status
```
Verify: "Index Status: ✓ Exists", no errors
•
Reindex to refresh
code
```
/pss-reindex-skills
```
•
Check skill metadata
- •Open the skill's SKILL.md
- •Verify frontmatter has keywords and categories
- •Check if your prompt keywords match skill keywords
•
Try explicit keywords Rephrase your prompt to use exact keywords from skill frontmatter

Example: If skill has keywords: ["pytest", "unittest"], try:
code
```
"Write pytest tests for the API"
```
•
Check skill is available to agent
- •PSS only suggests skills the current agent can use
- •Review agent's frontmatter available_skills list
- •If skill missing, add it to agent's skill list

For detailed troubleshooting, see section 5.2 in pss-commands.md.

Error Handling

Problem: PSS commands not found

•See section 5.1 in pss-commands.md
•Quick fix: Check plugin enabled with /plugin list

Problem: No skill suggestions

•See section 5.2 in pss-commands.md
•Quick fix: Run /pss-reindex-skills

Problem: Index file corrupted

•See section 5.3 in pss-commands.md
•Quick fix: Delete ~/.claude/skill_index.json and reindex

Problem: Reindexing fails

•See section 5.4 in pss-commands.md
•Quick fix: Check error message, verify skills directories exist

Best Practices

When to Reindex

Always reindex after:

•Installing new skills
•Modifying skill metadata (name, description, keywords, categories)
•Moving skills between directories
•Deleting skills

Check but may not need reindex:

•Modifying skill content (SKILL.md body, references)
•Adding/removing skill references (does not affect suggestions)

Interpreting Suggestions

Trust the confidence level:

•HIGH = activate unless you know better
•MEDIUM = consider the evidence
•LOW = skip unless you recognize the need

Read the evidence:

•intent evidence is strongest (semantic understanding)
•keyword evidence is explicit (word matching)
•co_usage evidence is weakest (correlation only)

Multiple evidence types are stronger:

•intent:testing, keyword:pytest = very strong
•keyword:docker alone = moderate
•co_usage:skill(0.5) alone = weak

Maintaining Index Health

Regular checks:

•Run /pss-status weekly or after major skill changes
•Look for warnings about stale index
•Verify skill counts match expectations

Keep metadata current:

•Update skill keywords when adding new features
•Review skill categories for accuracy
•Add co-usage hints in skill descriptions

Clean index occasionally:

•Delete index file every few months
•Rebuild with /pss-reindex-skills
•Ensures AI co-usage analysis is fresh

Examples

Example 1: Testing Workflow

User prompt:

code

"Write pytest tests for the authentication module"

PSS suggests:

•python-test-writer (HIGH, intent:testing, keyword:pytest, keyword:tests)
•auth-security-checker (MEDIUM, keyword:authentication, co_usage:python-test-writer(0.7))
•docker-deploy (LOW, co_usage:python-test-writer(0.3))

Actions:

•Activate python-test-writer (HIGH confidence, directly needed)
•Activate auth-security-checker (MEDIUM confidence, relevant for auth testing)
•Skip docker-deploy (LOW confidence, not relevant to test writing)

Example 2: First-Time Setup

Commands:

code

/pss-status

Output: "Index file missing"

code

/pss-reindex-skills

Output: "Phase 2: Analysis... ✓ Index updated successfully. Total: 42 skills"

code

/pss-status

Output: "Index Status: ✓ Exists. Total Skills Indexed: 42"

Result: PSS is now ready to suggest skills.

Example 3: Debugging Missing Suggestions

Problem: Expected skill not suggested.

Steps:

•Check PSS health: /pss-status → Index exists
•Refresh index: /pss-reindex-skills → Completed successfully
•Verify skill metadata: Open SKILL.md, check frontmatter has keywords and categories
•Rephrase prompt with explicit keywords: "Write pytest unit tests" → python-test-writer now appears

Resolution: Keyword matching is sensitive; use exact terms from skill metadata.

Resources

Related Skills

•Skill authoring skills - For creating/modifying skills that PSS will index
•Plugin development skills - For modifying PSS plugin behavior

External References

•Agent Skills Open Standard - https://github.com/agentskills/agentskills
•Claude Code Documentation - https://platform.claude.com/llms.txt

Summary

Two commands, simple usage:

•/pss-status - Check PSS health
•/pss-reindex-skills - Rebuild skill index

Three confidence levels:

•HIGH - Activate by default
•MEDIUM - Review evidence
•LOW - Skip unless certain

Three evidence types:

•intent - Semantic category match
•keyword - Word match
•co_usage - Related skill correlation

For complete details, see:

•pss-commands.md - Full command reference and troubleshooting

Notes for Skill Authors

If you are developing skills and want PSS to suggest them effectively:

Essential frontmatter fields:

yaml

---
name: my-skill
description: "When and why to use this skill (be specific!)"
categories: ["testing", "debugging"]  # Pick from 16 standard categories
keywords: ["pytest", "unittest", "test-fixture", "mock"]
---

Tips for better suggestions:

•Use specific keywords that users naturally type
•Include tool names (pytest, docker, git, etc.)
•Include action verbs (debug, deploy, refactor, etc.)
•Mention common use cases in description
•Choose accurate categories from the 16 standard options

Categories list: debugging, testing, deployment, refactoring, documentation, performance, security, database, api, frontend, backend, devops, data-processing, ml-ai, collaboration, other

Co-usage relationships:

•PSS automatically detects co-usage during indexing
•Mention related skills in your SKILL.md content
•Reference complementary skills in examples
•No manual co-usage configuration needed

For PSS architecture and design, see docs/PSS-ARCHITECTURE.md in the PSS plugin directory.

pss-usage

PSS Usage Skill

Overview

Prerequisites

When to Use This Skill

Instructions

Step-by-Step Usage

Quick Reference

Most Common Tasks

Command Quick Examples

Detailed Command Reference

Contents of pss-commands.md

Output

Understanding PSS Suggestion Output

Reading This Table

Decision Framework

Common Workflows

Workflow 1: First-Time PSS Setup

Workflow 2: Adding New Skills

Workflow 3: Debugging Missing Suggestions

Error Handling

Best Practices

When to Reindex

Interpreting Suggestions

Maintaining Index Health

Examples

Example 1: Testing Workflow

Example 2: First-Time Setup

Example 3: Debugging Missing Suggestions

Resources

Related Documentation

Related Skills

External References

Summary

Notes for Skill Authors