# Planning Osprey Rules

> Use when gathering requirements for a new Osprey SML rule before any code is written. Not triggered on general coding tasks — only when planning what a rule should detect, which labels to apply, and what signals to use.

- **Type:** Skill
- **Install:** `agentstack add skill-skywatch-bsky-skywatch-agent-skills-planning-osprey-rules`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [skywatch-bsky](https://agentstack.voostack.com/s/skywatch-bsky)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [skywatch-bsky](https://github.com/skywatch-bsky)
- **Source:** https://github.com/skywatch-bsky/skywatch-agent-skills/tree/main/claude-skills/plugins/osprey-rules/skills/planning-osprey-rules
- **Website:** https://bsky.app/profile/skywatch.blue

## Install

```sh
agentstack add skill-skywatch-bsky-skywatch-agent-skills-planning-osprey-rules
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Planning Osprey Rules

This workflow guides you through gathering requirements and producing a structured
rule specification before any SML code is written.

## 1. Validate Input Context

The orchestrator provides you with context before you begin. Verify you have
everything you need.

**Required inputs (provided by orchestrator in your prompt):**
1. **Investigator report** — structured text report from `osprey-rule-investigator`
   containing project structure, labels table, model catalogue, UDF signatures,
   and execution graph map.
2. **User request** — what the user wants a rule for.

**Validate the investigator report contains:**
- Labels table (label names, valid_for, connotation)
- Model catalogue (variable names, types)
- UDF signatures (available functions)
- Execution graph map (Import/Require chains)

**If the investigator report is missing or incomplete:** Report what's missing and
ask the orchestrator to re-dispatch the investigator. Do NOT proceed without
project context.

## 2. Understand the Target Behaviour

Before writing any code, understand what the user wants to detect.

**Ask clarifying questions:**
1. **What event type?** (post, follow, identity, repost, etc.)
2. **What signals?** (text patterns, metadata, account age, etc.)
3. **What label to emit?** (must exist in `config/labels.yaml`)
4. **Expiration/validity?** (permanent, expiring, conditional)
5. **Who/what gets labeled?** (the account, the post, both?)

**Map to labeling patterns:**
- Chain to `osprey-sml-reference` skill to look up common labeling patterns if you
  need naming conventions or syntax examples.
- Document the detection logic in plain English before writing code.

Example user request:
> "I want to detect posts that contain profanity and label them with 'contains-profanity'."

Analysis:
- Event type: record (post)
- Signal: post text content contains profanity
- Label: contains-profanity (check labels.yaml to confirm it exists)
- Target: the post (AtUri)

## 3. Produce Rule Specification

After gathering requirements, produce a structured plain-text specification that the
implementation agent can use to write SML.

**Rule specification format:**

```
## Rule Specification: [Rule Name]

**Target behaviour:** [What the rule detects]
**Event type:** [Which AT Protocol event triggers the rule]
**Signals:** [What data points the rule examines]
**Models needed:** [ML models or UDFs required, referencing available ones from investigator report]
**Labels to apply:** [Which labels from config/labels.yaml to use]
**Target entity:** [What gets labeled — account, record, etc.]
**Effect type:** [LabelAdd, AtprotoLabel, DeclareVerdict, etc.]
**Expiration:** [Duration if applicable, using named constants: Day, Hour, Week]
**Guard conditions:** [Re-labeling prevention if needed]

**Detection logic (plain English):**
[Step-by-step description of what conditions trigger the rule]

**Examples:**
- Should catch: [content examples]
- Should NOT catch: [counter-examples]

**Edge cases:**
- [Boundary conditions discussed with the user]
```

**Confirm with user:** Present the specification and get explicit confirmation before
handing off to the implementation agent.

## 4. Skill Chaining

Load additional skills when you need specialized guidance during planning.

**When to chain to `osprey-sml-reference`:**
- Need to look up available labeling patterns
- Unsure of naming conventions for the planned rule
- Need to understand what effect types are available
- Want to verify a UDF exists or understand its signature

Load with: `Skill(skill='osprey-sml-reference')`

## 5. Common Mistakes

These are planning-phase mistakes that lead to problems downstream.

1. **Hardcoding label names not in `config/labels.yaml`**
   - Wrong: Plan a rule using a label without checking if it exists
   - Right: Check `config/labels.yaml` using the investigator report first
   - Impact: Validation fails when implementation agent writes the effect

2. **Not asking about the target entity**
   - Wrong: Assume every rule labels the account
   - Right: Ask whether the account, the post, or both should be labeled
   - Impact: Wrong entity type in models, must rewrite

3. **Skipping UDF availability check**
   - Wrong: Plan a rule assuming a UDF exists
   - Right: Check the investigator's UDF catalogue for available functions
   - Impact: Implementation agent discovers missing UDF mid-authoring

## 6. Rationalizations to Block

| Rationalization | Reality | Action |
| --- | --- | --- |
| "This label probably exists" | No. Labels must be explicitly configured. | Check the investigator report's labels table and confirm the label exists before including it in the spec. |
| "I know the type system" | No. SML type rules are strict. | Load `osprey-sml-reference` if uncertain about EntityJson vs JsonData. |
| "The investigator report looks fine" | No. Incomplete context causes downstream failures. | Validate every required section of the investigator report before proceeding. |
| "I'll figure out the entity type later" | No. Entity type determines model structure. | Ask the user what gets labeled (account, record, both) during requirements gathering. |
| "The user knows what they want" | Requirements need refinement. | Always ask clarifying questions even if the request seems clear. |

---

**Output:** A confirmed rule specification in plain text. Hand this to the
orchestrator, which passes it to `osprey-rule-impl` with the investigator report.

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [skywatch-bsky](https://github.com/skywatch-bsky)
- **Source:** [skywatch-bsky/skywatch-agent-skills](https://github.com/skywatch-bsky/skywatch-agent-skills)
- **License:** MIT
- **Homepage:** https://bsky.app/profile/skywatch.blue

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-skywatch-bsky-skywatch-agent-skills-planning-osprey-rules
- Seller: https://agentstack.voostack.com/s/skywatch-bsky
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.