AI Agent Skills · token efficiency · 30 min

Functional
Skills

Designing AI Agent Skills with Functional Thinking
Single Responsibility · Composable · Side-Effect Free

@lyonFull Stack Engineer · ESDD · 2026

Hey everyone, I'm lyon. Today I want to talk about something I've been exploring over the last six months — how to use AI Agent Skills more efficiently.

This isn't your typical AI talk. I won't teach you prompt engineering, and I won't explain what MCP is. My angle is "design thinking" — specifically, how to apply functional programming principles to design and compose your skills.

Why this angle? Because I see most people using skills in a very reactive way: download a bunch, try them, they don't fit, try others, give up. The root cause isn't that there aren't enough skills — it's that we misunderstand what skills fundamentally are. They're not magic. They're just "structured prompts."

Today in 30 minutes, I'll start from two core functional principles — single responsibility and composition — and use real examples to show how this mindset produces skills that are dramatically more effective. I'll also share my daily workflow, so you can take something practical home.

Let's go.

// opening · the problem

Sound familiar?

🔍 Can't find the right skill

Too many skills, docs are too long to read. The one you find needs tweaking before it works.

✍️ Afraid to write your own

Skills feel complex and mysterious. But they're really just structured prompts.

🔧 Others' skills don't quite fit

Downloaded skills always miss something. In many cases, writing your own is faster.

💸 Trial-and-error is expensive

Each bad skill attempt = wasted tokens. Low quality → repeated tasks → wasted tokens.

Quick show of hands — how many of you use skills regularly? How many have written one?

OK. What I observe is that most people use skills, but very few write them. Why? I think there are four pain points.

First, there are too many skills. You open a skill repo and there are hundreds. Each one has long docs. Humans are lazy — we're not going to read through all of them.

Second, even when you find one, it might not work out of the box. You try it, it doesn't fit your use case, you spend more time adjusting it.

Third, and this is the one I think matters most — people mystify skills. They think writing a skill requires some special expertise. But a skill is just a prompt with structure. If you can write a prompt, you can write a skill.

Fourth, the trial-and-error cost is high. A poorly designed skill might contain hundreds of lines. Every time you use it, the AI has to read all of it. If the quality is low, you end up re-doing tasks — each redo is another round of token consumption. That's why skill quality is directly linked to token efficiency.

Today my answer focuses on pain points three and four — how to design skills that are pure, effective, and whose power multiplies when composed. The answer is functional thinking.

// part 01 · demystify

A skill is just a structured prompt.
That's it.

01

Reduces repetitive prompt engineering

Write once, use everywhere. Maintain in one place — every consumer benefits from updates.

02

Enables sharing and reuse

Encapsulate domain knowledge → others load it → works out of the box. No more everyone writing their own version.

03

Start from the simplest thing

A 20-line skill is still a skill. Solve your smallest pain point first, iterate from there.

Before diving into functional thinking, I need to do one thing — demystify skills.

What's in a skill file? A system prompt, some trigger conditions, maybe some constraint rules. Fundamentally, it's no different from the system prompt you write in Cursor every day. The only difference: a skill has a format specification — where to put it, what metadata to include, how it's triggered.

What does this "structure" give you? Three things.

First, it eliminates repetitive prompt engineering. You know that feeling — every new project, every new conversation, you copy-paste the same long system prompt. Skills fix that. Load once, maintain centrally, update everywhere.

Second, sharing and reuse. You wrote a skill for handling Bitbucket PRs — your teammate needs the same capability. They just load it. No need to write from scratch. This is huge for team efficiency, because prompt engineering is highly personal — everyone's output quality varies significantly.

Third, and most important — start from the simplest thing. Many people think a skill needs to cover a complete workflow to be valuable. Wrong. A skill that does just one thing well — like "fetch git diff from CLI" — is already powerful when used correctly. Don't let the mysterious impression intimidate you.

OK, demystification done. Now let's get to the core: how functional thinking applies to skill design.

// part 02 · functional thinking

Functional Thinking
→ Skill Design

🧩 Single Responsibility

A function does one thing, and does it well.

→ One skill covers one domain, and does it well.

A "do-everything" skill = hard to maintain, reuse, compose

🔗 Composition

Complex behavior emerges from composing simple functions.

→ Two simple skills composed = a more powerful skill

AI automatically infers which skills to load for a given task

"Write your skills like pure functions
— single responsibility, composable, side-effect free"

The two core principles of functional programming — I'm sure most of you are familiar with them. What surprised me is how few people apply them to skill design.

First: single responsibility. A function does one thing, and does it well. In the skill world, this means one skill covers one business domain. I've seen too many "mega-skills" — like one called "full-stack dev assistant" that crams frontend, backend, database, deployment, testing… all into one file. What happens? The AI has to read thousands of lines every time, and those instructions might even contradict each other. Maintenance is a nightmare.

Second: composition. In the functional world, complex behavior doesn't come from writing complex functions — it comes from composing simple ones. In the skill world, two sufficiently simple and pure skills compose into something more powerful. And here's what might be the most important insight today — the AI automatically infers which skills to load.

It sees "review this PR" in your task description and loads the code review skill. It sees "fetch from Bitbucket" and loads the Bitbucket CLI skill. This inference capability is enabled by your functional design — because each skill's responsibility boundary is clear enough for the AI to accurately judge "which one applies here."

Let me demonstrate with a real case study.

// part 02 · case study

Code Review Case:
Two Designs

❌ Non-Functional

One "mega" code review skill:

Fetch PR diff from Bitbucket
Parse diff files
Analyze against local codebase
Generate review comments
...all in one file

Switch to GitHub? Rewrite. Change review strategy? Rewrite.

✅ Functional

Split into three independent skills:

using-bitbucket-cli — fetch PR data
java-best-practices — review strategy (code conventions, tech stack, performance, security)
requesting-code-review — describe review flow (abstract away "where data comes from and how to review")

Switch to GitHub? Swap Bitbucket CLI for GitHub CLI. Switch to Python? Swap review strategy skill. Other skills: zero changes.

💡 AI inference is the key — it sees "review this Java PR" and automatically loads using-bitbucket-cli + java-best-practices + requesting-code-review

OK, let me validate everything I just said with a real example. This is a code review scenario I actually use.

On the left — the non-functional design — that was my first approach. I wrote one giant skill that covered everything from "how to fetch a PR from Bitbucket" to "how to parse diffs" to "how to generate review comments," all in one file. Then what happened?

A month later I needed to review a GitHub repo. The skill was useless — the "fetch PR" part was hardcoded for Bitbucket's API. I had to either rewrite the whole skill or create a new GitHub version. Both meant tons of duplicated effort.

On the right is the refactored version. I split it into three skills: one handles "fetching external data" (Bitbucket CLI), one handles "review strategy" (java-best-practices), and a third one handles "the review process" (requesting-code-review).

Why the third one? Because reviewing code isn't just about checking syntax — you need a strategy. For Java, that might mean checking code conventions, tech stack constraints, performance patterns, and security concerns. The review flow skill is generic — it describes how to review. But java-best-practices describes what to look for. Two different responsibilities.

How does the AI know to load all three? Through inference. The AI sees your task description mentions Java review and PR, and automatically loads using-bitbucket-cli for the data, java-best-practices for the review strategy, and requesting-code-review for the flow.

The result? Flexibility. When the project migrates to GitHub, I just swap using-bitbucket-cli for using-gh-cli. When reviewing a Python project, I swap java-best-practices for a Python review strategy skill. The core review flow skill never changes. This flexibility isn't something you design extra — it emerges from decomposition. Single responsibility naturally gives you replaceability.

That's the core message: skill design isn't about making the most "capable" skill — it's about making the most "decomposable" one. Because pure skills compose into real power.

// part 03 · daily skills · token & coding

Token Efficiency & Coding Skills

⚡ Token Efficiency

caveman — Cuts ~75% of output tokens while keeping full technical accuracy. My default for every conversation.

🛠️ Coding

brainstorming — clarify requirements
writing-plans — implementation plans
test-driven-development — TDD
subagent-driven-development — parallel agents
requesting-code-review — code review
systematic-debugging — debug

✨ Refactoring

simplify — Refactor recently written code for clarity and consistency without changing functionality.

clonedeps — inspect dependency source code locally.

Now let me share something practical — the skills I use every day, organized by category.

First, Token Efficiency. This one's simple but powerful — caveman compresses output by about 75% while keeping full technical accuracy. It's my default — I turn it on at the start of every conversation. If you take nothing else from today, try this one tomorrow.

Second, Coding. This is where I spend most of my time. I use the Superpowers skill pack, which gives me a composable development methodology. Each skill does one thing — brainstorming for clarifying requirements, writing-plans for planning, test-driven-development for TDD, subagent-driven-development for running parallel agents, requesting-code-review for reviews, and systematic-debugging for debugging.

Two extras: simplify for refactoring code for clarity after writing it, and clonedeps for pulling dependency source code locally so you can inspect library internals.

Notice the pattern — each skill handles one phase of the development cycle. You load only what you need, when you need it.

// part 03 · daily skills · context & harness

Context & Harness

Give your agent the ability to pull context from internal systems — the more declarative, the higher the ceiling.

🔌 Source Control

using-bitbucket-cli

using-gh-cli

One CLI per platform. Composable.

📋 PM & Communication

using-jira-cli

using-confluence-cli

using-mst-cli

Pull tickets, docs & messages as context.

🏗️ Harness

creating-agents-md

Generate AGENTS.md files that follow best practices. Make your project AI-ready in one skill.

Next category — Context and Harness. This is about giving your agent the ability to pull information from your internal systems.

The context skills are all structured the same way — one CLI wrapper per system. Bitbucket, GitHub, Jira, Confluence, Microsoft Teams — each one is a standalone skill that knows how to talk to exactly one system. This is single responsibility in action.

Why does this matter? Because when a task says "review the PR from this Jira ticket," the AI can automatically infer it needs using-jira-cli to get ticket context and using-bitbucket-cli to get the code. You didn't hardcode that combination — it emerges from each skill's clear responsibility boundary.

And this is where the declarative principle kicks in — the more declarative your integration skills are, the higher the ceiling. Describe what you need, not how to get it. Let the AI figure out the "how."

Under Harness, creating-agents-md is a single-purpose skill that generates AGENTS.md files — making projects AI-ready. One skill, one job.

// part 03 · daily skills · knowledge

Knowledge Base & Memory

🔬 Deep Understanding

understand-anything

Generate knowledge graphs from codebases & docs. Make sense of complex domains.

📦 Project Memory

using-memvid-cli

Per-project compressed memory. Project-specific context on demand.

🌐 Cross-Domain RAG

using-light-rag

Cross-project, cross-domain knowledge retrieval. Recall how similar problems were solved elsewhere.

Three layers: deep understanding → project memory → cross-domain retrieval

Next — Knowledge Base and Memory. This is where skills go beyond just "doing tasks" and start building institutional memory.

Three layers here. First, understand-anything — this generates knowledge graphs from codebases and documents. It's how I make sense of a new project or a complex domain. The output is an interactive graph, not just text.

Second, using-memvid-cli — per-project knowledge management. Once I understand a project, I store that understanding as a compressed memory that the agent can query later. Think of it as "project-specific context on demand."

Third, using-light-rag — this goes beyond a single project. It manages knowledge across projects and domains. When I need to recall how a similar problem was solved in another codebase, this is where I look.

Notice the layered architecture — deep understanding feeds project memory, which feeds cross-domain retrieval. Each layer is a separate skill with a clear boundary. You can use them independently or compose them.

// part 03 · daily skills · authoring

Authoring & Skill Creation

📄 Documents

Kami — Typeset professional documents (reports, whitepapers, resumes)
html-ppt — Generate HTML slide decks (like this one!)

🛠️ Skill Creation

skill-creator — Create and optimize new skills
reviewing-skill — Review and validate skills

Meta-skills: skills that create and validate other skills. The Ouroboros of skill engineering.

Last category — Authoring. These are skills that produce outputs, not just process inputs.

Kami generates typeset professional documents — reports, whitepapers, one-pagers. html-ppt generates slide decks — in fact, this very deck was created using html-ppt. So you're looking at the output of the thing I'm describing. Very meta.

Then there are the meta-skills — skill-creator for creating new skills, and reviewing-skill for validating them. These are skills that operate on skills themselves. The Ouroboros of skill engineering.

The important thing here is that authoring skills follow the same single-responsibility principle. Kami does documents, html-ppt does slides, skill-creator does skills. They don't overlap. They compose when you need a pipeline — like "research a topic → generate a report → create a slide deck."

// part 03 · composable workflows

Composable Workflows

A Standard superpowers brainstorming → writing-plans → subagent-driven-dev → requesting-code-review → simplify

B Bug fix from Jira using-jira-cli → using-memvid-cli → tdd → requesting-code-review → simplify

C PR review on GitHub using-gh-cli + requesting-code-review

D Feature from Confluence using-confluence-cli → using-light-rag → brainstorming → writing-plans → subagent-driven-dev → code-review → simplify

E Tech research + doc brainstorming → understand-anything → Kami

F Skill creation skill-creator + reviewing-skill

G Project AI adaption creating-agents-md

Here's where composition really shines. These are the actual workflows I use every day — each one is just a sequence of simple, single-responsibility skills.

Workflow A is the standard superpowers flow for feature development. Brainstorm to clarify, plan to decompose, execute with parallel agents, review, then simplify.

Workflow B is my bug-fix flow. Pull context from Jira, recall project knowledge from memvid, write tests first with TDD, review, simplify.

Workflow C is the simplest — just two skills composed. Fetch from GitHub, then review. That's it. Two skills, one job.

Workflow D is the most complex — a feature request that starts from Confluence docs, enriches with cross-domain knowledge from LightRAG, then goes through the full development cycle.

Workflow E is research-oriented — brainstorm a question, understand it deeply with knowledge graphs, then generate a polished document with Kami.

And Workflow F is meta — creating skills with skills.

Workflow G is about project AI adaption — using creating-agents-md to generate an AGENTS.md file that makes any project immediately AI-ready. One skill, one job: bridge the gap between your codebase and your AI agent.

Notice something: every workflow is just a different combination of the same small set of skills. The skills don't change — the composition changes. That's the power of functional design.

// closing

One takeaway

"Use your skills like
pure functions"

fn single()

Single Responsibility

compose(a, b)

Composable

pure(fn)

Side-Effect Free

Back to the original question: skills aren't mysterious. Start simple, decompose with functional thinking, compose for power.

If you remember only one thing today, it's this — "write your skills like pure functions."

This has three layers. First, single responsibility — one skill does one thing, covers one domain, does it well. No "do-everything" skills.

Second, composable — two simple skills composed together, the power isn't additive, it's multiplicative. Because the AI automatically infers which skills to load, you don't need to manually orchestrate.

Third, side-effect free — this is also important in functional thinking. A good skill shouldn't depend on external state or modify the global environment. It should be self-contained, predictable, and reusable.

Going back to the original frustration — too many skills, can't find the right one, afraid to write your own. What I want you to take away is: skills aren't mysterious, they're just structured prompts. Start from your smallest pain point, write a skill that does one thing well, then compose it, iterate it. Functional thinking will help you write it right.

Thanks for listening. Let's move to Q&A.

// bonus tips

Three more tips

🧠 Actively manage context

Don't wait for the AI Agent to manage it for you.

You know better which information is critical and which can be discarded. Proactively compress, trim, curate.

🦾 AI is a lever

Not a brain replacement.

AI should help you think better — gather info, compare options, execute. But thinking itself? Always your job.

💰 Right model, right task

Don't nuke every task with the most expensive model.

~80% of tasks don't need Opus + thinking. Defaulting to max = massive budget waste.

Three bonus tips before I wrap up. The first two I've mentioned — actively manage your context, and remember that AI is a lever for your thinking, not a replacement for it.

The third one is about model selection. I see a common pattern: people always pick the most advanced model — like Opus — and enable extended thinking for every single task. That's a huge waste of budget.

Think about it with the 80/20 rule. About 80% of your daily tasks don't require the most expensive model. Writing a commit message, running a simple refactor, generating boilerplate — a faster, cheaper model handles these just fine. Reserve the heavy artillery — the Opus-level models with extended thinking — for the 20% of tasks that actually need deep reasoning: architectural decisions, complex debugging, nuanced code reviews.

This is directly related to token efficiency. The most expensive token is the one you didn't need to spend. Matching model to task complexity is one of the easiest ways to cut your AI budget without sacrificing quality.

OK, last slide.

Q & A