@blxzer/pactile 0.5.0

package/dist/templates/common/bundled-skills/pactile-meta/references/platform-files/skills-and-commands.md

@@ -0,0 +1,108 @@
+# Skills, Commands, Prompts, And Workflows
+
+Skills and commands are textual entry points for user interaction with Pactile. They tell the AI how to enter the Pactile flow when the user expresses a certain intent.
+
+## Conceptual Differences
+
+| Type | Trigger mode | Best for |
+| --- | --- | --- |
+| skill | AI auto-match or explicit user mention | Long-term capabilities, workflow rules, modification guides. |
+| command | Explicit user invocation | Clear operation entry points such as continue and finish-work. |
+| prompt | Explicit user invocation or platform selection | Similar to command, but in a platform prompt format. |
+| workflow | Explicit user selection or platform auto-match | Guides the main session when no sub-agent/hook exists. |
+
+> Pactile previously shipped per-platform skill/command directories for many AI tools. The project has converged on **Cursor-only**. New skills and commands ship into `.cursor/`; legacy adapter directories in upgraded projects are preserved but not extended.
+
+Pactile has two skill families:
+
+- Workflow skills: `brainstorm`, `before-dev`, `check`, `update-spec`, and `break-loop`.
+- Multi-file bundled skills include `pactile-meta`, `pactile-spec-bootstrap`, `pactile-skill-creator`, `smart-search-cli`, and `pactile-micro-grill`.
+
+Bundled skills are installed as directories and may include nested `agents/`, `examples/`, `references/`, or other lazy-loadable files. Do not describe bundled skills as a closed `pactile-*` list: `smart-search-cli` intentionally keeps its existing non-`pactile-` name.
+
+`smart-search-cli` is CLI-backed source retrieval. The Pactile package exposes the `smart-search` executable through its runtime wrapper; the skill documents how agents should use that CLI and cite retrieved sources.
+
+`pactile-spec-bootstrap` bootstraps project-specific `.pactile/spec/` guidance from the real repository.
+
+`pactile-skill-creator` is the authoring and review guide for Pactile-compatible skills. Use it when creating or improving project-local skills under `.cursor/skills/`, the shared `.agents/skills/` directory (industry skill-sharing, kept but not extended by new Pactile behavior), or upstream bundled skills. Keep `pactile-meta` focused on architecture and routing.
+
+`pactile-micro-grill` is the Pactile clarification adapter. It asks one high-value question at a time and escalates to Lite, Full, or Parent/Child task modes only when durable artifacts or broader risk require it.
+
+## Common Paths (Cursor)
+
+| Platform | Common entries |
+| --- | --- |
+| Cursor | `.cursor/skills/` (preferred); `.cursor/commands/` is legacy compatibility-only |
+
+In a user project, use the files actually generated by init as authoritative. On current Cursor, Pactile prefers Agent Skills for manual entrypoints such as `pactile-continue` and `pactile-finish-work`; legacy `.cursor/commands/` files may exist in older projects but should be treated as an explicit compatibility surface rather than the default current-platform command surface.
+
+## Skill Structure
+
+A common skill is a directory:
+
+```text
+pactile-meta/
+├── SKILL.md
+└── references/
+pactile-spec-bootstrap/
+├── SKILL.md
+└── references/
+pactile-skill-creator/
+├── SKILL.md
+└── references/
+smart-search-cli/
+├── SKILL.md
+├── agents/
+├── examples/
+└── references/
+pactile-micro-grill/
+└── SKILL.md
+```
+
+`SKILL.md` should tell the AI:
+
+- When to use this skill.
+- Which reference to read first for the selected task.
+- What not to do.
+
+References hold longer explanations so the entry file does not contain everything.
+
+## Command/Prompt/Workflow Structure
+
+Commands, prompts, and workflows are usually single files. Their content should include:
+
+- When to use it.
+- Which `.pactile/` files to read.
+- Which scripts to run.
+- How to report after completion.
+
+They should not store task state; task state belongs in `.pactile/tasks/` and `.pactile/.runtime/`.
+
+Task selection uses `selected_task`, not legacy current/active task commands. The current command chain is:
+
+- `task.py dashboard` for routing without selecting a task.
+- `task.py select <task>` to select a task for the live session without changing `task.status`.
+- `task.py selected [--source]` to inspect the live-session selection.
+- `task.py start-execution <task> --check` and then `--approved` for the execution boundary.
+- `task.py exit` to clear the live-session selection without changing `task.status`.
+- `task.py archive <task>` for guarded completion.
+
+Do not reintroduce `task.py start`, `task.py current`, or `task.py finish` into platform commands or docs.
+
+## Local Change Scenarios
+
+| User need | Edit location |
+| --- | --- |
+| Change AI auto-trigger rules | The corresponding skill's frontmatter description. |
+| Change user command behavior | The corresponding command/prompt/workflow file. |
+| Add a project-local skill | `.cursor/skills/` (or `.agents/skills/` only when explicitly sharing with another non-Pactile tool that reads that path). |
+| Change finish/continue entry points | On current Cursor, prefer `.cursor/skills/pactile-continue` and `.cursor/skills/pactile-finish-work` over legacy `.cursor/commands/`. |
+
+## Modification Principles
+
+1. **Keep entry files short; references carry long content**. This matters especially for multi-file skills like `pactile-meta` and `pactile-skill-creator`.
+2. **Make trigger descriptions specific**. A description that is too broad can mis-trigger; one that is too narrow may not trigger.
+3. **Keep behavior descriptions consistent with the shared `.pactile/` runtime**. Format may differ per file type, but semantics should match the shared workflow.
+4. **Put project-specific capabilities in local skills**. Do not put team-private flows into public `pactile-meta`.
+
+If the user only wants local AI to know one more project rule, usually create a project-local skill under `.cursor/skills/` or update `.pactile/spec/` instead of changing a Pactile built-in workflow skill.

package/dist/templates/common/bundled-skills/pactile-micro-grill/SKILL.md

@@ -0,0 +1,68 @@
+---
+name: pactile-micro-grill
+description: "Clarifies small underspecified Pactile requests with one high-value question at a time before direct execution. Use when a request is likely small, missing details would materially change the result, and creating a Pactile task would be premature."
+---
+
+# Pactile Micro-Grill
+
+## Goal
+
+Clarify a small request just enough to execute it directly without creating Pactile task artifacts by default.
+
+## Hard Constraints
+
+- Always ask exactly one high-value question at a time.
+- Always inspect local files first when the missing answer is discoverable from the project.
+- Always include a recommended answer when enough evidence exists.
+- Always use Simplified Chinese for user-facing questions.
+- Never create Pactile task artifacts by default.
+- Never keep grilling after the request is clear enough to execute.
+- Never repeat already answered questions after escalation.
+
+## Thinking Principles
+
+These two principles shape *which* question is worth asking and *what* to recommend — apply them inside the one-question-per-message contract above.
+
+### First Principles
+
+Pick the question whose answer most changes the result by tracing the request back to its root user value, not to how similar requests are usually handled.
+
+- Separate the **root need** from **inherited shape** ("I want X like Y") — grill the root need first.
+- Prefer the question that, once answered, collapses the most other candidate questions.
+
+### Occam's Razor
+
+Your recommended answer defaults to the **minimal sufficient** option that still satisfies the likely acceptance bar. Complexity must be justified by evidence you can cite, not added speculatively. If two clarifications are equally valid, recommend the simpler one.
+
+## Workflow
+
+1. Confirm internally that the request is small, underspecified, and not already covered by a selected Pactile task.
+2. Inspect relevant local context first if it can answer the missing detail.
+3. Ask one question whose answer would most change the result.
+4. Include a recommended answer with the concrete tradeoff.
+5. After the user answers, summarize the clarified requirement in one or two Chinese sentences.
+6. Execute directly once the requirement is clear enough.
+
+## Frontier support (optional)
+
+Default is one question at a time (small-request clarification). When several questions can be asked together and their prerequisites are all decided (**≤3 questions**), list them in one round (numbered + recommended answers) and wait for a batch reply. Beyond that, keep one question at a time.
+
+Facts the environment can self-check do not consume question slots: self-check first (Hard Constraints: always inspect local files first); while a fact check is pending it only blocks the questions that depend on it — ask the rest of the frontier without blocking.
+
+## Escalation
+
+Escalate once when the clarified work no longer fits Micro-Grill:
+
+- Use Lite Task when there is one independently verifiable deliverable that needs persistence, review, or continuation.
+- Use Full Task when one deliverable has broad impact, platform-adapter changes, external research dependency, or durable design risk.
+- Use Parent/Child when there are multiple independently verifiable deliverables, staged execution, parallel execution, or Parent-controlled integration needs.
+
+When escalating, hand the clarified answers into `pactile-brainstorm` and update Pactile artifacts there.
+
+## When NOT to Use
+
+- Do not use for multi-deliverable work.
+- Do not use for cross-platform workflow changes.
+- Do not use for risky refactors, migrations, prompt deployments, or durable architecture decisions.
+- Do not use when the request is already clear enough to execute.
+- Do not use when there is already a selected Pactile task for the work.

package/dist/templates/common/bundled-skills/pactile-skill-creator/SKILL.md

@@ -0,0 +1,47 @@
+---
+name: pactile-skill-creator
+description: "Create or improve Pactile-compatible agent skills. Use when the user asks to author a project-local skill, shared .agents skill, platform-specific skill, or upstream Pactile bundled skill."
+---
+
+# Pactile Skill Creator
+
+Create high-quality skills for Pactile-managed projects and Pactile bundled templates. This unified guide covers general authoring method plus Pactile packaging constraints.
+
+This skill is the authoring and review guide for skill files. It is not the local Pactile architecture map. Use `pactile-meta` first when the user needs to understand or customize `.pactile/`, hooks, settings, commands, prompts, workflows, agents, or platform directory layout.
+
+## Hard Constraints
+
+- Always inspect existing skill directories and platform conventions before creating or changing a skill.
+- Always keep `SKILL.md` under 500 lines, in English, and focused on trigger, constraints, workflow, references, and boundaries.
+- Always use lowercase letters, numbers, and hyphens in the frontmatter `name`.
+- Always write a trigger-rich frontmatter `description` that states what the skill does (WHAT) and when it should trigger (WHEN).
+- Always place safety, sequencing, and reliability rules in a `## Hard Constraints` section before `## Workflow`.
+- Always write Hard Constraints (and any other rule list) as imperative one-liners ("Always X. Never Y."). Never bury rules in prose paragraphs.
+- Always move long guidance, examples, prompts, and reference material into directly linked files.
+- Always make helper scripts deterministic, runnable from the skill directory, and explicit about inputs and outputs.
+- Never repeat the same rule in two sections — Hard Constraints is the single source of truth.
+- Never duplicate `pactile-meta` architecture guidance or project-private conventions inside a public Pactile skill.
+- Never edit Cursor's built-in `create-skill`; create or update Pactile-compatible skill files instead.
+
+## Workflow
+
+1. Classify the target skill location and read `references/pactile-skill-locations.md`.
+2. Gather requirements (six elements): purpose and scope, trigger scenarios, target location, domain constraints (tools / APIs / reliability), output style, and existing patterns. Infer from conversation context when available; ask the user when discrete choices are ambiguous. Capture tool budget and overlap with existing skills.
+3. Design, then draft: choose a specific skill name, write a trigger-rich description, decide script / no-script, and define success and stop criteria. Draft or revise `SKILL.md` using `references/authoring-rules.md` and `references/general-authoring.md`.
+4. Add `references/`, `examples/`, `prompts/`, or `scripts/` only when they reduce entry-file size or make execution more deterministic.
+5. Verify the result with `references/review-checklist.md`.
+6. Report changed files, validation performed, and any boundaries or follow-up work.
+
+## References
+
+- `references/pactile-skill-locations.md`: Choose project-local, shared, platform-specific, or upstream bundled skill locations.
+- `references/authoring-rules.md`: Frontmatter, trigger descriptions, hard-constraint form, progressive disclosure, writing-for-agents techniques, deterministic scripts, and anti-patterns.
+- `references/general-authoring.md`: General authoring method — principles, directory layout, patterns, utility scripts, and the minimal template.
+- `references/review-checklist.md`: Final quality checklist before handing off a skill change.
+
+## When NOT To Use
+
+- Do not use for general Pactile architecture discovery; use `pactile-meta`.
+- Do not use for project coding conventions that belong in `.pactile/spec/`.
+- Do not use for one-off commands or prompts unless the user wants a durable auto-triggered capability.
+- Do not use for non-Pactile global skill installation or platform configuration unless the user explicitly asks for that scope.

package/dist/templates/common/bundled-skills/pactile-skill-creator/references/authoring-rules.md

@@ -0,0 +1,171 @@
+# Skill Authoring Rules
+
+Use these rules when creating or reviewing a Pactile-compatible skill.
+
+Imperative constraints (length, English, `name` charset, WHAT+WHEN description, Hard Constraints placement and form, no duplicated rules, no `pactile-meta` duplication) live in `SKILL.md` Hard Constraints. This file shows how to apply them.
+
+## Required Shape
+
+Every active skill directory needs a `SKILL.md` with YAML frontmatter:
+
+```markdown
+---
+name: skill-name
+description: Specific capability and trigger scenarios.
+---
+```
+
+Keep the body focused on trigger, constraints, workflow, references, and boundaries. Long guidance belongs in directly linked files.
+
+## Description Quality
+
+The description is the trigger surface. Platforms inject it into discovery prompts, so write it in third person and include concrete task nouns plus user-intent phrases.
+
+1. **Write in third person**
+   - Good: "Processes Excel files and generates reports"
+   - Avoid: "I can help you process Excel files"
+2. **Be specific and include trigger terms**
+   - Good: "Fetch and verify one specific news event with minimal tool calls. Use when user asks whether a specific claim is true."
+   - Vague: "Helps with news."
+3. **Include both WHAT and WHEN**
+   - WHAT: what the skill does (specific capabilities)
+   - WHEN: when the agent should use it (trigger scenarios)
+
+Pactile example:
+
+```yaml
+description: "Create or improve Pactile-compatible agent skills. Use when the user asks to author a project-local skill, shared .agents skill, platform-specific skill, or upstream Pactile bundled skill."
+```
+
+Avoid:
+
+```yaml
+description: "Helps with skills."
+```
+
+Checklist:
+
+- Names the capability.
+- Names common trigger situations.
+- Avoids first person.
+- Avoids broad utility wording such as "helper", "tools", or "useful".
+- Does not claim support for platforms or files the skill does not cover.
+
+## Hard Constraints Form
+
+Put `## Hard Constraints` near the top, before `## Workflow`, when the skill has safety, sequencing, scope, or reliability rules.
+
+Write constraints as imperative one-liners:
+
+- Always inspect local files before editing.
+- Never modify global configuration without explicit user approval.
+- Always run the validator before final output.
+
+Do not bury constraints in paragraphs. Do not restate the same rule elsewhere; Hard Constraints is the only rule list.
+
+## Progressive Disclosure
+
+`SKILL.md` should route, not carry every detail.
+
+Good candidates for references:
+
+- Detailed authoring rules.
+- Domain background.
+- Long examples.
+- Output templates.
+- Platform-specific notes.
+- Review checklists.
+
+Keep references one level deep and link them directly from `SKILL.md`. Avoid reference chains where one reference requires reading another reference before it is useful.
+
+## Writing for agents (four techniques)
+
+Write instructions for how agents consume text: tokens in, behavior out. Apply these techniques to `SKILL.md`, descriptions, and references.
+
+1. **Leading words** — Open each instruction with the load-bearing verb or decision; agents anchor behavior on the first tokens of a line or sentence. Criterion: the first two words of every instruction state the action, not the context. Bad: "After checking the environment, update the file." Good: "Inspect local files first, then edit."
+
+2. **No-op test** — Test redundancy by deleting the whole sentence, not a word. Criterion: if the skill still holds with the sentence removed, cut it; word-level trimming hides leftover redundancy. Bad: deleting "local" from "inspect local files" leaves the same ambiguity.
+
+3. **Negation anti-pattern** — Prefer positive wording over stacked "do not" instructions. Criterion: each "do not"/"never" line should be rewritable as a "do" statement or merged into an existing constraint. Bad: "Do not edit files you have not read." Good: "Read a file before editing it."
+
+4. **Context pointer wording** — Phrase references with their trigger branch so the agent knows when to load them. Criterion: every pointer names the condition or decision that should open it. Vague: "See authoring rules." Actionable: "Load `references/authoring-rules.md` when reviewing skill shape or descriptions."
+
+## Deterministic Scripts
+
+Add scripts only when they make the skill more reliable than generated ad hoc code.
+
+Script rules:
+
+- Put scripts under the owning skill directory, usually `scripts/`.
+- Expose only parameters the agent must supply.
+- Let the script decide internal paths, timestamps, defaults, and output filenames when possible.
+- Return structured JSON to stdout when the script mutates files or produces machine-readable status.
+- State whether the agent should execute the script or read it as reference.
+- Avoid shell variables or cross-step state that would not survive separate tool calls.
+
+## Common Anti-Patterns
+
+### Vague description or name
+
+Vague frontmatter descriptions trigger on unrelated work.
+
+- Good names: `processing-pdfs`, `render-mermaid`
+- Avoid: `helper`, `utils`, `tools`
+
+### Mixing unrelated workflows
+
+One skill should not address multiple unrelated concerns. Split into separate skills.
+
+### Pasting long prompts or full scripts into SKILL.md
+
+Link references instead of inlining long material.
+
+### Repeated rules
+
+Do not restate the same rule in several sections with slightly different wording.
+
+### Missing stop conditions
+
+Multiple broad search loops without explicit exit criteria.
+
+### Cross-step variable sharing
+
+Each tool call is independent and stateless. Shell variables set in one call do not exist in the next.
+
+```markdown
+# Bad — variable $TS differs between Write and Bash calls
+Write content to /tmp/data-$TS.txt     # tool call 1: timestamp A
+Bash: cmd --input /tmp/data-$TS.txt    # tool call 2: timestamp B → file not found
+
+# Good — use a fixed path; let the script handle dynamic naming internally
+Write content to /var/skill-name/input.txt
+Bash: cmd --input /var/skill-name/input.txt
+```
+
+### Exposing internal decisions as parameters
+
+If a value can be determined by the script itself, do not expose it as a parameter.
+
+```markdown
+# Bad — unnecessary parameters the agent must coordinate
+cmd --input file.txt --output out.png --format png --theme default
+
+# Good — only the essential input; script decides the rest
+cmd --input file.txt
+```
+
+### Too many options
+
+```markdown
+# Bad
+"You can use pypdf, or pdfplumber, or PyMuPDF, or..."
+
+# Good — provide a default with an escape hatch
+"Use pdfplumber for text extraction.
+For scanned PDFs requiring OCR, use pdf2image with pytesseract instead."
+```
+
+### Broken or private references
+
+- References to files, scripts, or examples that do not exist.
+- Project-private conventions added to public Pactile bundled skills.

package/dist/templates/common/bundled-skills/pactile-skill-creator/references/general-authoring.md

@@ -0,0 +1,189 @@
+# General Skill Authoring
+
+Method and patterns for writing reusable agent skills. Imperative rules live in `SKILL.md` Hard Constraints; this file explains how to apply them. For Pactile location choice, read `pactile-skill-locations.md`. For description wording and anti-patterns, read `authoring-rules.md`.
+
+## Gather Requirements
+
+Collect these six elements before writing files:
+
+1. **Purpose and scope**: What specific workflow should this skill solve?
+2. **Trigger scenarios**: When should the agent automatically use it?
+3. **Target location**: Project skill, shared skill, bundled template, or personal skill?
+4. **Domain constraints**: Required tools, APIs, reliability constraints.
+5. **Output style**: Report template, checklist, strict schema, etc.
+6. **Existing patterns**: Are there existing skills or conventions to follow?
+
+### Inferring from Context
+
+If previous conversation already surfaced workflows, patterns, or domain knowledge, infer the skill from that context.
+
+Ask the user when requirements are ambiguous and discrete choices are needed.
+
+## Directory Layout
+
+```
+skill-name/
+├── SKILL.md            # required
+├── scripts/            # optional utility scripts
+├── bin/                # optional compiled binaries
+├── references/         # optional detailed docs (preferred over a single reference.md)
+├── examples/           # optional samples
+└── prompts/            # optional long prompts
+```
+
+Keep the entry file short. Put long guidance one level deep under `references/` and link it from `SKILL.md`.
+
+Generic storage scopes (`~/.agents/skills/` vs project `.agents/skills/`) are not enough for Pactile work. Use `pactile-skill-locations.md` to pick the target directory.
+
+## 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 does not 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?
+
+### 2. Progressive Disclosure
+
+Put essential information in `SKILL.md`; detailed reference material in separate files that the agent reads only when needed.
+
+Keep references one level deep — link directly from `SKILL.md`. Nested reference chains may result in partial reads.
+
+### 3. One File, One Concern
+
+Each skill should address a single workflow. If a skill tries to do too many things, split it.
+
+### 4. Maximize Determinism
+
+Skills run through multiple independent tool calls. Each call is stateless — no shared session or persistent variables between calls.
+
+Eliminate ambiguity at every layer — description, workflow, script parameters, and output format.
+
+- Internalize decisions: if a value can be decided inside a script (output path, temp filename, timestamp), do not expose it as a parameter.
+- Use fixed literal paths in workflows. The agent copies commands verbatim. Never rely on shell variables staying consistent across separate tool calls.
+- Minimize script parameters. Only require what the agent must provide.
+- Scripts return structured JSON to stdout so the agent can parse the result deterministically.
+- Specify an exact tool-call sequence, for example: "Exactly 3 steps: write file → run command → deliver output."
+- Add stop conditions. Prevent open-ended tool loops for expensive operations.
+
+### 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 |
+
+## Recommended SKILL.md Sections
+
+1. Goal
+2. Hard Constraints (imperative one-liners; placed before Workflow)
+3. Workflow
+4. Output Template
+5. When NOT to use this skill
+
+## Common Patterns
+
+### Workflow Pattern
+
+Break operations into explicit steps with a clear tool-call sequence:
+
+```markdown
+## Workflow
+
+1. Gather input data
+2. Process: `<exact command the agent should run>`
+3. Parse output, proceed to the next step
+4. Stop when the condition is met
+```
+
+### Template Pattern
+
+Provide output format templates:
+
+````markdown
+## Output Template
+
+```markdown
+# [Title]
+
+## Summary
+[One-paragraph overview]
+
+## Findings
+- Finding 1 with supporting data
+- Finding 2 with supporting data
+```
+````
+
+### Conditional Workflow Pattern
+
+Guide through decision points:
+
+```markdown
+## Workflow
+
+1. Determine the type:
+   **Creating new?** → Follow "Creation workflow" below
+   **Editing existing?** → Follow "Editing workflow" below
+```
+
+### Feedback Loop Pattern
+
+For quality-critical tasks, implement validation:
+
+```markdown
+1. Make edits
+2. Validate: `python scripts/validate.py output/`
+3. If validation fails → fix and re-validate
+4. Only proceed when validation passes
+```
+
+## Utility Scripts
+
+Pre-made scripts are more reliable than generated code, save tokens, and keep behavior consistent.
+
+Script design:
+
+- Only expose parameters the agent must supply (input data, mode selection).
+- Let the script handle internal decisions (output path, temp files, format defaults).
+- Return results as structured JSON to stdout.
+- State whether the agent should **execute** the script or **read** it as reference.
+
+## Minimal Template
+
+```markdown
+---
+name: skill-name
+description: Specific capability and trigger scenarios.
+---
+
+# Skill Name
+
+## Goal
+One clear objective.
+
+## Hard Constraints
+- Always X. Never Y.
+- Always validate the input before step 2.
+- Never call the API more than 5 times per run.
+
+## Workflow
+1. Step one
+2. Step two
+3. Stop when condition met
+
+## Output Template
+Required output structure.
+
+## When NOT to use this skill
+- Boundary cases.
+```

package/dist/templates/common/bundled-skills/pactile-skill-creator/references/pactile-skill-locations.md

@@ -0,0 +1,52 @@
+# Pactile Skill Locations
+
+Choose the target directory before writing content. Local files are authoritative when they already exist.
+
+## Location Decision Table
+
+| User goal | Default location | Notes |
+| --- | --- | --- |
+| Add a skill for one Pactile project on Cursor | `.cursor/skills/<skill-name>/` | Default target — Pactile is Cursor-only. |
+| Add a skill shared across tools that read the agentskills.io convention | `.agents/skills/<skill-name>/` | Use only when explicitly sharing with a non-Pactile tool that reads the shared agentskills layer. New Pactile behavior stays in `.cursor/skills/`. |
+| Change an existing local Pactile skill | The existing skill directory in the user's project | Preserve local customizations and read the current `SKILL.md` first. |
+| Add a public Pactile bundled skill | `packages/cli/src/templates/common/bundled-skills/<skill-name>/` | Only when working in the Pactile source repository. Update tests that assert bundled skill installation and template tracking. |
+| Add a personal cross-project skill | User's configured global skills directory | Requires explicit user approval because it changes global behavior outside the project. |
+
+## Relationship To `pactile-meta`
+
+Use `pactile-meta` to understand where local Pactile files live and which platform entry point should be changed.
+
+Use `pactile-skill-creator` after the task is clearly about authoring or reviewing the content of a skill:
+
+- frontmatter quality
+- trigger descriptions
+- hard constraints
+- workflow shape
+- references
+- examples
+- deterministic scripts
+- final quality review
+
+Do not copy the full skill-writing guide into `pactile-meta`. `pactile-meta` should route to this skill for detailed authoring guidance.
+
+## Relationship To Cursor `create-skill`
+
+Cursor may provide its own built-in `create-skill` helper. Treat it as a platform-owned helper, not as Pactile source material to edit.
+
+For Pactile work:
+
+- Use `pactile-skill-creator` for Pactile-compatible content and multi-platform boundaries.
+- Keep the skill name `pactile-skill-creator` to avoid colliding with Cursor's built-in skill.
+- If a user explicitly asks for Cursor-only behavior, write to the local `.cursor/skills/` directory and follow the platform's current file format.
+
+## Upstream Bundled Skill Notes
+
+When adding or modifying a bundled skill in the Pactile source repository:
+
+- Do not edit `dist/` directly.
+- Keep the bundled skill public and project-agnostic.
+- Put the skill under `packages/cli/src/templates/common/bundled-skills/`.
+- Include a short `SKILL.md` and lazy-loadable references when the guidance is long.
+- Search for hard-coded bundled skill lists or tests before editing.
+- Update `pactile-meta` only to route users to the new skill where appropriate.
+- Validate template collection, platform installation, and hash tracking with focused tests.