@kensaurus/skills 0.0.0-stage → 2.1.0

package/skills-cursor/create-hook/SKILL.md

@@ -0,0 +1,238 @@
+---
+name: create-hook
+description: Create Cursor hooks. Use to create a hook, write hooks.json, add hook scripts, or automate behavior around agent events.
+disable-model-invocation: true
+---
+# Creating Cursor Hooks
+
+Create hooks when you want Cursor to run custom logic before or after agent events. Hooks are scripts or prompt-based checks that exchange JSON over stdin/stdout and can observe, block, modify, or follow up on behavior.
+
+When the user asks for a hook, don't stop at describing the format. Gather the missing requirements, then create or update the hook files directly.
+
+## Gather Requirements
+
+Before you write anything, determine:
+
+1. **Scope**: Should this be a project hook or a user hook?
+2. **Trigger**: Which event should run the hook?
+3. **Behavior**: Should it audit, deny/allow, rewrite input, inject context, or continue a workflow?
+4. **Implementation**: Should it be a command hook (script) or a prompt hook?
+5. **Filtering**: Does it need a matcher so it only runs for certain tools, commands, or subagent types?
+6. **Safety**: Should failures fail open or fail closed?
+
+Infer these from the conversation when possible. Only ask for the missing pieces.
+
+## Choose the Right Location
+
+- **Project hooks**: `.cursor/hooks.json` and `.cursor/hooks/*`
+- **User hooks**: `~/.cursor/hooks.json` and `~/.cursor/hooks/*`
+
+Path behavior matters:
+
+- **Project hooks** run from the project root, so use paths like `.cursor/hooks/my-hook.sh`
+- **User hooks** run from `~/.cursor/`, so use paths like `./hooks/my-hook.sh` or `hooks/my-hook.sh`
+
+Prefer **project hooks** when the behavior should be shared with the repository and checked into version control.
+
+## Choose the Hook Event
+
+Use the narrowest event that matches the user's goal.
+
+### Common Agent events
+
+- `sessionStart`, `sessionEnd`: set up or audit a session
+- `preToolUse`, `postToolUse`, `postToolUseFailure`: work across all tools
+- `subagentStart`, `subagentStop`: control or continue Task/subagent workflows
+- `beforeShellExecution`, `afterShellExecution`: gate or audit terminal commands
+- `beforeMCPExecution`, `afterMCPExecution`: gate or audit MCP tool calls
+- `beforeReadFile`, `afterFileEdit`: control file reads or post-process edits
+- `beforeSubmitPrompt`: validate prompts before they are sent
+- `preCompact`: observe context compaction
+- `stop`: handle agent completion
+- `afterAgentResponse`, `afterAgentThought`: track agent output or reasoning
+
+### Tab events
+
+- `beforeTabFileRead`: control file access for inline completions
+- `afterTabFileEdit`: post-process edits made by Tab
+
+### Quick event chooser
+
+- **Block or approve shell commands** -> `beforeShellExecution`
+- **Audit shell output** -> `afterShellExecution`
+- **Format files after edits** -> `afterFileEdit`
+- **Block or rewrite a specific tool call** -> `preToolUse`
+- **Add follow-up context after a tool succeeds** -> `postToolUse`
+- **Control whether subagents can run** -> `subagentStart`
+- **Chain subagent loops** -> `subagentStop`
+- **Check prompts for secrets or policy violations** -> `beforeSubmitPrompt`
+- **Protect MCP calls** -> `beforeMCPExecution`
+
+## Hooks File Format
+
+Create a `hooks.json` file with schema version 1:
+
+```json
+{
+  "version": 1,
+  "hooks": {
+    "afterFileEdit": [
+      {
+        "command": ".cursor/hooks/format.sh"
+      }
+    ]
+  }
+}
+```
+
+Each hook definition can include:
+
+- `command`: shell command or script path
+- `type`: `"command"` or `"prompt"` (defaults to `"command"`)
+- `timeout`: timeout in seconds
+- `matcher`: filter for when the hook runs
+- `failClosed`: block the action when the hook crashes, times out, or returns invalid JSON
+- `loop_limit`: mainly for `stop` and `subagentStop` follow-up loops
+
+## Matchers
+
+Use matchers to avoid running the hook on every event.
+
+- `preToolUse` / `postToolUse` / `postToolUseFailure`: match on tool type such as `Shell`, `Read`, `Write`, `Task`, or MCP tools in `MCP: ...` form
+- `subagentStart` / `subagentStop`: match on subagent type such as `generalPurpose`, `explore`, or `shell`
+- `beforeShellExecution` / `afterShellExecution`: match on the full shell command string
+- `beforeReadFile`: match on tool type such as `Read` or `TabRead`
+- `afterFileEdit`: match on tool type such as `Write` or `TabWrite`
+- `beforeSubmitPrompt`: matches the value `UserPromptSubmit`
+
+Important matcher warning:
+
+- Matchers use JavaScript-style regular expressions, not POSIX/grep syntax
+- Do not use POSIX classes like `[[:space:]]`; use JavaScript equivalents like `\s`
+- If the matcher is at all tricky, start by getting the hook working without one or with a very simple matcher, then tighten it after the hook is confirmed to load and fire
+
+If the user wants a hook for only one risky command family, prefer script-side filtering for the first working version and add a matcher afterward only if it is simple and clearly correct.
+
+## Command Hooks
+
+Command hooks are the default. They receive JSON on stdin and can return JSON on stdout.
+
+Before using a command hook, verify that every executable it depends on will actually run in the hook environment:
+
+- the script itself has a valid shebang and is executable
+- any helper binary it calls is already installed and on `$PATH`
+- if the script depends on tools like `jq`, `python3`, `node`, or repo-local CLIs, verify that explicitly before finishing
+
+Do not assume a binary exists just because it is common on your machine.
+
+### Minimal project-level example
+
+```json
+{
+  "version": 1,
+  "hooks": {
+    "beforeShellExecution": [
+      {
+        "command": ".cursor/hooks/approve-network.sh",
+        "matcher": "curl|wget|nc ",
+        "failClosed": true
+      }
+    ]
+  }
+}
+```
+
+```bash
+#!/bin/bash
+input=$(cat)
+command=$(echo "$input" | jq -r '.command // empty')
+
+if [[ "$command" =~ curl|wget|nc ]]; then
+  echo '{
+    "permission": "ask",
+    "user_message": "This command may make a network request. Please review it before continuing.",
+    "agent_message": "A hook flagged this shell command as a possible network call."
+  }'
+  exit 0
+fi
+
+echo '{ "permission": "allow" }'
+exit 0
+```
+
+Important behavior:
+
+- Exit code `0`: success
+- Exit code `2`: block the action, same as returning deny
+- Other non-zero exit codes: fail open by default unless `failClosed: true`
+
+Make hook scripts executable after creating them (`chmod +x`): a non-executable script errors, and by default that fails open, so the hook silently does nothing.
+
+## Prompt Hooks
+
+Prompt hooks are useful when the policy is easier to describe than to script.
+
+```json
+{
+  "version": 1,
+  "hooks": {
+    "beforeShellExecution": [
+      {
+        "type": "prompt",
+        "prompt": "Does this command look safe to execute? Only allow read-only operations. Here is the hook input: $ARGUMENTS",
+        "timeout": 10
+      }
+    ]
+  }
+}
+```
+
+Use prompt hooks for lightweight policy decisions. Prefer command hooks when the logic must be deterministic or when the user needs exact, auditable behavior.
+
+## Event Output Cheat Sheet
+
+Use the event's supported output fields only.
+
+- `preToolUse`: can return `permission`, `user_message`, `agent_message`, and `updated_input`
+- `postToolUse`: can return `additional_context`; for MCP tools it can also return `updated_mcp_tool_output`
+- `subagentStart`: can return `permission` and `user_message`
+- `subagentStop`: can return `followup_message`
+- `beforeShellExecution` / `beforeMCPExecution`: can return `permission`, `user_message`, and `agent_message`
+
+When the user wants to rewrite a tool call, prefer `preToolUse`. When they want to gate only shell commands, prefer `beforeShellExecution`.
+
+## Implementation Workflow
+
+1. Pick the correct location and event
+2. Create or update the correct `hooks.json` file
+3. Start with no matcher or the simplest safe matcher
+4. Create the script under the matching hooks directory
+5. Read stdin JSON and implement the required behavior
+6. Make the script executable
+7. Verify any helper executables the script uses are installed and on `$PATH`
+8. Trigger the relevant action to test the hook
+9. Verify behavior in Cursor's **Hooks** settings tab or the **Hooks** output channel
+
+If you are editing an existing hooks setup, preserve unrelated hooks and only change the minimum necessary entries.
+
+## Validation and Troubleshooting
+
+- Cursor watches `hooks.json` and reloads on save
+- If hooks still do not load, restart Cursor
+- Double-check relative paths:
+  - project hooks -> relative to the project root
+  - user hooks -> relative to `~/.cursor/`
+- If the hook does not appear to load at all, suspect matcher/config parsing first; remove the matcher and confirm the base hook works before tightening it
+- If the script runs external commands, verify each one is installed and reachable from the hook process with `command -v` or equivalent
+- If the hook should block on failure, set `failClosed: true`
+- If a command hook should intentionally block, returning exit code `2` is valid
+
+## Final Checklist
+
+- [ ] Used the correct hook location and path style
+- [ ] Chose the narrowest correct event
+- [ ] Added a matcher when appropriate
+- [ ] Returned only fields supported by that hook event
+- [ ] Made the script executable
+- [ ] Tested the hook by triggering the real event
+- [ ] Checked the Hooks tab or Hooks output channel if debugging was needed

package/skills-cursor/create-rule/SKILL.md

@@ -0,0 +1,185 @@
+---
+name: create-rule
+description: Create Cursor rules for persistent AI guidance. Use when user wants to create a rule, add coding standards, project conventions, file-specific patterns, or mentions ".cursor/rules", "AGENTS.md", "cursor rule", "coding standard", "convention", or "AI guidance".
+disable-model-invocation: true
+---
+# Creating Cursor Rules
+
+Create project rules in `.cursor/rules/` to provide persistent context for the AI agent.
+For one plain-Markdown file that always applies, `AGENTS.md` at the project root does the same job as an `alwaysApply` rule and needs no frontmatter.
+
+## Check existing first
+
+**Before creating a rule, check:**
+
+1. **Check for existing rules:**
+```bash
+ls -la .cursor/rules/*.mdc 2>/dev/null
+cat .cursor/rules/*.mdc 2>/dev/null | head -100
+```
+
+2. **Check for conflicting conventions:**
+```bash
+cat CONTRIBUTING.md .editorconfig .eslintrc* 2>/dev/null | head -50
+```
+
+3. **Check if similar rule exists:**
+- Don't duplicate existing rules
+- Consider extending existing rules instead
+
+**Why:** Rules should complement, not conflict with, existing project conventions.
+
+## Gather Requirements
+
+Before creating a rule, determine:
+
+1. **Purpose**: What should this rule enforce or teach?
+2. **Scope**: Should it always apply, or only for specific files?
+3. **File patterns**: If file-specific, which glob patterns?
+
+### Inferring from Context
+
+If you have previous conversation context, infer rules from what was discussed. You can create multiple rules if the conversation covers distinct topics or patterns. Don't ask redundant questions if the context already provides the answers.
+
+### Required Questions
+
+If the user hasn't specified scope, ask:
+- "Should this rule always apply, or only when working with specific files?"
+
+If they mentioned specific files and haven't provided concrete patterns, ask:
+- "Which file patterns should this rule apply to?" (e.g., `**/*.ts`, `backend/**/*.py`)
+
+Get the file patterns right: a wrong glob means the rule never loads, or loads for every file.
+
+Use the AskQuestion tool when available to gather this efficiently.
+
+---
+
+## Rule File Format
+
+Rules are `.mdc` files in `.cursor/rules/` with YAML frontmatter:
+
+```
+.cursor/rules/
+  typescript-standards.mdc
+  react-patterns.mdc
+  api-conventions.mdc
+```
+
+### File Structure
+
+```markdown
+---
+description: Brief description of what this rule does
+globs: **/*.ts  # File pattern for file-specific rules
+alwaysApply: false  # Set to true if rule should always apply
+---
+
+# Rule Title
+
+Your rule content here...
+```
+
+### Frontmatter Fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `description` | string | What the rule does (shown in rule picker) |
+| `globs` | string | File pattern - rule applies when matching files are open |
+| `alwaysApply` | boolean | If true, applies to every session |
+
+---
+
+## Rule Configurations
+
+### Always Apply
+
+For universal standards that should apply to every conversation:
+
+```yaml
+---
+description: Core coding standards for the project
+alwaysApply: true
+---
+```
+
+### Apply to Specific Files
+
+For rules that apply when working with certain file types:
+
+```yaml
+---
+description: TypeScript conventions for this project
+globs: **/*.ts
+alwaysApply: false
+---
+```
+
+---
+
+## Best Practices
+
+### Keep Rules Concise
+
+- **Under 50 lines**: Rules should be concise and to the point
+- **One concern per rule**: Split large rules into focused pieces
+- **Actionable**: Write like clear internal docs
+- **Normal volume, with the reason**: state each constraint once and say why. MUST/NEVER/CRITICAL over-trigger on current models; "try to" reads as permission to skip
+- **Concrete examples**: Ideally provide concrete examples of how to fix issues
+- **Always-on costs every turn**: an `alwaysApply` rule rides in every request inside the cached prefix. Keep those few, short, and byte-stable (no dates, counters, or generated timestamps); scope the rest with `globs`
+
+---
+
+## Example Rules
+
+### TypeScript Standards
+
+```markdown
+---
+description: TypeScript coding standards
+globs: **/*.ts
+alwaysApply: false
+---
+
+# Error Handling
+
+\`\`\`typescript
+// ❌ BAD
+try {
+  await fetchData();
+} catch (e) {}
+
+// ✅ GOOD
+try {
+  await fetchData();
+} catch (e) {
+  logger.error('Failed to fetch', { error: e });
+  throw new DataFetchError('Unable to retrieve data', { cause: e });
+}
+\`\`\`
+```
+
+### React Patterns
+
+```markdown
+---
+description: React component patterns
+globs: **/*.tsx
+alwaysApply: false
+---
+
+# React Patterns
+
+- Use functional components
+- Extract custom hooks for reusable logic
+- Colocate styles with components
+```
+
+---
+
+## Checklist
+
+- [ ] File is `.mdc` format in `.cursor/rules/`
+- [ ] Frontmatter configured correctly
+- [ ] Content under 50 lines (split larger rules by concern)
+- [ ] Includes concrete examples

package/skills-cursor/create-skill/SKILL.md

@@ -0,0 +1,269 @@
+---
+name: create-skill
+description: Guide users through creating effective Agent Skills for Cursor. Use when user wants to create, write, update, or debug a skill, or asks about SKILL.md format, skill structure, ~/.cursor/skills/, or skill best practices.
+disable-model-invocation: true
+---
+# Creating Skills in Cursor
+
+This skill guides you through creating effective Agent Skills for Cursor. Skills are markdown files that teach the agent how to perform specific tasks: reviewing PRs using team standards, generating commit messages in a preferred format, querying database schemas, or any specialized workflow.
+
+## Check existing first
+
+**Before creating a skill, check:**
+
+1. **Check for existing skills:**
+```bash
+ls -la ~/.cursor/skills/*/SKILL.md 2>/dev/null
+ls -la .cursor/skills/*/SKILL.md 2>/dev/null
+```
+
+2. **Check for similar functionality:**
+```bash
+grep -r "description:" ~/.cursor/skills/*/SKILL.md 2>/dev/null
+```
+
+3. **Consider extending vs creating:**
+- Could an existing skill be enhanced?
+- Would a rule be more appropriate than a skill?
+
+**Why:** Avoid skill duplication. Skills should have clear, distinct purposes.
+
+## Before You Begin: Gather Requirements
+
+Before creating a skill, gather essential information from the user about:
+
+1. **Purpose and scope**: What specific task or workflow should this skill help with?
+2. **Target location**: Should this be a personal skill (~/.cursor/skills/) or project skill (.cursor/skills/)?
+3. **Trigger scenarios**: When should the agent automatically apply this skill?
+4. **Key domain knowledge**: What specialized information does the agent need that it wouldn't already know?
+5. **Output format preferences**: Are there specific templates, formats, or styles required?
+6. **Existing patterns**: Are there existing examples or conventions to follow?
+
+### Inferring from Context
+
+If you have previous conversation context, infer the skill from what was discussed. You can create skills based on workflows, patterns, or domain knowledge that emerged in the conversation.
+
+### Gathering Additional Information
+
+If you need clarification, use the AskQuestion tool when available:
+
+```
+Example AskQuestion usage:
+- "Where should this skill be stored?" with options like ["Personal (~/.cursor/skills/)", "Project (.cursor/skills/)"]
+- "Should this skill include executable scripts?" with options like ["Yes", "No"]
+```
+
+If the AskQuestion tool is not available, ask these questions conversationally.
+
+---
+
+## Skill File Structure
+
+### Directory Layout
+
+Skills are stored as directories containing a `SKILL.md` file:
+
+```
+skill-name/
+├── SKILL.md              # Required - main instructions
+├── reference.md          # Optional - detailed documentation
+├── examples.md           # Optional - usage examples
+└── scripts/              # Optional - utility scripts
+    ├── validate.py
+    └── helper.sh
+```
+
+### Storage Locations
+
+| Type | Path | Scope |
+|------|------|-------|
+| Personal | ~/.cursor/skills/skill-name/ | Available across all your projects |
+| Project | .cursor/skills/skill-name/ | Shared with anyone using the repository |
+
+**IMPORTANT**: Never create skills in `~/.cursor/skills-cursor/`. This directory is reserved for Cursor's internal built-in skills and is managed automatically by the system.
+
+### SKILL.md Structure
+
+Every skill requires a `SKILL.md` file with YAML frontmatter and markdown body:
+
+```markdown
+---
+name: your-skill-name
+description: Brief description of what this skill does and when to use it
+---
+
+# Your Skill Name
+
+## Instructions
+Outcomes, constraints, and how to verify. Numbered steps only where order is load-bearing (destructive ops, auth, migrations).
+
+## Examples
+Concrete examples of using this skill.
+```
+
+### Required Metadata Fields
+
+| Field | Requirements | Purpose |
+|-------|--------------|---------|
+| `name` | Max 64 chars, lowercase letters/numbers/hyphens only | Unique identifier for the skill |
+| `description` | Max 320 chars in kenji (spec max 1024), non-empty | Helps agent decide when to apply the skill |
+
+### Optional fields
+
+Cursor ignores keys it does not list; Claude Code honors all of these. Any other key goes under `metadata`.
+
+| Field | Hosts | Use |
+|-------|-------|-----|
+| `disable-model-invocation: true` | Cursor, Claude Code | User-initiated rituals. Also keeps the description out of the always-on skill roster that every request pays for. |
+| `user-invocable: false` | Claude Code | Reference-only skill; hides the `/` entry. |
+| `effort` | Claude Code | `low` / `medium` / `high` / `xhigh` / `max`. Opus 5.5 defaults to `medium`; declare `high` for audit, plan, judge, security, and architecture skills, `low` for mechanical, read-only, or handoff skills. Effort is the thinking control — prose cannot raise or lower it. |
+| `context: fork` + `agent: <name>` | Claude Code | Run in a forked context so the output stays out of the main conversation; `agent: Explore` for read-only inventory. |
+| `model`, `allowed-tools` | Claude Code | Pin a model; restrict tools. |
+| `paths` | Cursor, Claude Code | Globs; the skill applies when matching files are in play. |
+
+---
+
+## Writing Effective Descriptions
+
+The description is **critical** for skill discovery. The agent uses it to decide when to apply your skill.
+
+### Description Best Practices
+
+1. **Write in third person** (the description is injected into the system prompt):
+   - ✅ Good: "Processes Excel files and generates reports"
+   - ❌ Avoid: "I can help you process Excel files"
+   - ❌ Avoid: "You can use this to process Excel files"
+
+2. **Be specific and include trigger terms**:
+   - ✅ Good: "Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction."
+   - ❌ Vague: "Helps with documents"
+
+3. **Include both WHAT and WHEN**:
+   - WHAT: What the skill does (specific capabilities)
+   - WHEN: When the agent should use it (trigger scenarios)
+
+### Description Examples
+
+```yaml
+# PDF Processing
+description: Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction.
+
+# Excel Analysis
+description: Analyze Excel spreadsheets, create pivot tables, generate charts. Use when analyzing Excel files, spreadsheets, tabular data, or .xlsx files.
+
+# Git Commit Helper
+description: Generate descriptive commit messages by analyzing git diffs. Use when the user asks for help writing commit messages or reviewing staged changes.
+
+# Code Review
+description: Review code for quality, security, and best practices following team standards. Use when reviewing pull requests, code changes, or when the user asks for a code review.
+```
+
+---
+
+## Core Authoring Principles
+
+### 1. Concise is Key
+
+The context window is shared with conversation history, other skills, and requests. Every token competes for space.
+
+**Default assumption**: The agent is already very smart. Only add context it doesn't already have.
+
+Challenge each piece of information:
+- "Does the agent really need this explanation?"
+- "Can I assume the agent knows this?"
+- "Does this paragraph justify its token cost?"
+
+**Good (concise)**:
+```markdown
+## Extract PDF text
+
+Use pdfplumber for text extraction:
+
+\`\`\`python
+import pdfplumber
+
+with pdfplumber.open("file.pdf") as pdf:
+    text = pdf.pages[0].extract_text()
+\`\`\`
+```
+
+**Bad (verbose)**:
+```markdown
+## Extract PDF text
+
+PDF (Portable Document Format) files are a common file format that contains
+text, images, and other content. To extract text from a PDF, you'll need to
+use a library. There are many libraries available for PDF processing, but we
+recommend pdfplumber because it's easy to use and handles most cases well...
+```
+
+### 2. Keep SKILL.md Under 500 Lines
+
+For optimal performance, the main SKILL.md file should be concise. Use progressive disclosure for detailed content.
+
+### 3. Progressive Disclosure
+
+Put essential information in SKILL.md; detailed reference material in separate files that the agent reads only when needed.
+
+```markdown
+# PDF Processing
+
+## Quick start
+[Essential instructions here]
+
+## Additional resources
+- For complete API details, see [reference.md](reference.md)
+- For usage examples, see [examples.md](examples.md)
+```
+
+**Keep references one level deep** - link directly from SKILL.md to reference files. Deeply nested references may result in partial reads.
+
+### 4. Prune with the verbosity levers
+
+Adapted from [mattpocock/skills](https://github.com/mattpocock/skills) (MIT):
+
+- **No-op test** — if a sentence doesn't change behavior versus the agent's
+  default ("be thorough"), delete the whole sentence. Do not swap in an
+  intensifier (*relentless*); on current models emphasis over-triggers — name
+  the concrete behavior and its reason instead.
+- **Positive phrasing** — state the target behavior instead of prohibiting the
+  bad one; keep prohibitions only as hard guardrails, paired with what to do
+  instead.
+- **Leading words** — collapse restated qualities into one compact concept the
+  model already knows ("fast, deterministic, low-overhead" → a *tight* loop).
+- **One trigger per branch** — in descriptions, synonyms of the same trigger are
+  duplication; keep only genuinely distinct branches.
+- **Checkable completion criteria** — end steps on a condition the agent can
+  verify, not a vibe; vague criteria invite premature completion.
+
+### 5. Set Appropriate Degrees of Freedom
+
+Match specificity to the task's fragility:
+
+| Freedom Level | When to Use | Example |
+|---------------|-------------|---------|
+| **High** (text instructions) | Multiple valid approaches, context-dependent | Code review guidelines |
+| **Medium** (pseudocode/templates) | Preferred pattern with acceptable variation | Report generation |
+| **Low** (specific scripts) | Fragile operations, consistency critical | Database migrations |
+
+### 6. Write for current models
+
+- **Effort, not prose, sets thinking.** Leave out "think step by step", "think hard", and "double-check your work"; set `effort:` and state the outcome to verify. Keep evidence rules ("tie every finding to a tool result") — they target fabricated progress, not thinking.
+- **Normal volume, with the reason.** MUST/NEVER/CRITICAL over-trigger; "try to" and "if possible" read as permission to skip. Say it once and say why.
+- **Describe success, not the grader.** State every requirement; leave out how the output will be scored or tested by a reader.
+- **Do not suppress updates.** The always-on verification rule asks for an intent line, load-bearing notes and a recap; never add "no preamble" or "hold findings". A skill that runs unattended says when the turn may end.
+- **Frontend skills name the defaults to avoid** (cream backgrounds, italic accent words, "01/02/03" labels, pill buttons, Inter/Roboto, purple gradients, three equal cards); "avoid a generic look" swaps one default for another.
+
+---
+
+## Skill creation workflow (summary)
+
+1. **Discovery** — purpose, location, triggers, constraints
+2. **Design** — name, description, sections, supporting files
+3. **Implement** — `SKILL.md` + `references/` + `scripts/` as needed
+4. **Verify** — in kenji run `npm run validate:skills`; description ≤320 chars, body <500 lines
+
+## Additional resources
+
+- Patterns, anti-patterns, full workflow, example, checklist → [references/authoring-guide.md](references/authoring-guide.md)
+