Incitaciones 🤖

A collection of reusable prompts and best practices for CLI LLM tools.

Quick Install

Via npm / npx (recommended)

# Install as pi package (native skills, best UX):
pi install npm:incitaciones

# Or install across all tools (pi, Claude Code, Amp, Gemini CLI, etc.):
npx incitaciones install

# Install only the essentials bundle:
npx incitaciones install --bundle essentials

# List available skills:
npx incitaciones list

# Show skill details:
npx incitaciones info commit

From git

Clone and install prompts as skills for pi CLI, Claude Code, Amp, Gemini CLI, and other tools:

git clone https://github.com/charly-vibes/incitaciones.git
cd incitaciones
./install.sh

Install options:

./install.sh --bundle essentials    # Core prompts only
./install.sh --bundle planning      # Planning workflows
./install.sh --bundle reviews       # Review prompts
./install.sh --bundle documentation # Documentation tools
./install.sh --format commands      # Legacy flat-file format for other tools
./install.sh --disable-model-invocation # Require explicit /skill:name usage
./install.sh --list                 # Show available prompts
./install.sh --help                 # Show all options

After installation:

# pi CLI native skill invocation
/skill:commit
/skill:debug
/skill:create-plan

# pi CLI prompt-template shortcuts
/commit
/debug
/create-plan

# Other compatible tools
/debug
/create-plan
/code-review

For non-pi tools, exact command syntax depends on the harness, but slash-command usage like the examples above is the common case.

Skills are installed to ~/.agents/skills/ (or project .agents/skills/) and copied to tool-specific directories when detected. For pi, skills are discovered from .agents/skills/ / ~/.agents/skills/, and the installer also writes prompt templates to ~/.pi/agent/prompts/ or project .pi/prompts/ so pi users can invoke either /skill:<name> or the shorter /<name> template command.

Native pi package install

This repository is published as an npm package with a pi manifest, so pi can install it directly:

pi install npm:incitaciones
# or from git
pi install git:github.com/charly-vibes/incitaciones
# or from a local clone
pi install .

The repository includes checked-in pi package resources under pi-package/, and the generation step can refresh them when content changes:

• pi-package/skills/ — Agent Skills with pi-compatible frontmatter
• pi-package/prompts/ — prompt templates for slash-command shortcuts

After changing distilled content or manifest entries, run just generate-pi-resources and commit the updated pi-package/ files.

Publishing a new version

npm version patch   # bumps to 0.2.1, creates a git tag
npm version minor   # bumps to 0.3.0
npm version major   # bumps to 1.0.0

git push --tags     # triggers CI → auto-publishes to npm

CI workflow: .github/workflows/npm-publish.yml — runs on v* tags, generates pi resources, then publishes.

Top 10 Most Used Skills

Based on analysis of 621 pi sessions across 43 repositories:

Skill	Invocations	Repos	What it does
commit	513	41	Create well-structured, atomic git commits with clear intent
rule-of-5-universal	254	35	5-stage review for any artifact (Steve Yegge's method)
tdd	168	28	Test-driven development workflow
issue-review	158	31	Review issues for completeness and dependencies
debug	94	27	7-step diagnostic workflow for debugging issues
create-issues	44	19	Generate trackable issues from implementation plans
create-handoff	31	10	Generate context documents for session continuity
grill-me	28	12	Interview the user relentlessly about a plan or design
doc-link-verifier	27	9	Audit documentation for broken links
review-documentation	27	9	Review docs for cognitive scannability and AI-readiness

Session Lifecycle & Knowledge Management

Workflow skills that form a complete session lifecycle with persistent operational knowledge:

Skill	When	What it does
whisper	Start of project/branch	Manage ~/.whisper/ — global, tiered knowledge directory (init, check, status, link, decommission)
next	Quick context switch	Rapid snapshot to ~/.whisper/ — no git, no tickets, just stash
park	Thorough context switch	Log to journal, release ticket claims, record to beads epic
close	End of day	Log to journal, route knowledge to ~/.whisper/, commit, clear
renew	Start of session	Load journal + whisper + beads context, claim tickets with file conflict detection

Uses $JOURNAL_PATH (default ~/dev/status) for the daily log. See content/references-whisper-workflow.md for the full reference.

Full analysis: content/research-finding-skill-usage-analysis.md

Quick Start

# Browse content
ls content/

# Find prompts about a topic
just find refactoring

# Create new prompt scaffold
just new prompt "Your Task Name"

# Interactive search with fzf
just search

Structure

Everything lives in content/ with descriptive filenames:

• prompt-*.md - Reusable prompts (source)
• distilled/ - Optimized prompts for agent consumption (single file or multi-file)
• research-*.md - Experiments and findings
• example-*.md - Real-world examples
• template-*.md - Templates for new content

Key infrastructure files:

• package.json — npm package with pi manifest and bin entry for npx CLI
• scripts/cli.mjs — npx CLI entry point (npx incitaciones install / list / info)
• scripts/generate-pi-resources.mjs — generates pi-package/ from manifest
• pi-package/ — generated pi-compatible skills and prompt templates (gitignored)
• .github/workflows/npm-publish.yml — CI: auto-publishes to npm on v* tags
• .github/workflows/pages.yml — CI: deploys GitHub Pages site

See AGENTS.md for detailed structure and CONTRIBUTING.md for guidelines.

Commands

just --list              # Show all commands
just new [type] [name]   # Create new content
just find [term]         # Search content
just search              # Interactive fzf search
just validate            # Check metadata
just stats               # Show statistics

# Skills installation
just install                  # Run ./install.sh with any flags you pass through
just generate-pi-resources    # Build pi package skills + prompt templates
just validate-pi-package      # Verify pi package resources match the manifest
just list-distilled           # List all distilled prompts
just validate-distilled       # Validate distilled prompts
just list-bundles             # Show available bundles
just sync-manifest            # Validate manifest references and update content/manifest.json version
just generate-skill NAME      # Preview SKILL.md output for a prompt
just nucleus-roundtrip NAME   # Use pi to compile+decompile a prompt via Nucleus lambda
just compare-nucleus NAME     # Diff a Nucleus roundtrip against the canonical distilled prompt
just analyze-traces PATH      # Analyze trace exports from agent tools
just analyze-traces-auto      # Auto-detect local CLI history locations
just trace-insights           # Process traces and write insight artifacts

Trace Analysis

You can analyze exported traces from Claude, Gemini, Codex, AmpCode, and OpenCode with:

just analyze-traces examples/trace-analysis

If your histories live in the default local CLI directories, use auto-detection:

just analyze-traces-auto

Or directly:

node scripts/analyze-traces.js --auto-detect --format markdown

For the simplest workflow, use the wrapper command:

just trace-insights

That will:

• auto-detect local trace sources
• print a readable markdown summary
• write .cache/trace-insights/latest-report.json
• write .cache/trace-insights/session-records.jsonl
• write .cache/trace-insights/label-queue.jsonl

The analyzer now uses an incremental cache at .cache/trace-analysis-cache.json. Unchanged files are reused automatically on later runs. Use --no-cache if you want a full recomputation.

It can also emit normalized session records and join manual labels:

node scripts/analyze-traces.js \
  --auto-detect \
  --session-records-out /tmp/session-records.jsonl \
  --label-queue-out /tmp/label-queue.jsonl

To join labels back into the analysis:

node scripts/analyze-traces.js \
  --auto-detect \
  --labels examples/trace-analysis/labels-sample.jsonl \
  --format markdown

Or with the wrapper:

just trace-insights --labels examples/trace-analysis/labels-sample.jsonl

This scans JSON, JSONL, NDJSON, log, text, and markdown exports, then reports:

• provider mix
• prompt references matched against content/manifest.json
• skill format counts (single-file vs progressive-disclosure)
• progressive-disclosure reference mentions and stage hints
• slash commands
• tool and model usage
• prompt-to-tool pairs
• workflow transitions
• heuristic session outcomes
• rough conclusions across the analyzed traces

For raw JSON output:

node scripts/analyze-traces.js examples/trace-analysis --format json

The new session-level signals are heuristic, not authoritative:

• prompt -> tool pairs estimate when a prompt mention actually led to tool execution
• workflow transitions show common session shapes like prompt -> tool or user -> assistant
• outcomes classify sessions as succeeded, failed, needs_input, or unknown from assistant language

This is strongest for comparative usage analysis, not for hard evaluation of prompt quality.

Normalized session records include fields such as:

• session_id
• provider
• model
• task_type
• prompts_used
• skill_formats
• progressive_skills_used
• references_used
• stage_hints
• tools_used
• tests_run_or_mentioned
• verification_present
• commit_created
• tokens_total
• turn_count
• outcome_guess
• first_user_excerpt
• last_assistant_excerpt

The label queue is intended for manual annotation. Each queued record includes suggested questions so you can build a labeled evaluation set over time.

For progressive-disclosure skills, the analyzer now reads optional manifest metadata such as skill_format, eval.stages, and eval.references. That makes it possible to compare not just prompt usage, but also which stages and reference files were actually involved in successful sessions.

The aggregate report now separates adoption from evidence:

• Top Skills By Session and Skill Formats By Session count each skill at most once per session.
• Top References By Session and Top Stages By Session count whether a reference or stage appeared in a session.
• Skill Evidence Hits, Top Reference Evidence Hits, and Top Stage Evidence Hits count repeated detections across messages and tool inputs.

Use the session-level sections for effectiveness comparisons. Use the evidence-hit sections to understand how often the analyzer observed supporting signals.

Current auto-detected sources include common local paths such as:

• ~/.claude/projects
• ~/.gemini/tmp/**/chats/session-*.json
• ~/.codex/history.jsonl
• ~/.codex/log/codex-tui.log

AmpCode and OpenCode are only included when conversation-like files are found.

---

Meta Prompt for LLMs

Use this prompt when asking other LLMs to help you organize prompts in your projects

I want to organize prompts and AI instructions for my project. Please help me set up a system based on these principles:

STRUCTURE:
- Single flat directory (e.g., "prompts/" or ".ai/")
- Slugified filenames with type prefixes:
  - prompt-task-{name}.md for specific tasks
  - prompt-system-{name}.md for agent configurations
  - prompt-workflow-{name}.md for multi-step processes
  - instructions-{context}.md for project-specific instructions

METADATA:
Every file should have YAML frontmatter:
---
title: Human Readable Title
type: prompt|instruction|workflow
tags: [relevant, searchable, tags]
tools: [claude-code, cursor, aider]
status: draft|tested|verified
created: YYYY-MM-DD
updated: YYYY-MM-DD
version: 1.0.0
related: [other-file.md]
source: where-this-came-from
---

CONTENT STRUCTURE:
1. ## When to Use - Context for applying this prompt
2. ## The Prompt - The actual prompt text in a code block
3. ## Example - At least one concrete usage example
4. ## Expected Results - What success looks like
5. ## Variations - Alternative approaches
6. ## References - Links to sources or research
7. ## Notes - Caveats or additional context

WORKFLOW:
1. Create content from templates
2. Test with real AI tools
3. Update status: draft → tested → verified
4. Link related files in frontmatter
5. Track changes in CHANGELOG.md

AUTOMATION:
Create a justfile or Makefile with commands:
- new: Create from template
- find: Search by tag or keyword
- search: Interactive fzf browser
- validate: Check metadata completeness
- stats: Show repository statistics

Please analyze my project at [path] and:
1. Propose which existing prompts/instructions to capture
2. Suggest an appropriate directory name
3. Create initial template files
4. Set up basic automation commands
5. Draft 2-3 initial prompt files based on current usage

Focus on simplicity and discoverability over complex organization.

Examples

Creating a new task prompt:

just new prompt "Incremental Refactoring"
# Edit content/prompt-task-incremental-refactoring.md
# Edit content/distilled/incremental-refactoring.md (or create a directory for multi-file)
# Add prompt text, examples, and distilled runtime form
# Register the prompt in content/manifest.json
# Run just validate-distilled && just sync-manifest
# Test it with Claude Code
# Mark as tested and commit

Finding related content:

just find refactoring
# Shows all files tagged with 'refactoring'

just search
# Opens fzf to interactively browse and preview content

Validating content:

just validate
# Checks required metadata, status values, and related links
# Reports any issues

Experimenting with Nucleus lambda roundtrips:

just nucleus-roundtrip distill-prompt
# Uses pi -p to compile the distilled prompt to lambda and decompile it back to prose
# Writes content/compiled/nucleus/distill-prompt.lambda.md
# Writes content/compiled/nucleus/distill-prompt.roundtrip.md
just compare-nucleus distill-prompt
# Diffs the roundtrip prose against the canonical distilled prompt

Pass extra pi flags through when needed:

just nucleus-roundtrip distill-prompt --model sonnet:high

The content/compiled/nucleus/ directory is experimental. It is intentionally kept outside content/distilled/ so these comparison artifacts do not affect installation or packaged skills.

What Goes Here?

✅ Good candidates:

• Prompts you use repeatedly
• Task patterns that work well
• Tool-specific configurations
• Research on what works
• Real examples of successful interactions

❌ Don't include:

• Project-specific code
• Sensitive information
• One-off experiments without documentation
• Incomplete drafts without context

Philosophy

Flat structure - One directory, easy to find everything Rich metadata - Searchable, relatable, trackable Tested content - Everything should have real usage examples Source attribution - Credit where ideas come from Version control - Track evolution of prompts over time

Contributing

See CONTRIBUTING.md for:

• File naming conventions
• Metadata requirements
• Quality standards
• Submission process

Tools

This repository is designed to work with:

• Claude Code - Anthropic's CLI
• Aider - AI pair programming
• Cursor - AI-first editor
• Gemini CLI - Google's CLI
• Any other LLM CLI tool

The prompts are tool-agnostic where possible, with tool-specific variations noted.

License

[To be determined]

Related Projects

• Awesome Prompts
• Anthropic Prompt Library
• OpenAI Prompt Engineering Guide

---

A note on authorship

All the code in this repository was generated by a large language model. This is not a confession, nor an apology. It's a fact, like the one that says water boils at a hundred degrees at sea level: neutral, technical, and with consequences one discovers later.

What the human did is what tends to happen before and after things come into existence: thinking. Reviewing requirements, arguing about edge cases, understanding what needs to be built and why, deciding how the system should behave when reality —which is capricious and does not read documentation— confronts it with situations nobody anticipated. The hours of planning, of design, of reading specifications until exhaustion dissolves the boundary between understanding and hallucination.

The LLM writes. The human knows what it should say.

There is a distinction, even if looking at the commit history makes it hard to find. The distinction is that a machine can produce correct code without understanding anything, the same way a calculator can solve an integral without knowing what time is. Understanding what that integral is for, whether it actually solves the problem, whether the problem was the right problem to begin with — that remains human territory. For now.

Leer en español