Skills

Skills are concise markdown files that give coding agents the context they need to write correct code in a specific domain. Each skill is ~35 lines and contains structured information that agents can act on immediately.

Anatomy of a skill

---
name: billing
description: Stripe billing — subscriptions, usage tracking, webhooks
triggers:
  files:
    - "**/billing*.ts"
    - "**/stripe*.ts"
  keywords:
    - stripe
    - subscription
    - invoice
    - webhook
---

You are working on **billing, Stripe integration, and usage limits**.

## Key Files
- `src/services/billing/stripe.ts` — Stripe SDK wrapper
- `src/services/billing/usage.ts` — Usage counters and limit checks

## Key Concepts
- **Webhook-driven:** Subscription state changes come from Stripe webhooks
- **Usage gating:** `checkLimit(userId, type)` returns structured 429 error data

## Critical Rules
- Webhook endpoint has NO auth middleware — verified by Stripe signature only
- Cancel = `cancel_at_period_end: true` (user keeps access until period end)

Sections

Frontmatter

• name — domain identifier (used for file path and cross-referencing)
• description — one-line summary (used in skill selection and indexing)
• triggers — activation rules for the skill:
  • files — glob patterns that activate the skill when a matching file is edited
  • keywords — words in a prompt that activate the skill
  • alwaysActivate — set to true to load the skill on every prompt

When a Claude hook detects you’re editing a matching file (or mentioning a keyword), the skill is automatically loaded.

Note

Skills used to declare activation in a free-form ## Activation section. As of 0.8.0, activation lives in the triggers: frontmatter block shown above, and new skills generated by doc init / doc sync emit that form. Legacy ## Activation sections still parse for backwards compatibility, so older skills keep working.

Key Files

The most important files for this domain. Agents use these as entry points when investigating or modifying code.

Key Concepts

Architecture patterns, conventions, and domain-specific knowledge. This is the “how things work” section.

Critical Rules

Gotchas, anti-patterns, and hard rules. Things agents must follow to avoid bugs or security issues.

Skill activation (Claude)

For Claude Code, skills activate automatically through hooks:

1. skill-activation-prompt.sh — runs on every prompt, matches against skill-rules.json keywords, intents, and file patterns
2. post-tool-use-tracker.sh — runs after file edits, tracks which domains have been touched in the session
3. Session-sticky skills — once a skill activates via file editing, it stays active for the session

Custom skills

Create your own skills for conventions not covered by auto-generation:

# Scaffold an empty skill
npx aspens add skill my-convention

# Generate from a reference document
npx aspens add skill release --from dev/release.md

Custom skills live alongside generated skills and are preserved during doc sync.

Skills for Codex and OpenCode

Codex and OpenCode skills use the same content format but live in different locations:

• Claude: .claude/skills/<name>/skill.md
• Codex: .agents/skills/<name>/SKILL.md
• OpenCode: .claude/skills/<name>/skill.md

Codex and OpenCode do not have Claude’s activation hooks, so skills are referenced through AGENTS.md instructions (and, for Codex, directory-scoped AGENTS.md files).