feat: initialize agent skills repository with three starter skills

Add project structure documentation (AGENTS.md) and initial README files that organize skills by bucket and invocation type (user-invoked vs model-invoked). Introduce three skills: - forge-interaction: GitHub/Gitea CLI automation for issues, PRs, releases - forge-preferences: personal forge conventions (companion to forge-interaction) - pkm-curation: Obsidian vault curation and note management Include reference docs for vault conventions, agent integration, and the invocation model that separates user-only from model-reachable skills.
2026-06-22 13:15:36 -04:00
commit 041be56757
10 changed files with 648 additions and 0 deletions
@@ -0,0 +1,29 @@
 # Steve Beaulac Skills
 A collection of agent skills (slash commands and behaviors) loaded into my agent.
 # Structure
 Skills are organized into buckets based on where they can be used and their category.
 - Use `/common/` for skills that work in all CLI agents.
 - Use `/common/misc/` for skills that work in all CLI agents and are in the misc category.
 - Use an agent-specific bucket only when a skill is intended for a specific agent.
 Skill are organized into categories based on their function. For example, `/common/misc/` is a bucket for miscellaneous skills that work in all CLI agents.
 If we have a skill that is only relevant to a specific agent, we can put it in an agent-specific bucket. For example, if we have a skill that is only relevant to the `opencode` agent, we can put it in `/opencod/misc`.
 ## list of categories
 - `engineering/` — daily code work
 - `productivity/` — daily non-code workflow tools
 - `misc/` — kept around but rarely used
 - `personal/` — tied to my own setup, not promoted
 - `in-progress/` — drafts not yet ready to ship
 - `deprecated/` — no longer used
 Each bucket folder has a `README.md` that lists every skill in the bucket with a one-line description, with the skill name linked to its `SKILL.md`. Bucket `README.md`s and the top-level `README.md` group entries into **User-invoked** and **Model-invoked**.
 Every `SKILL.md` is either user-invoked (`disable-model-invocation: true`, reachable only by the human) or model-invoked (model- or user-reachable). For the full definitions, description conventions, and why a user-invoked skill can invoke model-invoked skills but never another user-invoked one, see [docs/invocation.md](./docs/invocation.md).
@@ -0,0 +1,12 @@
 # Skills
 A collection of agent skills (slash commands and behaviors) loaded into Steve Beaulac's agents.
 ## User-invoked
 - [pkm-curation](common/pkm-curation/SKILL.md) — Curate an Obsidian-style personal knowledge vault.
 ## Model-invoked
 - [forge-preferences](common/personal/forge-preferences/SKILL.md) — Apply Steve's personal or project-specific GitHub/Gitea forge preferences.
 - [forge-interaction](common/engineering/forge-interaction/SKILL.md) — Work safely with GitHub and Gitea repositories, issues, pull requests, releases, and remote forge state.
@@ -0,0 +1,12 @@
 # Common Skills
 Skills that work in all CLI agents.
 ## User-invoked
 - [pkm-curation](pkm-curation/SKILL.md) — Curate an Obsidian-style personal knowledge vault.
 ## Model-invoked
 - [forge-preferences](personal/forge-preferences/SKILL.md) — Apply Steve's personal or project-specific GitHub/Gitea forge preferences.
 - [forge-interaction](engineering/forge-interaction/SKILL.md) — Work safely with GitHub and Gitea repositories, issues, pull requests, releases, and remote forge state.
@@ -0,0 +1,9 @@
 # Engineering Skills
 ## User-invoked
 _None yet._
 ## Model-invoked
 - [forge-interaction](forge-interaction/SKILL.md) — Work safely with GitHub and Gitea repositories, issues, pull requests, releases, and remote forge state.
@@ -0,0 +1,212 @@
 ---
 name: forge-interaction
 description: Use when the user wants forge work such as opening a PR, creating or listing issues, checking CI, looking at the repo, pushing a branch, publishing changes, or making a release on GitHub or Gitea.
 ---
 # Forge Interaction
 Use this skill for Git forge work on GitHub or Gitea, especially when the user asks to:
 - open a PR;
 - create, list, modify, or comment on issues;
 - create, list, modify, comment on, or merge pull requests;
 - check CI;
 - look at the repo on the forge;
 - push a branch;
 - publish changes;
 - make or inspect a release.
 ## Purpose
 Choose the correct forge CLI and use it to interact with issues, pull requests, releases, CI, and repository state.
 This skill is intended to perform forge actions, including mutating actions, when the user asks for them. Do not turn every requested forge action into a confirmation loop; if the user clearly asks to create, edit, comment, publish, or release, do the requested action after selecting the correct forge and tool.
 ## Strict Decision Tree
 Follow this order every time.
 ### 1. Determine the target remote
 1. If the user explicitly says which remote or forge to use, use that.
 2. Else, if user/project memory or repo guidance states where to find the forge, use that.
 3. Else, if a remote named `forge` exists, use `forge`.
 4. Else, if the user has configured a default remote, use that.
 5. Else, use `origin`.
 Useful inspection commands:
 ```bash
 git remote -v
 git config --get checkout.defaultRemote
 git config --get clone.defaultRemoteName
 git config --get branch.$(git branch --show-current).remote
 ```
 Interpretation:
 - A remote named `forge` is the preferred convention for the canonical forge remote.
 - If no `forge` remote exists, `origin` is the fallback.
 - If the current branch has an upstream remote and no stronger rule applies, treat that as the user's configured default for the current work.
 Only mention this selection if there is ambiguity or a conflict.
 ### 2. Determine the forge type from the chosen remote
 Inspect the selected remote URL:
 ```bash
 git remote get-url <remote>
 ```
 Classify it:
 - URLs containing `github.com` are GitHub.
 - URLs containing `gitea`, or a known Gitea host from memory/project guidance, are Gitea.
 - If the remote is self-hosted and ambiguous, inspect repo guidance, memory, and web/API/tool configuration before asking.
 Do not choose based on which CLI is installed. The remote determines the forge; the forge determines the CLI.
 ### 3. Choose the CLI
 - If the forge is GitHub, use `gh`.
 - If the forge is Gitea, use `tea`.
 Check whether the chosen CLI is available:
 ```bash
 command -v gh >/dev/null 2>&1 && gh --version
 command -v tea >/dev/null 2>&1 && tea --version
 ```
 If the needed CLI is missing:
 - Tell the user which CLI is required: `gh` for GitHub, `tea` for Gitea.
 - Tell the user to install it.
 - If it may already be installed but not discoverable, tell the user to add it to their `PATH`.
 - Do not use the wrong CLI as a fallback.
 ### 4. Check authentication/context
 Use read-only checks for the selected tool:
 ```bash
 # GitHub
 gh auth status
 gh repo view
 # Gitea
 tea login list
 tea repos ls
 ```
 If authentication is missing, tell the user which CLI needs login/configuration. Do not ask the user to paste tokens or secrets.
 ### 5. Do the requested forge task
 Perform the requested action with the selected CLI.
 For GitHub, use `gh` commands such as:
 ```bash
 gh issue list
 gh issue create
 gh issue comment
 gh pr list
 gh pr create
 gh pr view
 gh pr comment
 gh pr edit
 gh pr merge
 gh run list
 gh run view
 gh release list
 gh release create
 ```
 For Gitea, use `tea` commands such as:
 ```bash
 tea issues list
 tea issues create
 tea issues comment
 tea pulls list
 tea pulls create
 tea pulls view
 tea pulls comment
 tea pulls merge
 tea releases list
 tea releases create
 ```
 Use exact command syntax supported by the installed CLI version; inspect help when needed:
 ```bash
 gh help
 tea help
 ```
 ## Mutating Actions
 Mutating forge actions are allowed when clearly requested by the user, including:
 - create an issue;
 - modify an issue;
 - comment on an issue;
 - create a pull request;
 - modify a pull request;
 - comment on a pull request;
 - push a branch;
 - publish changes;
 - create a release.
 Still be careful with destructive or high-impact actions:
 - Ask before deleting branches, tags, releases, issues, or repositories.
 - Ask before force-pushing.
 - Ask before merging a PR unless the user explicitly asked to merge it.
 - Ask before overwriting existing release assets or tags.
 ## Branch and PR Preparation
 Before creating or updating a PR:
 1. Select the remote using the strict decision tree.
 2. Select the CLI from the remote's forge type.
 3. Inspect branch state and upstream tracking.
 4. Inspect the diff against the target branch.
 5. Read the PR template if one exists.
 6. Push the branch if needed and requested by the workflow.
 7. Create or update the PR.
 Useful local inspection:
 ```bash
 git status --short --branch
 git branch -vv
 git diff --stat
 git diff --check
 ```
 ## Output Style
 Normally, do not over-explain. If the remote/tool selection is straightforward, just complete the task and summarize the result.
 Report detection details only when there is ambiguity, conflict, missing tooling, or failure. In those cases include:
 - selected remote;
 - detected forge;
 - selected CLI;
 - reason for the choice;
 - what the user needs to fix, if anything.
 ## Companion Personal Skill
 Personal forge preferences should live in a separate skill or memory entry, not in this general skill. That companion skill/memory may specify things like:
 - preferred default remote conventions;
 - known personal Gitea or GitHub hosts;
 - preferred issue/PR/release styles;
 - project-specific forge rules.
 This general skill should consume that memory/guidance when present, but keep the generic decision tree above as the fallback.
@@ -0,0 +1,31 @@
 ---
 name: forge-preferences
 description: Use with forge-interaction to apply Steve's personal or project-specific GitHub/Gitea remote, CLI, issue, PR, and release preferences.
 ---
 # Forge Preferences
 Use this companion skill with `/forge-interaction` when personal or project-specific forge preferences are relevant.
 ## Purpose
 Store personal conventions that should not live in the generic forge interaction skill.
 ## Current Preferences
 - If a remote named `forge` exists, treat it as the canonical forge remote.
 - If no `forge` remote exists, use the user's configured default remote when available.
 - If no default remote is configured, use `origin`.
 - Use the forge type of the selected remote to choose the CLI:
  - GitHub → `gh`
  - Gitea → `tea`
 - If the correct CLI is missing, tell the user to install it or add it to `PATH`.
 - Do not use the wrong CLI as a fallback.
 ## Open Questions To Fill In Later
 - Known personal Gitea hosts.
 - GitHub usernames or organizations.
 - Preferred PR title/body format.
 - Preferred issue labels and milestones.
 - Release naming and tagging conventions.
@@ -0,0 +1,213 @@
 ---
 name: pkm-curation
 description: Curate an Obsidian-style personal knowledge vault by classifying notes, normalizing frontmatter, improving structure, extracting atomic notes, and adding meaningful wikilinks. 
 disable-model-invocation: true
 ---
 # PKM Curation
 Use this skill when working inside a Markdown-first vault that values curation over collection.
 ## Goals
 - Turn raw notes into clear, reusable notes.
 - Keep new notes consistent with vault conventions.
 - Strengthen the link graph with meaningful `[[wikilinks]]`  syntax `[[Note Title]]`.
 - Extract atomic notes from long or mixed-topic notes.
 - Avoid unnecessary reorganization and weak links.
 ## Read This First
 - Read `AGENTS.md` in the current repo scope before editing notes.
 - Read `references/vault-conventions.md` when normalizing metadata, deciding note types, or choosing folders.
 - Read `references/agent-integration.md` when running this skill through an agent.
 - Keep changes small and reviewable.
 - Keep file operations local to the vault unless the user explicitly asks otherwise.
 ## Workflows
 ## Search for notes
 ```bash
 # Search by filename
 fd --type f ".md" "$HOME/Documents/nca-notes" | rg -i "keyword"
 # Search by content
 rg -l "keyword" "$HOME/Documents/nca-notes" --include "*.md"
 ```
 ## Curate existing note
 1. Inspect the target note or note set.
 2. Identify the note type: inbox, source, atomic, project, daily, or reference.
 3. Normalize frontmatter and basic structure.
 4. Clarify the title if the current one is vague or timestamp-like.
 5. Summarize or distill the note if it mixes too many ideas.
 6. Add or suggest meaningful `[[wikilinks]]` to related notes.
 7. If a note contains multiple durable ideas, extract 1-3 atomic notes.
 8. Suggest moving the note only if the destination is clearly better.
 ## Find related notes
 Search for `[[Note Title]]` across the vault to find backlinks:
 ```bash
 rg -l "\\[\\[Note Title\\]\\]" "$HOME/Documents/nca-notes" --include "*.md"
 ```
 ### Find index notes
 ```bash
 fd --type f "Index" "$HOME/Documents/nca-notes"
 ```
 ## Operating Rules
 - Prefer reorganization over curation.
 - Do not move, rename, or delete many notes at once unless the user asks.
 - Do not invent links based only on shared words.
 - Preserve the user's voice unless the user asks for a rewrite.
 - Keep source material and evergreen ideas separate when possible.
 - Treat `Inbox/` as temporary capture, not long-term storage.
 - Preserve all command blocks, code snippets, configuration directives, and
  step-by-step instructions verbatim. Do not summarize or condense them.
 - For reference/source notes: add a brief overview at the top, but keep the
  original commands and details intact below. Completeness > brevity.
 - Read every file completely before editing. Do not rely on head/tail,
  heading-only scans, or partial reads to judge a file's content.
 - For any file you plan to move, rename, or modify, run `cat` on the full file
  first. Only then decide what stays, what moves, and what changes.
 ## Note-Type Heuristics
 ### Inbox note
 Use when the note is raw capture, partial thinking, copied text, or an unprocessed link dump.
 Actions:
 - clean obvious structure issues
 - add frontmatter if missing
 - classify for later promotion
 - avoid over-polishing unless requested
 ### Source note
 Use when the note is based on an article, video, book, paper, transcript, or other external material.
 Actions:
 - keep source context intact
 - summarize key takeaways
 - extract reusable ideas into separate atomic notes
 - link to related concepts and projects
 ### Atomic note
 Use when the note captures one durable idea, concept, claim, pattern, or insight.
 Actions:
 - ensure one main idea per note
 - make the title concept-focused
 - add links to neighboring ideas
 - keep it concise and self-contained
 ### Project note
 Use when the note supports active work, planning, resources, decisions, or tasks.
 Actions:
 - preserve project context
 - link tasks to the project note
 - avoid turning active project logistics into evergreen notes unless there is a reusable insight
 ### Daily note
 Use when the note is date-based and captures activity, learning, tasks, or reflection for a single day.
 Actions:
 - preserve chronology
 - link out to durable notes rather than stuffing ideas into the daily note
 ## Linking Guidance
 Add links only when they express one of these relationships:
 - concept to broader concept
 - source note to extracted idea
 - project note to relevant knowledge note
 - daily note to work done or ideas learned
 - sibling concepts that genuinely inform one another
 When linking, prefer existing notes over creating speculative new ones.
 ## Extraction Guidance
 Extract atomic notes when a note contains:
 - multiple durable ideas
 - a strong claim hidden in raw notes
 - a reusable method, distinction, or definition
 - a concept that should be linked from many places
 Keep extracted notes short. One note, one idea.
 ## Common Tasks
 ### Curate one note
 - inspect the note
 - identify note type
 - normalize frontmatter
 - tighten headings and summary
 - add a few strong links
 - suggest extracted atomic notes if warranted
 - locate the target file in the vault
 - inspect nearby related notes before adding links
 - patch the note in place
 - return a short summary of edits and suggested follow-up notes
 ### Curate an inbox batch
 - process a small batch, usually 5-10 notes
 - classify each note
 - normalize metadata
 - suggest which notes should stay raw, become source notes, or become atomic notes
 - avoid large folder reshuffles unless the pattern is clear
 - enumerate a small set of `Inbox/` notes
 - process them one at a time
 - stop and summarize after each batch
 ### Review recent notes
 - inspect recently edited notes
 - identify missing links and vague titles
 - flag notes with mixed concerns
 - suggest a small set of follow-up curation actions
 - search by recent filenames or recent folders when file metadata is available
 - keep edits conservative and return a review summary
 ### Serendipity review
 - choose a note from the vault
 - summarize it briefly
 - compare it to the user's current topic or active project
 - suggest only high-confidence connections
 - pick one note from a user-specified folder or from curated folders only
 - avoid randomizing across obviously raw capture unless the user asks for that
 ## Output Style
 When responding to the user:
 - state what kind of note you think it is
 - summarize the curation changes you made or recommend
 - list any extracted notes to create
 - list meaningful links added or suggested
 - mention any move or rename separately before doing it
 - name the file or files touched
 - separate completed edits from suggested next actions
 - call out anything that still needs user confirmation
 ## If You Need More Context
 If the vault structure is unclear, inspect folders and a few nearby notes before editing.
 If note conventions appear to conflict, follow the most local `AGENTS.md` instructions in scope.
 Don't guess at user preferences. When in doubt, ask the user before making big changes or suggesting speculative links.
@@ -0,0 +1,51 @@
 ---
 id: pkm-curation-agent-integration
 aliases:
  - PKM Curation agent Integration
 tags:
  - knowledge-management
  - reference
 area: Personal Knowledge Management
 project:
 ---
 # Agent Integration
 ## Purpose
 This skill should be usable from any agent, and it should also fit chat environments where the agent as tool access.
 ## Recommended Role
 - batch curation, targeted note cleanup, folder reviews, and repeatable vault maintenance
 - interactive note refinement, serendipity review, and exploratory linking sessions
 - editor-side entry point that delegates vault actions to agent where possible
 ## Preferred Behaviors
 - search the vault before proposing links
 - inspect nearby notes before creating new ones
 - patch files directly when the requested change is clear
 - summarize edits in plain Markdown
 - ask before removing any content or links from a note
 - ask before moving, renaming, or creating many files
 ## Good Task Shapes
 - curate a specific note
 - process a small `Inbox/` batch
 - review recent notes for missing links
 - extract atomic notes from one source note
 - run a serendipity review against a current topic
 ## Avoid
 - large autonomous folder reorganizations
 - broad speculative linking passes
 - converting every long note into atomic notes
 - changing note titles without stating why
 ## Portability Guidance
 - keep the workflow in `SKILL.md` tool-agnostic where possible
 - prefer small deterministic file edits so the skill remains portable to other `SKILL.md`-based agents
@@ -0,0 +1,61 @@
 ---
 id: pkm-curation-vault-conventions
 aliases:
  - PKM Curation Vault Conventions
 tags:
  - knowledge-management
  - obsidian
  - reference
  - ai
 area: Personal Knowledge Management
 project:
 ---
 # Vault Conventions
 ## Required Frontmatter
 All notes should include YAML frontmatter with:
 ```yaml
 ---
 id: unique-id
 aliases: []
 tags: []
 area: Primary area/domain
 project: [[Project Note]]
 ---
 ```
 Use an empty value for `project:` when there is no relevant project note.
 ## Core Principles
 - Markdown-first
 - explicit `[[wikilinks]]`
 - atomic notes for durable ideas
 - project, topic, and date-based organization
 - consistency over novelty
 ## Folder Roles
 - `Inbox/`: raw capture and unprocessed notes
 - `Dailies/`: day-specific notes and reflection
 - `Templates/`: note templates
 - `Knowledge/`: preferred home for evergreen atomic notes if the folder exists or is created
 - project/topic folders: active work and structured reference material
 ## Task Conventions
 - Use Markdown task items: `- [ ] Task description [[Project Name]]`
 - Add status and priority tags where useful
 - Use `due:: YYYY-MM-DD` for due dates
 - Add `start::` and `end::` only when explicitly requested or when tracking active work
 ## Curation Heuristics
 - A saved thing is not yet a knowledge note.
 - A source note is not the same as an evergreen note.
 - A link should reflect a real conceptual or project relationship.
 - A long note may remain long if it is reference material; only extract notes when reuse is likely.
 - Prefer gradual improvement over mass refactoring.
@@ -0,0 +1,18 @@
 # Model-invoked vs user-invoked
 Every `SKILL.md` in this repo is a skill. The one axis that splits them is **invocation** — who can reach it:
 - **User-invoked** — reachable **only by the human typing its name**. Set `disable-model-invocation: true` in the frontmatter. The `description` is **human-facing**: a one-line summary read by a person browsing slash-commands. Strip trigger lists ("Use when the user says…").
 - **Model-invoked** — reachable by **model or user**. The default: omit `disable-model-invocation`. The `description` is **model-facing** and keeps rich trigger phrasing ("Use when the user wants…, mentions…, asks for…") so auto-invocation fires. The test for whether a skill should stay model-invoked: _could the model usefully reach for this autonomously?_ (Reuse is the reason to extract a skill, not the test.)
 Because a user-invoked skill has no description, nothing but the human can reach it — no other skill can fire it. So a user-invoked skill may invoke model-invoked skills, but it can never reach another user-invoked skill.
 Bucket `README.md`s and the top-level `README.md` group entries into **User-invoked** and **Model-invoked**.
 ## Dependencies between them
 Dependencies are expressed as **`/skill`-style prose invocation** ("Run the `/grilling` skill"), not deep `../other-skill/FILE.md` cross-references. Shared reference docs live inside the skill that owns them; other skills reach that material by invoking the skill, not by linking across folders.
 ## Passive vs active domain work
 Merely _reading_ `CONTEXT.md` for vocabulary is a one-line prose pointer, not the `domain-modeling` skill. Only the active build/sharpen discipline (challenge terms, edge-case scenarios, write ADRs, update `CONTEXT.md` inline) is `domain-modeling`.