# Pss Authoring

> Use when writing skills for PSS discovery or improving suggestion accuracy. Used by pss-agent-profiler. Trigger with /pss-authoring.

- Skill: `emasoft/pss-authoring` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add emasoft/pss-authoring`
- Raw SKILL.md: https://api.skillmd.com/api/skills/emasoft/pss-authoring/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Product & Planning
- Author: Emasoft (https://skillmd.com/u/emasoft)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/emasoft/pss-authoring

---


# PSS Authoring Best Practices

## Overview

Guidance for writing skills that PSS discovers effectively, maintaining index health, and interpreting suggestions accurately. Complements pss-usage (core commands and workflows).

## Prerequisites

- PSS plugin installed and enabled
- Familiarity with SKILL.md frontmatter format
- Index built via `/pss-reindex-skills`

## Instructions

1. Add proper frontmatter to your SKILL.md (name, description, categories, keywords)
2. Choose keywords that match how users naturally phrase requests
3. Select 1-2 categories from the 16 standard options
4. Reindex after any metadata changes
5. Use `/pss-status` to verify index health regularly

### Checklist

Copy this checklist and track your progress:

- [ ] Frontmatter includes name, description, categories, keywords
- [ ] Keywords match natural user phrasing
- [ ] Categories selected from standard list
- [ ] Index rebuilt after changes (`/pss-reindex-skills`)
- [ ] Suggestion quality verified with test prompts

## How PSS Indexes Your Skills

The canonical index is a CozoDB store (`pss-skill-index.db`), not the legacy `skill-index.json` file. What authoring-side reindexing actually does:

1. `pss_discover.py` walks user / project / plugin / marketplace directories and emits one JSONL line per element.
2. The Rust binary's `--pass1-batch` mode reads that JSONL and enriches each line with deterministic keywords, intents, categories, domains, languages, and frameworks.
3. `pss_merge_queue.py` writes the enriched rows directly into CozoDB via `pycozo[embedded]` under an `fcntl` lock, preserving each entry's original `first_indexed_at` timestamp across rebuilds.

Python is the sole writer; the Rust `--build-db` flag has been removed. `skill-index.json` is no longer auto-generated — run `pss export --json` on demand if you want a diffable snapshot for code review. Nothing about authoring your SKILL.md changes: frontmatter rules, keyword selection, and category choices remain unchanged.

## References

- [Best Practices](references/pss-best-practices.md)
  - When to reindex your skill index
    - Events that always require reindexing
    - Events that may not require reindexing
  - Interpreting PSS skill suggestions accurately
    - Trusting confidence levels: HIGH, MEDIUM, LOW
    - Reading evidence types: intent, keyword, co_usage
    - Evaluating suggestions with multiple evidence types
  - Maintaining index health over time
    - Regular health checks with /pss-status
    - Keeping skill metadata current
    - Periodic clean rebuilds of the index
- [Skill Authoring Tips](references/pss-skill-authoring-tips.md)
  - Making your skills discoverable by PSS
    - Essential frontmatter fields for PSS indexing
    - Choosing effective keywords that match user prompts
    - Selecting accurate categories from the 16 standard options
  - Improving suggestion quality for your skills
    - Writing descriptions that help PSS match intent
    - Including tool and action keywords
    - Leveraging co-usage relationships automatically
  - Reference: Standard categories list

## Output

Improved skill metadata and index quality. Skills with proper frontmatter appear in PSS suggestions with higher confidence.

## Error Handling

- **Skills not appearing**: Check frontmatter has `keywords` and `categories`
- **Low confidence**: Improve description specificity and keyword coverage
- **Stale suggestions**: Run `/pss-reindex-skills` after metadata changes

## Examples

Input: A skill with generic description "Does testing"
Output: Improved to "Use when writing pytest unit tests with fixtures and mocking. Trigger with /python-testing."

## Resources

- **Standard categories**: `${CLAUDE_PLUGIN_ROOT}/schemas/pss-categories.json`
- **Companion skill**: pss-usage (core commands and workflows)