@asermax/tachikoma 2.0.0

package/skills/skill-authoring/SKILL.md

@@ -0,0 +1,168 @@
+---
+name: skill-authoring
+description: |
+  Activates when the user wants to create, define, set up, build, or scaffold a new skill; encode expertise or save a process for reuse; define automation for the assistant. Also triggers on requests to author a skill, write a skill, help me make a skill, guide me through skill authoring, how to create a skill, make a skill, build a skill, new skill.
+---
+
+# Skill Authoring Guide
+
+This guide provides everything you need to create well-structured skills. Read this document when asked to create, define, or set up a new skill for the assistant.
+
+## Directory Conventions
+
+User skills live in the `skills/` directory of the workspace (`{workspace}/skills`). Each skill is a subdirectory containing a `SKILL.md` file:
+
+```
+skills/
+└── my-skill/
+    ├── SKILL.md       # Required: metadata + content
+    ├── agents/        # Optional: delegable agent definitions
+    │   └── helper.md
+    ├── references/    # Optional: detailed docs read on demand
+    │   └── api.md
+    └── workflows/     # Optional: multi-step workflow definitions
+```
+
+**Naming**: lowercase with hyphens (e.g. `code-review`, `git-workflow`). Names must be 64 characters or fewer, use only `a-z`, `0-9`, and hyphens, and must not start/end with a hyphen or contain consecutive hyphens.
+
+A directory containing a `SKILL.md` is a skill root — discovery does not recurse further inside it, so nested content (references, agents, scripts) belongs to that skill.
+
+## SKILL.md Format
+
+A `SKILL.md` file follows the Agent Skills standard: YAML frontmatter followed by a markdown body.
+
+```yaml
+---
+name: my-skill
+description: "A clear description of what this skill does and when to use it"
+---
+
+# Skill Title
+
+The skill's content goes here. Explain what the skill does,
+when to use it, and how to use it.
+```
+
+### Frontmatter Fields
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `name` | No | Skill identifier. Defaults to the directory name. Same naming rules as directories. |
+| `description` | Yes | What the skill does and when it applies (max 1024 characters). Drives skill selection. |
+
+### Body Content
+
+The body is loaded into context when the skill is used. Explain what the skill does, when to use it, how to use it, and any constraints or tips.
+
+## How Skills Are Discovered
+
+Skills use **progressive disclosure**: the name and description of every skill are always visible to the agent, while the body is only loaded when the skill is relevant. There is no separate classification pass — the description alone determines whether the skill gets picked up.
+
+### Tips for Effective Descriptions
+
+**Be specific about triggers** — mention concrete actions and requests:
+
+```yaml
+# Good: specific triggers
+description: "Activates when the user wants to create, define, or scaffold a new skill"
+
+# Bad: too vague
+description: "A skill for skills"
+```
+
+**Include synonyms** — cover different phrasings of the same intent.
+
+**Avoid false positives** — say what the skill does *not* cover when a term is ambiguous.
+
+## Available Capabilities
+
+### Agents (`agents/`)
+
+**When to use**: delegate focused sub-tasks to an isolated agent with its own system prompt and tool set.
+
+Agents are markdown files under the skill's `agents/` directory. Each file has YAML frontmatter and a body that becomes the agent's system prompt:
+
+```yaml
+---
+description: "Finds and summarizes relevant sources"
+tools:
+  - read
+  - grep
+---
+
+You are a research scout. Given a topic, locate relevant files
+and produce a concise summary of what you found.
+```
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `description` | Yes | What the agent does — shown to the main agent when choosing whom to delegate to. |
+| `name` | No | Agent identifier. Defaults to the file name without `.md`. |
+| `tools` | No | Tools available to the agent: a YAML list or a comma-separated string. Defaults to read-only tools (`read`, `grep`, `find`, `ls`). |
+
+Agents are exposed through the `delegate_to_agent` tool, namespaced as `<skill>/<agent>` to avoid collisions. Discovery runs per agent session, so a newly added agent becomes available on the next session without a restart.
+
+### Reference Files (`references/`)
+
+**When to use**: detailed documentation that would clutter the main body.
+
+Reference files are regular files the agent reads with file-system tools when directed by the SKILL.md body. They are **not automatically injected** — use them for detailed API docs, extended examples, or large templates.
+
+**Format**: any file type. Reference from SKILL.md like: "See `references/api.md` for detailed options."
+
+### Workflows (`workflows/`)
+
+**When to use**: the skill encodes a multi-step process that benefits from tracked, resumable execution.
+
+Workflows are directory-based step definitions executed through dedicated lifecycle tools. See the `workflow-authoring` skill for the full format and conventions.
+
+### Scripts and Other Content
+
+Skills can bundle executable scripts or data files anywhere in the skill directory; the agent runs them with its shell tool when the SKILL.md body says to. Organize additional content as needed (`data/`, `templates/`, `examples/`). Keep generated runtime state out of the skill directory — a skill should stay a read-only package.
+
+## Writing Best Practices
+
+### Explain the Why
+
+Don't just say what to do — explain the reasoning behind choices so the agent can make good decisions when the situation deviates from the script.
+
+### Keep It Lean
+
+Only include what's necessary. Avoid redundant explanations, overly verbose instructions, and information already covered by the system prompt or other skills.
+
+### Progressive Disclosure
+
+Put essential information in the main body. Move detailed reference material to `references/` files. This keeps loaded context focused while making details available on demand.
+
+## Example
+
+```yaml
+---
+name: git-commit
+description: |
+  Activates when the user wants to create, update, or manage git commits.
+  Triggers on requests to commit changes, create a commit, make a commit.
+---
+
+# Git Commit Workflow
+
+Guides the user through creating well-structured git commits.
+
+## When to Use
+
+- User asks to commit changes
+- User wants a commit with a specific message
+- User needs help with commit message format
+
+## Workflow
+
+1. **Stage changes**: review what files have been modified
+2. **Draft message**: propose a conventional commit message
+3. **Create commit**: execute the git commit
+
+## Tips
+
+- Use conventional commit format (type(scope): message)
+- Group related changes into logical commits
+- Keep commits focused and atomic
+```

package/skills/workflow-authoring/SKILL.md

@@ -0,0 +1,251 @@
+---
+name: workflow-authoring
+description: |
+  Activates when the user wants to create, define, set up, build, or scaffold a new workflow; encode a multi-step process or save a procedure for reuse; define automation for workflows. Also triggers on requests to author a workflow, write a workflow, help me make a workflow, guide me through workflow authoring, how to create a workflow, make a workflow, build a workflow, new workflow.
+---
+
+# Workflow Authoring Guide
+
+This guide provides everything you need to create well-structured workflows. Read this document when asked to create, define, or set up a new workflow for a skill.
+
+## What Workflows Are
+
+Workflows are ordered multi-step processes defined within skills. They provide:
+
+- **Structured execution**: steps run in sequence with clear boundaries
+- **State persistence**: progress is saved between steps, enabling resumption after interruptions
+- **Recovery**: lost context can be recovered by querying active workflows and resuming
+
+Workflows are **optional** — skills may have zero, one, or many workflows depending on their purpose.
+
+## Directory Conventions
+
+Workflows live in a `workflows/` subdirectory within a skill:
+
+```
+skills/
+└── my-skill/
+    ├── SKILL.md              # Mentions available workflows
+    └── workflows/
+        └── my-workflow/
+            ├── 01-first-step/
+            │   ├── instructions.md
+            │   ├── references/
+            │   └── scripts/
+            ├── 02-next-step/
+            │   └── instructions.md
+            └── 03-final-step/
+                └── instructions.md
+```
+
+**Naming**:
+
+- Workflow directories: lowercase with hyphens (e.g. `feature-planning`, `code-refactor`)
+- Step directories: two-digit prefix for ordering (e.g. `01-analyze`, `02-design`, `03-implement`)
+
+Steps execute in **lexicographic order of their directory names** — the numeric prefix is what orders them. Gaps are allowed (`01-*`, `05-*`, `10-*`) to leave room for future steps.
+
+## SKILL.md Integration Pattern
+
+Critical: workflows are discovered by reading the skill's SKILL.md body, not by automatic detection. You **must** document workflows in the SKILL.md for the agent to know they exist:
+
+```markdown
+## Available Workflows
+
+### feature-planning
+Use when planning a new feature. Steps through requirements analysis,
+design considerations, and implementation planning.
+```
+
+For each workflow, explain when to use it, what it does, and the expected outcome.
+
+## Step Format
+
+Each step directory contains:
+
+- **instructions.md** (required): the step's content with YAML frontmatter
+- **references/** (optional): detailed documentation read on demand
+- **scripts/** (optional): executable scripts for the step
+
+A step directory without an `instructions.md`, or whose frontmatter is missing a valid `title`, is skipped at load time with a warning — the rest of the workflow still loads.
+
+### instructions.md
+
+```yaml
+---
+title: "Analyze Requirements"
+---
+
+# Step Instructions
+
+The step's guidance goes here. Explain what the step does,
+what to produce, and how to validate completion.
+```
+
+### Frontmatter Fields
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `title` | Yes | Human-readable step title (non-empty string) |
+| `required` | No | If `false`, the step may be skipped when not applicable (default: `true`) |
+| `*` | No | Custom fields are preserved as step metadata but are not interpreted by the engine |
+
+`skippable: true` is a deprecated alias for `required: false` — use `required` in new workflows.
+
+### Body Content
+
+The body is returned to the agent when the step starts. Explain:
+
+- What the step accomplishes
+- What actions to take
+- What outputs to produce
+- How to validate completion
+
+## Workflow Execution Flow
+
+The agent drives workflows through four tools:
+
+1. **Start**: `start_workflow(skill_name, workflow_name)` creates a tracked instance with a unique ID, a scratchpad file for progress notes, and returns the step list. Only one instance per skill/workflow pair can be active at a time.
+2. **First step**: `update_workflow_state(workflow_id, step, action="start")` begins the first step and returns its instructions.
+3. **Execute**: the agent performs the step's actions, producing outputs and updating the scratchpad.
+4. **Advance**: `update_workflow_state(workflow_id, step, action="complete")` marks the step done, **auto-starts** the next pending step, and returns its instructions — no separate `start` call needed. `action="skip"` does the same for steps declared `required: false`.
+5. **Finalize**: when the last step is completed or skipped, the workflow is **auto-finalized** — state and scratchpad are cleaned up automatically.
+
+To abort a workflow early, use `end_workflow(workflow_id, action="abort")`.
+
+### Recovery
+
+Workflow state survives context loss and restarts:
+
+- `query_workflow()` without arguments lists all active workflows
+- `query_workflow(workflow_id=...)` returns the full state: per-step status, current step, and scratchpad path
+- Resume from the current step — all progress is preserved
+
+Instances abandoned across sessions are expired automatically after a configurable staleness window.
+
+## Step Design Patterns
+
+### Atomic Steps
+
+Each step should address one concern. Break complex work into smaller, focused steps:
+
+```
+# Good: atomic steps
+01-requirements/  # Gather and analyze requirements
+02-design/        # Design the solution
+03-implement/     # Write the code
+04-test/          # Validate the implementation
+
+# Bad: one giant step
+01-do-everything/  # Too broad — hard to track progress
+```
+
+### Clear Instructions
+
+Each step should provide actionable guidance:
+
+```markdown
+# Good: specific actions
+## Your Task
+1. Read the feature request in `docs/feature-specs/my-feature.md`
+2. Identify the core requirements
+3. List any ambiguities or missing information
+
+## Output
+Create a requirements checklist as a markdown file
+```
+
+Avoid vague directives like "think about the requirements and write them down".
+
+### Provide Clear Validation Criteria
+
+Each step should define what "done" looks like:
+
+```markdown
+## Validation
+- [ ] All files pass linting
+- [ ] All tests pass
+- [ ] Type checking succeeds
+```
+
+### Mark Steps as Optional When Needed
+
+Use `required: false` for steps that are conditionally needed, and say in the body how to decide:
+
+```yaml
+---
+title: "Configure Database"
+required: false
+---
+
+# Database Configuration
+
+Skip this step if the project already has a configured database.
+Check for `config/database.toml` to verify.
+```
+
+### Leveraging References and Scripts
+
+Use `references/` for detailed content that doesn't fit in the main instructions, and `scripts/` for executable code the step should run:
+
+```
+02-validate/
+├── instructions.md          # Main: "Run validation checks"
+├── references/
+│   └── lint-rules.md        # Detailed: rule explanations
+└── scripts/
+    └── lint-checks.sh       # Executable: runs project linting
+```
+
+## Example Workflow
+
+```
+workflows/
+└── feature-planning/
+    ├── 01-requirements/
+    │   └── instructions.md
+    ├── 02-design/
+    │   ├── instructions.md
+    │   └── references/
+    │       └── design-patterns.md
+    └── 03-implementation-plan/
+        └── instructions.md
+```
+
+**01-requirements/instructions.md**:
+
+```yaml
+---
+title: "Gather Requirements"
+---
+
+# Requirements Gathering
+
+## Your Task
+1. Read the feature request or user story
+2. Identify functional and non-functional requirements
+3. List assumptions and constraints
+
+## Output
+Create a requirements document at `docs/requirements/{feature-name}.md`
+
+## Validation
+- All requirements are testable
+- Assumptions are explicit
+- Constraints are documented
+```
+
+## Testing Your Workflow
+
+Before considering a workflow complete:
+
+1. **Manual walkthrough**: read through each step's instructions — do they make sense?
+2. **Ordering check**: are steps in the right order? Do dependencies flow correctly?
+3. **Validation check**: does each step have clear success criteria?
+4. **SKILL.md check**: is the workflow documented in the skill's SKILL.md?
+
+## Common Patterns
+
+- **Planning**: requirements → design → implementation-plan → validation
+- **Refactoring**: analyze-current → design-refactor → implement-changes → validate
+- **Onboarding**: read-context → understand-architecture → setup-environment → first-task