furanku-skills

Tools and skills that help AI coding agents work the way you want on your projects.

If you use Claude Code, Codex, Cursor, or a similar agent, this repo gives you:

1. Skills — short instruction packs the agent can load when the task matches (install once, then ask in normal language).
2. A command-line tool — furanku-skills, with namespaces such as guidance-composer for picking engineering principles and writing them into your project so agents keep following them.

You do not need every skill. Install what matches how you work.

Install skills

Agent Skills are portable. From any project:

# all skills from this collection
npx skills add rafaelvidaurre/furanku-skills

# or just one
npx skills add rafaelvidaurre/furanku-skills --skill guidance-composer
npx skills add rafaelvidaurre/furanku-skills --skill testing-best-practices

After install, talk to your agent as usual. When a skill fits, it should load and follow it.

The picker shows skills in groups: most live in the main (General) group; skills still proving themselves appear under Experimental (currently council).

Command-line tool

The collection ships one CLI: furanku-skills.

Quick start (recommended)

From a checkout, in your project directory:

node /path/to/furanku-skills/bin/furanku-skills.js
# or jump straight into setup:
node /path/to/furanku-skills/bin/furanku-skills.js init

Via npx:

npx furanku-skills
npx furanku-skills init

With no command, the CLI opens an interactive menu (setup wizard, agent files, guidance, help). The init wizard walks you through:

1. Agent instructions — create AGENTS.md and a CLAUDE.md → AGENTS.md symlink
2. Install skills — hands off to interactive npx skills@latest add rafaelvidaurre/furanku-skills (the skills CLI owns the picker)
3. Project guidance — optional guidance-composer setup

Non-interactive (agents / CI):

# sensible default: AGENTS.md + all skills, no guidance yet
npx furanku-skills init --yes

# pick pieces explicitly
npx furanku-skills init --yes --agents-md --skills guidance-composer,testing-best-practices --no-guidance
npx furanku-skills init --yes --no-skills --guidance simplest-current,prefer-libraries --guidance-mode inline

Commands & namespaces

| Command / namespace | What it does | | --- | --- | | init | Interactive (or flagged) project setup — agents file, skills install, guidance | | agents-md | Only create empty AGENTS.md + CLAUDE.md → AGENTS.md symlink | | guidance-composer | Compose engineering rules from a catalog into the project (guide) | | menu | Open the interactive menu explicitly (same as running with no command) | | version | Print the installed version |

node bin/furanku-skills.js help
node bin/furanku-skills.js agents-md --yes
node bin/furanku-skills.js guidance-composer list
node bin/furanku-skills.js guidance-composer inject --ids simplest-current --mode inline --harness agents --yes

Skills (what each one is for)

guidance-composer

Useful if: you want agents to follow a few explicit principles (for example “keep it simple,” “don’t keep old APIs around”) without rewriting those rules every chat.

What it does: offers a catalog of short, opinionated rules. You pick which ones apply. They are written into a file your agent already reads (often AGENTS.md), or into a linked doc.

You can use the CLI yourself or ask an agent to help you choose. Details: guidance-composer README.

> Help me set up project guidance — simplest path, no backward compatibility.
> What guidance options are in the catalog?

testing-best-practices

Useful if: you want better automated tests — clearer failures, less brittleness, less noise — without being forced into one testing religion.

What it does: steers the agent to treat each test as evidence for behavior that matters, and to match your project’s language and tools.

> Add tests for this change using the project's conventions.
> Review this test suite for flaky or low-value tests.
> What's the smallest useful test for this database path?

Optional deep dive: interactive testing guide.

prr

Useful if: product decisions get lost across chats, agents, or weeks — and you want a durable, trustworthy record of what the product is supposed to be.

What it does: keeps a Product Requirements Record in prr/ at your repo root: requirements, scope exclusions, and open questions, each confirmed with you and backed by verbatim evidence of what you actually said. It also listens while you work — when a coding session drifts into product intent (“users should be able to…”, “that’s out of scope”), it captures it instead of letting it evaporate.

> Start tracking product requirements for this project.
> Digest the tentative requirements and open questions.
> Audit the PRR — anything unconfirmed or contradictory?

progress-report

Useful if: you want a clear status of what changed recently, what’s in flight, and what’s blocked — based on real project evidence, not vibe.

What it does: writes a human-readable progress report over several time windows (fresh work through about the last month). It remembers past findings in a machine-local ledger outside your repo, so nothing lands in your commits, diffs, or merges.

> Give me a progress report for this project.
> Summarize status and progress for the last week.

decision-trail

Useful if: an agent (or you) will make a series of important choices and you want a compact log you can review later without replaying the whole session.

What it does: appends a simple table of decisions, reasons, evidence, and results (local by default).

> Keep a decision trail while you work through this migration.
> Leave a reviewable record of the important calls.

council (experimental)

Useful if: a decision is hard enough that you want several AI models to argue it out before you trust a single answer.

What it does: your agent runs a moderated “council”: multiple models take positions, challenge each other, and vote. You get a verdict plus dissent — not one model talking to itself.

> Council: should we migrate this service from REST to gRPC?
> Council of 5 — brainstorm product names.

First use walks you through approving which model tools may run on your machine.

crew

Useful if: you run multi-agent work and want clear ownership (who plans, who implements, who reports to whom) instead of a pile of unnamed agents.

What it does: defines simple roles — optional overall coordinator, lead for a larger front of work, and people focused on one concrete outcome. Model picks come from model-routing. Works with whatever your setup already has: the harness's strongest suitable native orchestration surface (Claude Workflow where available), or any orchestrator and issue tracker you configure per machine or project.

> Act as Commander and coordinate my projects without editing project files.
> You are Captain for the editor work. Report to me.
> Use GitHub issues as Crew's work record in this repo.

model-routing

Useful if: an agent is about to spawn or delegate work and you want the agent/model/effort pick to be evidence-based, quota-aware, and auditable — not vibes.

What it does: compiles a routing brief (research-backed candidates, your preferences, live quota), lets the spawning agent judge the pick, then gate-checks it: disabled candidates, missing features, agents the mechanism cannot launch, and exhausted quota are refused with reasons, and unknown quota needs an explicit sign-off.

> Which model should own this refactor? Show me the routing brief.
> Prefer terra for bulk edits in this repo.
> Show the effective routes for this repository.

Repository layout

.claude-plugin/
  marketplace.json # skill groups shown by `npx skills` (e.g. experimental)
skills/
  <name>/
    SKILL.md       # what the agent follows
    README.md      # human docs (where present)
    references/    # extra detail the skill loads when needed
    scripts/       # helpers
    assets/        # templates the skill copies (where present)
    bin/ lib/ test/ # CLI-bearing skills only (guidance-composer)

License

See LICENSE. Issues and contributions welcome.