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.
This commit is contained in:
@@ -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`.
|
||||
Reference in New Issue
Block a user