jinn-cli 0.1.0

package/template/skills/skill-creator/SKILL.md

@@ -0,0 +1,112 @@
+---
+name: skill-creator
+description: Create new custom skills by writing SKILL.md playbooks
+---
+
+# Skill Creator Skill
+
+## Trigger
+
+This skill activates when the user wants to create a new custom skill for {{portalName}}.
+
+## Output Location
+
+All skills are stored at `~/.jinn/skills/<skill-name>/SKILL.md`. Each skill lives in its own directory named with kebab-case.
+
+## Behavior by Engine
+
+### Claude Code (claude engine)
+
+Claude Code has native skill creation capabilities. Defer to the engine's built-in skill/memory system when available. The engine knows how to create well-structured instruction files. Simply ensure the output file lands at the correct path: `~/.jinn/skills/<skill-name>/SKILL.md`.
+
+### Codex (codex engine)
+
+Create the SKILL.md file manually following the conventions below. Write the file directly to `~/.jinn/skills/<skill-name>/SKILL.md`.
+
+## Steps
+
+1. Ask the user what the skill should do. Get a clear description of the capability.
+2. Ask for a name (kebab-case). Suggest one if the user does not provide it.
+3. Create the directory `~/.jinn/skills/<skill-name>/` if it does not exist.
+4. Generate the SKILL.md content following the conventions below.
+5. Write the file to `~/.jinn/skills/<skill-name>/SKILL.md`.
+6. Confirm the skill was created and summarize what it does.
+
+## Conventions for Writing Good SKILL.md Files
+
+Every SKILL.md should follow these conventions:
+
+### 1. Clear Trigger Description
+
+Start with a `## Trigger` section that explains exactly when this skill should activate. Be specific about the keywords, phrases, or situations that should invoke this skill.
+
+Good: "This skill activates when the user asks to generate a weekly report from their GitHub repositories."
+Bad: "This skill does reporting stuff."
+
+### 2. Step-by-Step Instructions
+
+Provide numbered steps that an AI engine can follow without ambiguity. Each step should be a concrete action, not a vague directive.
+
+Good: "1. Read the file at `~/.jinn/data/repos.json`. 2. For each repository, fetch the latest commits from the past 7 days."
+Bad: "1. Get the data. 2. Process it."
+
+### 3. Data File References
+
+Specify exact file paths for any data the skill reads or writes. Use `~/.jinn/` as the base directory. Define the expected schema for any JSON or YAML files.
+
+### 4. Error Handling Guidance
+
+Include a section on what to do when things go wrong: missing files, malformed data, unavailable services. Provide fallback behavior.
+
+### 5. Keep Skills Focused
+
+Each skill should do one thing well. If a skill is trying to do too many things, suggest splitting it into multiple skills.
+
+### 6. Use Concrete Examples
+
+Include example inputs, outputs, file contents, and commands wherever possible. Examples remove ambiguity.
+
+## Template
+
+Use this template as a starting point. **YAML frontmatter is required** — both Claude Code and Codex CLIs discover skills by reading frontmatter from `SKILL.md` files. Without it, the skill won't be recognized by engines.
+
+```markdown
+---
+name: <skill-name>
+description: <One-line description of what this skill does>
+---
+
+# <Skill Name>
+
+## Trigger
+
+This skill activates when <specific trigger description>.
+
+## Data Files
+
+- `~/.jinn/<path>` — <description of the file and its format>
+
+## Steps
+
+1. <First concrete action>
+2. <Second concrete action>
+3. ...
+
+## Examples
+
+<Example input and expected behavior>
+
+## Error Handling
+
+- If <error condition>, then <fallback behavior>.
+```
+
+## Auto-Sync
+
+The gateway automatically creates symlinks in `~/.jinn/.claude/skills/` and `~/.jinn/.agents/skills/` pointing to each skill directory. This happens on startup and whenever the `skills/` directory changes. You do not need to manage symlinks manually.
+
+## Error Handling
+
+- If a skill with the same name already exists, ask the user whether to overwrite or choose a different name.
+- Validate that the skill name is valid kebab-case (lowercase letters, numbers, and hyphens only).
+- If the user's description is too vague, ask clarifying questions before generating the skill.

package/template/skills/status/SKILL.md

@@ -0,0 +1,19 @@
+---
+name: status
+description: Show information about the current session
+---
+
+# Status Skill
+
+## Trigger
+
+This skill activates when the user sends `/status`. It shows information about the current session.
+
+## How It Works
+
+- **Web UI**: The frontend handles `/status` locally — it fetches the session details via the API and displays them inline. No message is sent to the engine.
+- **Connectors (Slack, etc.)**: The gateway's session manager intercepts `/status`, looks up the current session, and sends back session info (ID, engine, status, timestamps, last error).
+
+## Your Behavior
+
+You typically won't see `/status` messages because they're handled before reaching the engine. If a `/status` message does reach you, provide session info from your context: session ID, source, channel, engine, and any other metadata available.

package/template/skills/sync/SKILL.md

@@ -0,0 +1,67 @@
+---
+name: sync
+description: Sync the latest conversation with an employee into your context
+---
+
+# Sync Skill
+
+## Trigger
+
+This skill activates when the user sends `/sync @employee-name`. It pulls in the most recent conversation with the specified employee so you can respond with full awareness of what was discussed.
+
+## How It Works
+
+You fetch the conversation yourself using the gateway API. No magic injection — you're in control.
+
+**Gateway URL**: Use the gateway URL from the "Current configuration" section of your system prompt (e.g., `http://127.0.0.1:7777`). Do not hardcode it — it may vary.
+
+### Steps
+
+1. **Extract the employee name** from the user's message (e.g., `/sync @jinn-dev` → `jinn-dev`)
+
+2. **List all sessions** to find the employee's most recent one:
+
+```bash
+curl -s $GATEWAY_URL/api/sessions | jq '[.[] | select(.employee == "EMPLOYEE_NAME")] | sort_by(.lastActivity) | reverse | .[0]'
+```
+
+Replace `EMPLOYEE_NAME` with the target and `$GATEWAY_URL` with the gateway URL from your system prompt. This gives you the most recent session for that employee.
+
+**Tip**: Your own session ID is in the "Current session" section of your system prompt. If you want to exclude child sessions of the current session (to avoid circular references), filter with:
+
+```bash
+curl -s $GATEWAY_URL/api/sessions | jq '[.[] | select(.employee == "EMPLOYEE_NAME" and .parentSessionId != "YOUR_SESSION_ID")] | sort_by(.lastActivity) | reverse | .[0]'
+```
+
+3. **Fetch the full conversation** using the session ID from step 2:
+
+```bash
+curl -s $GATEWAY_URL/api/sessions/SESSION_ID | jq '.messages'
+```
+
+This returns all messages with `role` and `content` fields. Read through them to understand what was discussed.
+
+4. **Respond naturally** — summarize, highlight key points, offer next steps.
+
+## Your Behavior
+
+After fetching and reading the conversation:
+
+1. **Summarize** the key points — what was discussed, what decisions were made, what work was done
+2. **Highlight** any action items, blockers, or open questions
+3. **Offer** to take next steps — continue the work, relay instructions, or loop in other employees
+
+## Edge Cases
+
+- **No sessions found**: If no sessions exist for that employee, tell the user: "I don't see any recent conversations with @employee-name."
+- **Empty messages**: If the session exists but has no messages, note that the session was created but no conversation happened yet.
+- **Employee not found**: If the name doesn't match any sessions, suggest the user check the org with `curl -s $GATEWAY_URL/api/org` to see available employees.
+- **Very long conversations**: You decide how much to read. You can fetch the full conversation and focus on the most recent messages, or read everything if it's short. No artificial limits.
+
+## Examples
+
+User: `/sync @jinn-dev`
+You: *[fetches sessions via API, finds jinn-dev's latest session, reads messages]* "Here's what happened in the latest conversation with @jinn-dev: [summary]. Want me to follow up on anything?"
+
+User: `/sync @content-writer`
+You: *[fetches via API]* "Looking at the recent chat with @content-writer — they finished the blog draft and are waiting for review. Should I ask them to make revisions, or is it ready to publish?"

package/template/skills.json

@@ -0,0 +1,3 @@
+{
+  "installed": {}
+}