@hyperflow.fun/ghost 0.0.1

package/dist/skills/builtin/pre-trade-advisory/SKILL.md

@@ -0,0 +1,203 @@
+---
+name: pre-trade-advisory
+description: "Pre-trade context check before entering a trade. Gather portfolio state, funding, technical picture and share your take. Triggers: should I, good time to, pre-trade check, before I trade, what do you think about."
+always: true
+---
+
+# Pre-Trade Advisory
+
+Two modes — fast auto-check when placing orders, or full analysis when the trader asks.
+
+## Mode 1: Auto (trade execution flow)
+
+Triggers when the trader is placing an order ("long BTC 1k 20x market"). Runs BEFORE the confirmation step.
+
+**Output:** Concise — risk level + reason + suggested SL/TP + warning if any. 3-5 sentences max.
+
+### Gather Context (parallel)
+
+**MANDATORY: Call ALL tools below in parallel. Do not skip any. Every data point matters for the advisory.**
+
+```
+ghost_get_positions()                          → existing exposure
+ghost_get_balance()                            → margin situation
+ghost_get_price(symbol)                        → current price
+ghost_get_funding_rates(symbol)                → funding direction
+ghost_get_indicators(symbol, "4h")             → trend, momentum, volatility
+ghost_get_levels(symbol, "4h")                 → key S/R for SL/TP
+ghost_news_search({ coins: ["[SYMBOL]"] })     → local crawled articles
+ghost_tweets_search({ coins: ["[SYMBOL]"] })   → tweets from followed accounts
+web_search("[SYMBOL] crypto news today")       → broader / breaking coverage (for query angles when results are thin, see market-intel "Search query strategy")
+ghost_timing_risk(symbol)                      → timing risks (weekend, events, post-volatility)
+ghost_get_trade_history({ symbol, lookbackHours: 168 })  → trader's fills on this symbol (last 7d). If empty, follow up with { symbol, limit: 100 } to capture the last 100 fills regardless of date — less active traders may not have any in 7d but still have a track record.
+```
+
+### News Check
+
+Scan results from all three news tools (`ghost_news_search`, `ghost_tweets_search`, `web_search`) for urgent events:
+- **Urgent events** (hack, exploit, delisting, SEC action, exchange insolvency) → prominently flag at the top of your advisory with a warning
+- **Relevant catalysts** (upgrade, partnership, listing, regulatory clarity) → mention briefly as supporting context
+- **Cross-check tweets** — sudden whale / dev commentary often breaks before articles catch up
+- If no meaningful news → skip, don't mention the absence
+
+### Timing Risk
+
+Check timing risk results and incorporate into your advisory:
+- **High severity** (FOMC today, post-volatility) → warn prominently, suggest waiting or smaller size
+- **Medium severity** (weekend, upcoming event) → mention as a factor in your risk assessment
+- **Low severity** → mention only if it adds context to the trade thesis
+
+### What to Say
+
+Lead with your quick take, then:
+- **Risk level** in plain words — "this is moderate risk because..." (not scores or ratings)
+- **Suggested SL** — nearest structural support/resistance. Always concrete price.
+- **Suggested TP** — next key level or R:R-derived. Always concrete price.
+- **Warning** if any — thin margin, concentrated exposure, revenge pattern, timing risk
+
+Example (good — advisory text + tool call in same response):
+> BTC below EMA50, 4h still downtrending. Longing against the trend — SL $65,000 (support tested 3 times), TP $69,500 (nearest resistance). Funding negative, carry cost low.
+> [+ ghost_bracket_order call → UI shows confirmation card with exact R:R alongside this text]
+
+**Do NOT ask "confirm?" or "ready to place?" in chat.** The confirmation card appears automatically with the advisory. Trader approves on the card.
+
+Example (bad):
+> EMA9: 66,500, EMA21: 66,800, EMA50: 67,200, EMA200: 65,000, RSI: 44.8, ADX: 18.7, VWAP: 68,700...
+
+**Don't dump indicators.** Pick the 1-2 that matter most for THIS trade.
+
+## Mode 2: On-demand (trader asks for opinion)
+
+Triggers when the trader asks "should I long BTC?", "what do you think?", "is now a good time?"
+
+**Output:** Full assessment — clear YES/NO/WAIT + conviction, bullish & bearish factors, suggested entry/SL/TP.
+
+### Gather Context (parallel)
+
+**MANDATORY: Call ALL tools below in parallel. Do not skip any. Every data point matters for the advisory.**
+
+```
+ghost_get_positions()                          → what you're already holding
+ghost_get_balance()                            → margin situation
+ghost_get_price(symbol)                        → current price + 24h change
+ghost_get_funding_rates(symbol)                → who's paying whom
+ghost_get_indicators(symbol, "4h")             → trend, momentum, volatility
+ghost_get_levels(symbol, "4h")                 → key S/R levels
+ghost_news_search({ coins: ["[SYMBOL]"] })     → local crawled articles
+ghost_tweets_search({ coins: ["[SYMBOL]"] })   → tweets from followed accounts
+web_search("[SYMBOL] crypto news today")       → broader / breaking coverage (for query angles when results are thin, see market-intel "Search query strategy")
+ghost_timing_risk(symbol)                      → timing risks
+ghost_get_trade_history({ symbol, lookbackHours: 168 })  → trader's fills on this symbol (last 7d). If empty, follow up with { symbol, limit: 100 } to capture the last 100 fills regardless of date — less active traders may not have any in 7d but still have a track record.
+```
+
+### What to Say
+
+1. **Your take** — YES / NO / WAIT with conviction level in plain words ("fairly confident", "50-50", "not yet")
+2. **Bullish factors** — 2-3 key supporting data points
+3. **Bearish factors** — 2-3 key opposing data points
+4. **Suggested entry/SL/TP** — Concrete prices based on S/R levels, R:R ratio
+5. **If NO or WAIT** — What conditions would make it a YES
+
+Example:
+> Leaning WAIT on longing BTC right now.
+>
+> For: Negative funding (shorts paying longs), $65k support is solid (tested 3 times), buy volume picking up.
+> Against: Price below EMA50/200 on 4h, ADX 32 shows downtrend still strong, resistance near $68.5k.
+>
+> If entering: Entry $66,800, SL $64,800 (below support), TP1 $68,500 (take 50%), TP2 $70,000. R:R 1:2.
+> Better to wait for a retest of $65k and see if it holds.
+
+## Proactive News for Held Positions
+
+When the trader holds open positions and you come across urgent news (through any conversation or tool call):
+- If news reveals an urgent event (hack, exploit, delisting, SEC action, exchange insolvency, protocol vulnerability) affecting a held asset → surface it immediately
+- Frame it as: what happened, how it might affect their position, and a suggested action (reduce, close, or monitor)
+- Don't panic — be factual and let the trader decide
+
+## Risk Assessment (both modes)
+
+### Layer 1 — Objective (same for everyone)
+- Leverage vs volatility — 20x on a high-ATR coin is objectively risky
+- Distance to liquidation
+- Funding cost direction and magnitude
+- Timing risk: major events within 24h (CPI, FOMC, token unlock), low liquidity hours
+- Post-pump entry: spread still wide? Orderbook thin?
+- Total portfolio exposure after this order (all positions + new)
+- Correlation risk: multiple positions in same direction/sector
+
+### Layer 2 — Personal filter
+
+Use the fills returned by `ghost_get_trade_history` (symbol-scoped, last 7 days) as the data source. Look for:
+
+- **Recent loss on this symbol** — last fill on this coin closed in the red, especially if same direction as the new order
+- **Streak** — 3+ consecutive losers (or winners) on the symbol
+- **Size deviation** — current order size noticeably larger than the trader's typical fill size on this coin
+- **Leverage drift** — leverage on this order higher than recent fills on the same coin
+- **Repeated entries** — multiple attempts at the same direction within the window
+- **Cold start** — coin not in watchlist or no fills at all → mention as "first time on this coin" context
+- **Outside usual hours** — fills in this window cluster in one part of the day, current order is outside that
+
+Surface a personal-filter signal only when it's actionable for THIS trade. The agent decides whether to mention; not every advisory needs a history line.
+
+**Small-sample guard:** if the trader has fewer than 3 fills on this symbol within the window, the data is too thin to call out specific patterns (revenge, deviation, streak). Skip the personal filter entirely rather than over-interpret.
+
+**Tone:** name the pattern gently — observe, don't lecture. "Last 2 BTC trades closed red — worth a pause before sizing up" beats "you've lost 2 BTC trades, don't long again." Never weaponize the trader's history.
+
+**Never conflate Layer 1 and Layer 2.** A 50x trade is high risk regardless of who places it. Personal filter adds warnings, doesn't reduce objective risk.
+
+## Emotional State Detection
+
+Read the trader's message for emotional signals BEFORE responding.
+
+### FOMO signals
+- Urgency language: rushing to enter, wants to buy NOW
+- Chasing: mentions pump/Twitter/hype, asking AFTER price already moved significantly
+- Skipping steps: jumps to execution without asking for analysis first
+
+**Response:** Name it gently — don't lecture. Acknowledge the excitement, then show data that provides perspective (funding crowded, price already moved a lot, no strong support at current level). Include a Plan B (see below).
+
+### Revenge signals
+- Recent loss mentioned or visible in trade history
+- Bigger size or higher leverage than their usual
+- Same coin/direction as the losing trade
+
+**Response:** Name the pattern directly. Reference their recent loss. Suggest taking a break before entering.
+
+### Paralysis signals
+- Excessive hedging in language ("but...", "afraid to miss...", "wait a bit more...")
+- Asking the same question multiple ways
+- Has enough information but won't commit
+
+**Response:** Don't add more data — it feeds the paralysis. Give ONE clear verdict with specific levels. Skip the For/Against format — it invites more deliberation.
+
+### Plan B rule
+When advising WAIT or NO, always include a safer alternative: "If you really want to enter now, use lower leverage, tight stop loss at $X, smaller size than usual." This respects the trader's autonomy while guiding toward a safer version.
+
+## Don't Over-Rely on Technical Analysis
+
+Pick the 2-3 indicators that matter most for THIS trade. Don't dump everything.
+
+**Good:** "RSI 72 — stretched, pullback risk higher. Price near resistance at $85.50."
+**Bad:** "EMA9: 84.2, EMA21: 83.5, EMA50: 82.1, EMA200: 80.3, RSI: 72, StochRSI: 95/88, MACD: +0.4, ADX: 25, CCI: +162, Williams: -12, OBV: rising, ATR: 1.89..."
+
+Common terms (RSI, EMA, support/resistance, funding) are fine — most traders know them. But always pair values with meaning:
+- "RSI 72 — stretched" (not just "RSI 72")
+- "Below EMA200 — bigger trend is down" (not just "below EMA200")
+- "BB squeezing — big move building" (not just "BB bandwidth narrowing")
+
+Lead with your conclusion. Support with the 2-3 most relevant data points. Skip the rest.
+
+## Key Principles
+
+- **Have a view** — You're a companion, not a data terminal. Say what you think.
+- **Always suggest SL/TP** — Based on S/R structure and R:R ratio. Never arbitrary percentages unless no structure data available.
+- **Don't block** — Warn, advise, respect the trader's decision.
+- **Concise** — Auto mode: 3-5 sentences. On-demand: still under 10 sentences.
+- **Match risk level to reality** — Chasing a pump + high leverage + against the trend = HIGH risk. Never downplay to "moderate".
+- **Adapt to experience level** — Don't explain basic concepts to experienced traders. Skip the 101 for veterans.
+
+## Chart
+
+When the advisory cites TA indicators or levels, emit `<chart>` per the technical-analysis chart emission rule.
+
+For news handling, see market-intel.

package/dist/skills/builtin/risk-manager/SKILL.md

@@ -0,0 +1,124 @@
+---
+name: risk-manager
+description: "Position sizing, SL/TP placement, and margin calculations. Triggers: how much, position size, SL, TP, stop loss, take profit, R:R, liquidation, margin, add margin, reduce."
+---
+
+# Risk Manager
+
+Help with the math: position sizing, stop loss / take profit placement, and margin.
+
+## Two-Layer Risk Model
+
+- **Layer 1 — Objective market risk** (same for everyone): Leverage vs volatility, distance to liquidation, funding cost, total exposure, correlation between positions, timing risk. A 50x long is objectively high-risk regardless of who places it.
+- **Layer 2 — Personal risk filter**: Compare against trader's risk appetite and history. Flag deviations (unusual leverage, oversized position, coin outside watchlist). This layer warns, not reduces objective risk.
+
+## Behavioral Risk Check
+
+Before giving risk advice, check if the trader's request matches a known bad pattern:
+
+### Early exit pattern
+Trader wants to take profit early on a winning position.
+Don't validate early exits by default. Push back gently: suggest moving SL to breakeven instead of closing. Show what they'd gain by holding to the original target.
+
+### Adding to winners recklessly
+Trader wants to increase position size after unrealized profit.
+Check total leverage and exposure FIRST. If adding would push leverage beyond their normal range, flag it and suggest a smaller add size.
+
+### One clear action rule
+For traders who are stressed, rushed, or indecisive — give ONE specific recommendation, not a menu of options. Multiple options add decision burden when the trader is already struggling to decide.
+
+## Position Sizing
+
+### By risk amount
+```
+size = (equity × risk_pct) / |entry - stop_loss|
+
+Example: $25,000 equity, 2% risk, entry $67,000, SL $65,000
+  Risk = $500, Size = $500 / $2,000 = 0.25 BTC
+```
+
+### By dollar amount
+```
+"$5000 worth of BTC" → size = $5,000 / mark_price
+```
+
+### By leverage
+```
+"5x BTC" → size = (margin × leverage) / mark_price
+```
+
+Always show the dollar risk implied by the chosen size.
+
+### Lead with the Bottom Line
+
+Traders want to know "how much do I lose if wrong?" before the formula.
+
+- Lead with: "If this goes wrong, you lose $X (Y% of your account)"
+- Then show SL level and why (nearest support/resistance where the idea breaks)
+- Show formulas only when trader asks or when the math is non-obvious
+
+## SL/TP Placement
+
+### Stop Loss
+
+Find levels from structure, not arbitrary percentages:
+
+1. **Chart structure** — Use `ghost_get_levels(symbol)` to find tested support/resistance zones. Place SL below nearest support (longs) or above nearest resistance (shorts). Prefer levels tested 2+ times. Place slightly beyond (0.3-0.5% past wicks).
+
+2. **ATR-based** — Use `ghost_get_indicators(symbol, "1h", ["atr"])` for ATR(14). When no clear structure: 1.5-2x ATR from entry. Show the calculation.
+
+3. **Percentage fallback** — 2-5% from entry depending on leverage. Only when klines unavailable.
+
+SL must always trigger before liquidation. If it doesn't, say so.
+
+### Take Profit
+
+1. **Next key level** — Use `ghost_get_levels(symbol)` to find resistance (longs) or support (shorts) zones as TP targets.
+2. **R:R-derived** — If no clear level, set TP at 2x the SL distance.
+3. **Partial TP** — Suggest taking 50% at first target, trailing the rest.
+
+Show the math: risk amount, reward amount, R:R ratio.
+
+### Modifying existing TP/SL
+
+When the trader wants to change an existing stop or target (not add a fresh one), do NOT stack new orders on top of old ones — that leaves stale triggers on the book and can fire at the old price. The tool layer enforces 1 tool call = 1 step, so a "move" splits into two parallel tool calls in the same assistant response:
+
+1. Fetch `ghost_get_open_orders(symbol)` and read the trigger orders (each has `orderId`, `triggerPrice`, `orderType`).
+2. Match the trader's intent to the specific orderId(s) being replaced. With multiple TPs (TP1, TP2), only target the one the trader is changing.
+3. In ONE assistant response, emit two parallel tool calls: `ghost_cancel_order(orders: [{ id: <oldOrderId>, symbol }])` for the old trigger, and `ghost_set_sl_tp(symbol, stopLoss/takeProfit: <newPrice>)` for the new one. The orchestrator batches them into a single confirm card.
+
+If the trader's reference is ambiguous, ask before acting.
+
+## Liquidation Help
+
+**Always check `marginMode` from `ghost_get_positions()` first.** Liquidation mechanics differ:
+
+- **Isolated** — per-position margin. Adding margin moves the position's liq price directly. All three options below apply.
+- **Cross** — all positions share account equity; "add margin to this position" is meaningless. Liq is driven by total account margin vs. total exposure. Recommend: reduce size, close the position, or deposit more USDC at the account level. Do NOT suggest `ghost_adjust_margin` for cross positions.
+
+When someone's close to liquidation:
+
+If **isolated**, show three options with numbers:
+- **Add margin:** "Add $X → moves liq from $A to $B"
+- **Reduce size:** "Close 50% → moves liq from $A to $B"
+- **Close:** "Close now, PnL: $Z"
+
+If **cross**, show two options:
+- **Reduce size:** "Close 50% → frees $X account margin, moves liq from $A to $B"
+- **Close:** "Close now, PnL: $Z"
+- (Optional) "Deposit more USDC at the account level if you want to hold."
+
+## Chart
+
+When citing structural S/R or ATR, emit `<chart>` per the technical-analysis chart emission rule.
+
+## Tools
+
+```
+ghost_get_balance()                → equity, available margin
+ghost_get_positions()              → current positions, leverage, liq prices
+ghost_get_price()                  → mark price for calculations
+ghost_get_klines()                 → raw chart data
+ghost_get_levels(symbol)           → structural S/R for SL/TP placement
+ghost_get_indicators(symbol, indicators=["atr"]) → ATR for volatility-based stops
+```

package/dist/skills/builtin/skill-creator/SKILL.md

@@ -0,0 +1,68 @@
+---
+name: skill-creator
+description: Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
+---
+
+# Skill Creator
+
+Create effective, modular skills for Ghost. For detailed principles, anatomy, naming conventions, and progressive disclosure patterns, see [references/guide.md](references/guide.md).
+
+## Quick Reference
+
+```
+skill-name/
+├── SKILL.md          (required — frontmatter + instructions)
+├── scripts/          (deterministic, reusable code)
+├── references/       (docs loaded on demand)
+└── assets/           (templates, images for output)
+```
+
+**Ghost custom skills location:** `~/.ghost/workspace/skills/<skill-name>/SKILL.md`
+
+## Creation Process
+
+### Step 1: Understand — Gather Concrete Examples
+
+Ask the user:
+- What should this skill do? What are specific use cases?
+- What would a user say that should trigger this skill?
+- What variations or edge cases exist?
+
+Skip only when usage patterns are already clearly understood.
+
+### Step 2: Plan — Identify Reusable Contents
+
+For each use case, analyze:
+1. What code gets rewritten each time? → `scripts/`
+2. What documentation is needed for context? → `references/`
+3. What files appear in the output? → `assets/`
+
+### Step 3: Initialize — Create Directory Structure
+
+```bash
+mkdir -p ~/.ghost/workspace/skills/<skill-name>
+```
+
+Create SKILL.md with proper frontmatter. Add resource directories as needed.
+
+### Step 4: Edit — Implement the Skill
+
+1. **Start with bundled resources** — scripts, references, assets. Test scripts by running them.
+2. **Write SKILL.md:**
+   - **Frontmatter:** `name` + `description` (include all trigger phrases — body is only loaded after triggering)
+   - **Body:** Imperative form. Only include what's non-obvious to the agent. Keep under 500 lines.
+
+### Step 5: Package — Validate and Distribute
+
+Validate:
+- YAML frontmatter format and required fields
+- Naming conventions (lowercase, hyphens, <64 chars)
+- Description completeness
+- No symlinks (security restriction)
+
+### Step 6: Iterate — Improve from Real Usage
+
+1. Use the skill on real tasks
+2. Notice struggles or inefficiencies
+3. Update SKILL.md or bundled resources
+4. Test again

package/dist/skills/builtin/skill-creator/references/guide.md

@@ -0,0 +1,158 @@
+# Skill Creator — Detailed Guide
+
+## About Skills
+
+Skills are modular, self-contained packages that extend the agent's capabilities by providing
+specialized knowledge, workflows, and tools. Think of them as "onboarding guides" for specific
+domains or tasks—they transform the agent from a general-purpose agent into a specialized agent
+equipped with procedural knowledge that no model can fully possess.
+
+### What Skills Provide
+
+1. Specialized workflows - Multi-step procedures for specific domains
+2. Tool integrations - Instructions for working with specific file formats or APIs
+3. Domain expertise - Company-specific knowledge, schemas, business logic
+4. Bundled resources - Scripts, references, and assets for complex and repetitive tasks
+
+## Core Principles
+
+### Concise is Key
+
+The context window is a public good. Skills share the context window with everything else the agent needs: system prompt, conversation history, other Skills' metadata, and the actual user request.
+
+**Default assumption: the agent is already very smart.** Only add context the agent doesn't already have. Challenge each piece of information: "Does the agent really need this explanation?" and "Does this paragraph justify its token cost?"
+
+Prefer concise examples over verbose explanations.
+
+### Set Appropriate Degrees of Freedom
+
+Match the level of specificity to the task's fragility and variability:
+
+**High freedom (text-based instructions)**: Use when multiple approaches are valid, decisions depend on context, or heuristics guide the approach.
+
+**Medium freedom (pseudocode or scripts with parameters)**: Use when a preferred pattern exists, some variation is acceptable, or configuration affects behavior.
+
+**Low freedom (specific scripts, few parameters)**: Use when operations are fragile and error-prone, consistency is critical, or a specific sequence must be followed.
+
+Think of the agent as exploring a path: a narrow bridge with cliffs needs specific guardrails (low freedom), while an open field allows many routes (high freedom).
+
+## Anatomy of a Skill
+
+Every skill consists of a required SKILL.md file and optional bundled resources:
+
+```
+skill-name/
+├── SKILL.md (required)
+│   ├── YAML frontmatter metadata (required)
+│   │   ├── name: (required)
+│   │   └── description: (required)
+│   └── Markdown instructions (required)
+└── Bundled Resources (optional)
+    ├── scripts/          - Executable code (Python/Bash/etc.)
+    ├── references/       - Documentation intended to be loaded into context as needed
+    └── assets/           - Files used in output (templates, icons, fonts, etc.)
+```
+
+### SKILL.md (required)
+
+- **Frontmatter** (YAML): Contains `name` and `description` fields. These are the only fields that the agent reads to determine when the skill gets used, thus it is very important to be clear and comprehensive in describing what the skill is, and when it should be used.
+- **Body** (Markdown): Instructions and guidance for using the skill. Only loaded AFTER the skill triggers (if at all).
+
+### Bundled Resources (optional)
+
+#### Scripts (`scripts/`)
+
+Executable code (Python/Bash/etc.) for tasks that require deterministic reliability or are repeatedly rewritten.
+
+- **When to include**: When the same code is being rewritten repeatedly or deterministic reliability is needed
+- **Benefits**: Token efficient, deterministic, may be executed without loading into context
+
+#### References (`references/`)
+
+Documentation and reference material intended to be loaded as needed into context.
+
+- **When to include**: For documentation that the agent should reference while working
+- **Examples**: Database schemas, API documentation, domain knowledge, company policies
+- **Best practice**: If files are large (>10k words), include grep search patterns in SKILL.md
+- **Avoid duplication**: Information should live in either SKILL.md or references files, not both
+
+#### Assets (`assets/`)
+
+Files not intended to be loaded into context, but rather used within the output the agent produces.
+
+- **When to include**: When the skill needs files that will be used in the final output
+- **Examples**: Templates, images, icons, boilerplate code, fonts
+
+### What to Not Include in a Skill
+
+Do NOT create extraneous documentation: README.md, INSTALLATION_GUIDE.md, QUICK_REFERENCE.md, CHANGELOG.md, etc. The skill should only contain information needed for an AI agent to do the job.
+
+## Progressive Disclosure
+
+Skills use a three-level loading system to manage context efficiently:
+
+1. **Metadata (name + description)** - Always in context (~100 words)
+2. **SKILL.md body** - When skill triggers (<5k words)
+3. **Bundled resources** - As needed by the agent (Unlimited)
+
+Keep SKILL.md body to the essentials and under 500 lines. Split content into separate files when approaching this limit. When splitting, reference them from SKILL.md and describe clearly when to read them.
+
+### Progressive Disclosure Patterns
+
+**Pattern 1: High-level guide with references**
+
+```markdown
+# PDF Processing
+## Quick start
+[code example]
+## Advanced features
+- **Form filling**: See [FORMS.md](FORMS.md) for complete guide
+```
+
+**Pattern 2: Domain-specific organization**
+
+```
+bigquery-skill/
+├── SKILL.md (overview and navigation)
+└── reference/
+    ├── finance.md
+    ├── sales.md
+    └── product.md
+```
+
+**Pattern 3: Conditional details**
+
+```markdown
+## Creating documents
+Use docx-js for new documents. See [DOCX-JS.md](DOCX-JS.md).
+## Editing documents
+For simple edits, modify the XML directly.
+**For tracked changes**: See [REDLINING.md](REDLINING.md)
+```
+
+**Guidelines:**
+- Avoid deeply nested references — keep one level deep from SKILL.md
+- Structure longer reference files — include a table of contents for files >100 lines
+
+## Skill Naming
+
+- Use lowercase letters, digits, and hyphens only; normalize titles to hyphen-case
+- Under 64 characters
+- Prefer short, verb-led phrases that describe the action
+- Namespace by tool when it improves clarity (e.g., `gh-address-comments`)
+- Name the skill folder exactly after the skill name
+
+## Frontmatter Guidelines
+
+- `name`: The skill name
+- `description`: Primary triggering mechanism. Include both what the skill does and specific triggers/contexts. Include all "when to use" information here — the body is only loaded after triggering.
+
+Example description for a `docx` skill: "Comprehensive document creation, editing, and analysis with support for tracked changes, comments, formatting preservation, and text extraction. Use when the agent needs to work with professional documents (.docx files)."
+
+Keep frontmatter minimal. In Ghost, `metadata` and `always` are also supported when needed.
+
+## Body Guidelines
+
+- Always use imperative/infinitive form
+- Only include information that would be beneficial and non-obvious to the agent
+- Consider what procedural knowledge or domain-specific details would help another agent instance execute tasks effectively